Skip to main content
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

SurfaceWhenWhat runsSafe auto-fixBlocks
CommitEvery git commit.githooks/pre-commit -> tests/unit/script-docs.test.js --staged --write --stage --autofillPlaceholder header injection for newly added governed scripts, plus script index refreshYes
Pull requestEvery pull request to main or docs-v2.github/workflows/test-suite.yml -> tests/run-pr-checks.jsNoneYes
Scheduled repairWeekly on Monday at 05:00 UTC.github/workflows/repair-governance.yml -> tools/scripts/orchestrators/repair-governance.js in fix modeSafe governance repairs, report refresh, optional repair PR creationNo
ManualAny timeWorkflow dispatch for repair-governance.yml, npm --prefix tools run audit:scripts, or npm --prefix tools run repair:governanceDepends on command modeNo
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 tools/scripts/validators/governance/audit-script-inventory.js --dry-run
node tools/scripts/validators/governance/audit-script-inventory.js --fix
node tools/scripts/validators/governance/audit-script-inventory.js --verbose

npm --prefix tools run repair:governance
node tools/scripts/orchestrators/repair-governance.js --dry-run
node tools/scripts/orchestrators/repair-governance.js --report-only
node tools/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

  1. Create the script under a governed root such as tools/scripts/, tests/, .githooks/, or tasks/scripts/.
  2. Add the framework header fields: @script, @category, @purpose, @scope, @owner, @needs, @purpose-statement, @pipeline, and @usage.
  3. Run node tests/unit/script-docs.test.js --write --rebuild-indexes.
  4. 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.
  5. Open the pull request and let tests/run-pr-checks.js verify the changed governance surface.
  6. 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.
FieldEnforced todayAuto-derivedNotes
@scriptYesYesDefaults to the filename when missing.
@categoryYesNoMust match the governed enum. Never guessed.
@purposeYesNoMust match the governed enum. Never guessed.
@scopeYesNoMissing or invalid scope remains a human fix.
@ownerYesYesGovernance repair backfills docs.
@needsYesNoRequirement IDs are mandatory in the current framework validator, but repair will not invent them.
@purpose-statementYesNoRequired by the framework validator. Repair will not generate free text.
@pipelineYesSometimesSafe correction is allowed only when detected triggers are preserved.
@usagePartlyYesGovernance 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.
Last modified on March 16, 2026