Script Governance

This page is the canonical governance reference for all scripts in this repository. It defines the three-tier taxonomy, JSDoc header standard, enforcement tiers, and the process for adding a new script. The full script inventory lives in the auto-generated catalog: Scripts Catalog.

Taxonomy — the three-tier model

Every script in operations/scripts/ is placed at a path following this structure:

operations/scripts/<type>/<concern>/<niche>/script-name.js

This hierarchy is enforced — a script placed in the wrong folder will fail classification validation.

Layer 1 — Type

What the script does.

Type folder	What it does	`@type` value	Typical `@mode`
`audits/`	Read-only scan, measure, report. Never modifies files. Produces reports and metrics.	`audit`	`read-only`
`generators/`	Produces new files from source-of-truth data. Creates artefacts (JSON, MDX, indexes, registries).	`generator`	`write`, `generate`
`validators/`	Enforces rules with a pass/fail gate. Exits 0 (pass) or non-zero (fail).	`validator`	`read-only`
`remediators/`	Bulk-fixes existing files in place. Modifies source content to bring it into compliance.	`remediator`	`edit`
`dispatch/`	Dispatches work to other scripts or agents. Genuine orchestrators that spawn child processes.	`dispatch`	`execute`
`automations/`	End-to-end automated workflows — translation, data fetching, transforms.	`automation`	`write`, `execute`

Key distinctions:

If the script only reads → audit or validator (validator exits non-zero on failure; audit just reports)
If the script only creates new files → generator
If the script edits existing files → remediator
If the script runs other scripts → dispatch
A script that does NOT spawn other scripts is NOT a dispatch

Layer 2 — Concern

What domain the script operates on. The same four concerns appear under every type folder.

Concern	What it covers
`content/`	Docs pages, copy, SEO, veracity, quality, reference, reconciliation
`components/`	Component library, registry, CSS, naming, documentation
`governance/`	Scripts about scripts, repo structure, agent docs, manifests, catalogs
`ai/`	LLM files, agent packaging, skills sync, Codex operations

Layer 3 — Niche

The specific sub-concern within the domain. Examples: quality, veracity, structure, copy, grammar, catalogs, compliance, pr, codex, repair, style, scaffold, llm. Full niche reference: see script-framework.md section 2.

Classification decision tree

1. Does the script SPAWN other scripts or coordinate a multi-script pipeline?
   YES → dispatch/
   NO  → continue

2. Does the script only READ files and produce reports/metrics (no file modifications)?
   YES → Does it enforce a pass/fail gate (exit 0/1)?
         YES → validators/
         NO  → audits/
   NO  → continue

3. Does the script CREATE new files from source-of-truth data?
   YES → generators/
   NO  → continue

4. Does the script MODIFY existing files in place to fix/repair them?
   YES → remediators/
   NO  → continue

5. Is the script an end-to-end automated workflow (translation, data fetching, transforms)?
   YES → automations/

For concern:

- Operates on docs pages, MDX, copy, SEO, frontmatter? → content/
- Operates on components, registry, CSS, naming?        → components/
- Operates on scripts, repo structure, agent docs?      → governance/
- Operates on LLM files, agent packs, skills, Codex?   → ai/

JSDoc Header Standard

Every script MUST include a JSDoc header block as the first block comment in the file (or hash-comment equivalent for .sh and .py files). The pre-commit hook and CI validate header presence and tag format.

Required tags (enforced by `--strict`)

#	Tag	Required	What it captures	Allowed values / format
1	`@script`	Yes	Script identity	Filename without extension. Example: `lint-copy`
2	`@type`	Yes	Layer 1 — what the script does	`audit` \| `generator` \| `validator` \| `remediator` \| `dispatch` \| `automation`
3	`@concern`	Yes	Layer 2 — domain	`content` \| `components` \| `governance` \| `ai`
4	`@niche`	Yes	Layer 3 — specific sub-concern	See niche reference in section 2 above
5	`@purpose`	Yes	Functional category	Namespaced string: `qa:content-quality`, `governance:repo-health`, `tooling:dev-tools`, etc.
6	`@description`	Yes	One-line human-readable description	Plain English. No line breaks.
7	`@mode`	Yes	How the script affects the system	`read-only` \| `write` \| `edit` \| `generate` \| `execute`
8	`@pipeline`	Yes	Flow declaration	Arrow notation: `trigger → inputs → outputs`
9	`@scope`	Yes	What files/directories it operates on	Comma-separated paths, patterns, or keywords
10	`@usage`	Yes	CLI invocation example	Full command with flags
11	`@policy`	If applicable	Governance traceability	Requirement IDs: `E-R1, R-R11`

The required minimum validated by --strict is tags 1–10. @policy is expected but not blocked on by default.

`@mode` values

Value	Meaning
`read-only`	Inspects and reports only — no file changes. Used by audits and validators.
`write`	Creates new files. Used by generators and automations.
`edit`	Modifies existing files in place. Used by remediators.
`generate`	Produces artefacts (JSON, MDX, indexes, registries). Used by generators.
`execute`	Runs external commands, dispatches work to other scripts or agents. Used by dispatch.

`@pipeline` format

Single-line flow declaration using arrow notation:

@pipeline   trigger → inputs → outputs [→ dependants]

Examples:

@pipeline   pre-commit → staged .mdx files → stdout:report
@pipeline   manual → docs.json, v2 frontmatter → docs-index.json → scripts-catalog
@pipeline   cron:weekly → full v2 tree → governance-repair PR
@pipeline   pr-workflow → changed .mdx files → exit-code, stdout:violations

Example header — JavaScript

