Governance Pipeline

This repository currently governs about 214 scripts, hooks, and support modules through a shared 9-field metadata model. The governance pipeline checks that metadata at commit time, in pull request CI, on the weekly repair schedule, and during manual maintainer runs. Safe, derivable drift is repaired automatically where the source of truth is clear, while judgement fields and risky wiring decisions are left for a human.

Trigger chain

Surface	When	What runs	Safe auto-fix	Blocks
Commit	Every `git commit`	`.githooks/pre-commit` -> `tests/unit/script-docs.test.js --staged --write --stage --autofill`	Placeholder header injection for newly added governed scripts, plus script index refresh	Yes
Pull request	Every pull request to `main` or `docs-v2`	`.github/workflows/test-suite.yml` -> `tests/run-pr-checks.js`	None	Yes
Scheduled repair	Weekly on Monday at 05:00 UTC	`.github/workflows/repair-governance.yml` -> `operations/scripts/orchestrators/repair-governance.js` in fix mode	Safe governance repairs, report refresh, optional repair PR creation	No
Manual	Any time	Workflow dispatch for `repair-governance.yml`, `npm --prefix tools run audit:scripts`, or `npm --prefix tools run repair:governance`	Depends on command mode	No

There is no dedicated merge or push stage governance-sync workflow today. Governance repair happens on the Monday schedule or when a maintainer runs it manually.

Auto-fixed vs needs human

Auto-repaired

Phantom JSON entries are removed from tasks/reports/script-classifications.json.
Missing JSON rows can be added when a governed script already has valid category, purpose, and scope metadata.
Existing JSON rows can be updated from valid header metadata when missing fields are safely recoverable.
@owner is backfilled to docs.
@script is derived from the filename when it is missing.
@usage is derived from the file path and command type when it is missing.
@pipeline is corrected only when the proposed value is a safe superset of detected automation triggers.
Script indexes and aggregate indexes are regenerated when governance changes affect them.

Needs human

Missing or invalid @category
Missing or invalid @purpose
Missing or invalid @scope
Missing @needs
Missing @purpose-statement
Unsafe pipeline mismatches, including claims that would hide detected triggers
Missing classification rows that cannot be created from already valid metadata
Wiring decisions such as whether a script should stay manual or join a commit, PR, or scheduled path

Commands

npm --prefix tools run audit:scripts
node operations/scripts/validators/governance/audit-script-inventory.js --dry-run
node operations/scripts/validators/governance/audit-script-inventory.js --fix
node operations/scripts/validators/governance/audit-script-inventory.js --verbose

npm --prefix tools run repair:governance
node operations/scripts/orchestrators/repair-governance.js --dry-run
node operations/scripts/orchestrators/repair-governance.js --report-only
node operations/scripts/orchestrators/repair-governance.js --auto-commit

Use the audit command family when you want a detailed inventory or a targeted repair preview. Use the repair Orchestrator when you want the full safe-repair pipeline, including verification and repair reports.

Adding a new script

Create the script under a governed root such as operations/scripts/, tests/, .githooks/, or tasks/scripts/.
Add the framework header fields: @script, @category, @purpose, @scope, @owner, @needs, @purpose-statement, @pipeline, and @usage.
Run node tests/unit/script-docs.test.js --write --rebuild-indexes.
Commit the change. The pre-commit hook can auto-fill a missing placeholder template for newly added scripts, but it does not invent judgement fields for you.
Open the pull request and let tests/run-pr-checks.js verify the changed governance surface.
Use the weekly repair workflow or a manual repair-governance run to sync safe JSON and header drift after the script lands.

The 9-field schema

tests/unit/script-docs.test.js currently enforces the framework header set including @needs, @purpose-statement, and @pipeline. Governance repair extends that model by deriving @usage and other safe defaults where possible, but it still treats judgement fields and risky pipeline changes as human work.

Field	Enforced today	Auto-derived	Notes
`@script`	Yes	Yes	Defaults to the filename when missing.
`@category`	Yes	No	Must match the governed enum. Never guessed.
`@purpose`	Yes	No	Must match the governed enum. Never guessed.
`@scope`	Yes	No	Missing or invalid scope remains a human fix.
`@owner`	Yes	Yes	Governance repair backfills `docs`.
`@needs`	Yes	No	Requirement IDs are mandatory in the current framework validator, but repair will not invent them.
`@purpose-statement`	Yes	No	Required by the framework validator. Repair will not generate free text.
`@pipeline`	Yes	Sometimes	Safe correction is allowed only when detected triggers are preserved.
`@usage`	Partly	Yes	Governance repair derives it from file type and path. `script-docs.test.js` expects a non-placeholder value when the tag is present and uses it in generated indexes.

About

RFP

Generated Reports

Trigger chain

Auto-fixed vs needs human

Commands

Adding a new script

The 9-field schema

​Trigger chain

​Auto-fixed vs needs human

​Commands

​Adding a new script

​The 9-field schema

Trigger chain

Auto-fixed vs needs human

Commands

Adding a new script

The 9-field schema