/**
 * @script      lint-copy
 * @type        validator
 * @concern     content
 * @niche       copy
 * @purpose     qa:content-quality
 * @description Enforce banned word and phrase rules on MDX content files.
 * @mode        read-only
 * @pipeline    pr-workflow → staged .mdx files → exit-code, stdout:violations
 * @scope       staged, changed, v2-content, single-file
 * @usage       node operations/scripts/validators/content/copy/lint-copy.js [file or glob] [flags]
 * @policy      E-R1, R-R11
 */

Example header — shell / Python (hash-comment style)

# @script            pre-commit
# @type              dispatch
# @concern           governance
# @niche             pipelines
# @purpose           infrastructure:pipeline-orchestration
# @description       Pre-commit hook — hard gates only.
# @mode              execute
# @pipeline          P1 → git index → exit-code
# @scope             .githooks
# @usage             bash .githooks/pre-commit [flags]
# @policy            R-R29

Removed tags — MUST NOT appear

These tags were used in earlier versions and must not appear in new scripts:

Removed tag	Replaced by
`@owner`	Removed — ownerless governance model
`@category`	`@type`
`@dualmode`	Not replaced — scripts should have one purpose
`@purpose-statement`	`@description`
`@needs`	`@policy`
`@domain`	`@concern`

Enforcement Tiers

Scripts are assigned to one of three tiers. Tier assignment belongs in @pipeline.

Tier	Gate type	Runs where	What it means
Hard gate	Blocks commit or merge	Pre-commit hook + required GitHub Actions status check	Must pass. Violations block the commit.
Soft gate	Warns in PR, does not block merge	GitHub Actions check (non-required)	Violations surface in PR UI but do not prevent merge.
Self-heal	No gate — auto-fixes on schedule	Cron workflow with auto-PR	Runs periodically and opens a PR with corrections.

File Structure Standard

Every script MUST follow this section order:

Shebang line          #!/usr/bin/env node  (or bash, python3)
JSDoc header block    All 11 tags in declared order
'use strict'          JS only — recommended
Requires / imports    const fs = require('fs'); etc.
Constants / config    REPO_ROOT, paths, thresholds — ALL in first ~30 lines after imports
Helper functions      Small, focused utilities
Main function         Primary logic
Exports / execution   module.exports or main() call

REPO_ROOT pattern

// Correct — repo root from process.cwd()
const REPO_ROOT = process.cwd();

// Wrong — fragile, breaks if script is moved
const REPO_ROOT = path.resolve(__dirname, '../../../../..');

__dirname-relative paths are acceptable only for reaching sibling files or shared libraries within the scripts tree (e.g., require('../../../../lib/docs-index-utils')).

How to Write a New Script

Classify it first

Use the decision tree above to determine type, concern, and niche. Place the file at operations/scripts/<type>/<concern>/<niche>/<script-name>.js.

Write the JSDoc header

Copy the example header above. Fill all 11 tags. Do not leave placeholder values. Run node operations/scripts/validators/governance/compliance/review-governance-repair-checklist.js --staged to validate.

Follow the file structure

Shebang → JSDoc header → 'use strict' → imports → constants/config at top → helpers → main() → export/execute.

Use process.cwd() for REPO_ROOT

Never traverse up with __dirname to reach the repo root. Use process.cwd() or a shared getRepoRoot() utility.

Support --dry-run if the script writes files

Any script that writes or modifies files SHOULD support --dry-run to show what would change without making changes.

Assign an enforcement tier

Set @pipeline to indicate where the script runs. Hard gates go in pre-commit or required CI; soft gates in non-required CI; self-heals in cron.

Add to the registry

Run node operations/scripts/generators/governance/catalogs/generate-script-registry.js to update tools/config/registry/script-registry.json. The catalog is regenerated automatically from the registry.

Source of Truth

Resource	Where
This governance spec	`docs-guide/policies/script-governance.mdx` (you are here)
Full technical spec	`workspace/plan/active/SCRIPT-GOVERNANCE/script-framework.md`
Script registry (derived index)	`tools/config/registry/script-registry.json`
Script catalog (auto-generated)	docs-guide/catalog/scripts-catalog
Registry generator	`operations/scripts/generators/governance/catalogs/generate-script-registry.js`

About

RFP

Docs Guide

Generated Reports

Script Governance

Script Governance

Taxonomy — the three-tier model

Layer 1 — Type

Layer 2 — Concern

Layer 3 — Niche

Classification decision tree

JSDoc Header Standard

Required tags (enforced by `--strict`)

`@mode` values

`@pipeline` format

Example header — JavaScript

Example header — shell / Python (hash-comment style)

Removed tags — MUST NOT appear

Enforcement Tiers

File Structure Standard

REPO_ROOT pattern

How to Write a New Script

Source of Truth

About

RFP

Docs Guide

Generated Reports

​Script Governance

​Taxonomy — the three-tier model

​Layer 1 — Type

​Layer 2 — Concern

​Layer 3 — Niche

​Classification decision tree

​JSDoc Header Standard

​Required tags (enforced by --strict)

​@mode values

​@pipeline format

​Example header — JavaScript

​Example header — shell / Python (hash-comment style)

​Removed tags — MUST NOT appear

​Enforcement Tiers

​File Structure Standard

​REPO_ROOT pattern

​How to Write a New Script

​Source of Truth

Script Governance

Taxonomy — the three-tier model

Layer 1 — Type

Layer 2 — Concern

Layer 3 — Niche

Classification decision tree

JSDoc Header Standard

Required tags (enforced by `--strict`)

`@mode` values

`@pipeline` format

Example header — JavaScript

Example header — shell / Python (hash-comment style)

Removed tags — MUST NOT appear

Enforcement Tiers

File Structure Standard

REPO_ROOT pattern

How to Write a New Script

Source of Truth