@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/schemas/reviewer-output.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/reviewer-output.schema.json",
+  "version": "1.0.0",
+  "title": "Multi-Agent Pipeline — Phase 4 reviewer output",
+  "description": "Contract for a single code-reviewer subagent's JSON output in Phase 4 Step 2. Reviewer set is CLI-aware: Claude Code dispatches 2 parallel reviewers (Opus, Sonnet); Copilot CLI dispatches 3 (GPT-5.4, Opus, Sonnet). Every reviewer must return an object matching this shape before Opus triage merges them.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["findings", "approved"],
+  "properties": {
+    "findings": {
+      "type": "array",
+      "description": "Raw findings. May be empty. Duplicates and out-of-scope items are acceptable — Opus triage will deduplicate and filter.",
+      "items": { "$ref": "#/$defs/finding" }
+    },
+    "approved": {
+      "type": "boolean",
+      "description": "Reviewer's own verdict. MUST be false if any finding has severity=blocking, true otherwise. Triage may override."
+    }
+  },
+  "$defs": {
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["severity", "file", "line", "issue", "fix"],
+      "properties": {
+        "severity": {
+          "type": "string",
+          "enum": ["blocking", "important", "suggestion"],
+          "description": "blocking=must fix (bugs/security/data-loss/arch violations), important=should fix (quality/perf), suggestion=nice-to-have."
+        },
+        "file": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Path relative to repo root. Reviewers must not invent non-existent files."
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Line number. 0 = whole-file finding."
+        },
+        "issue": {
+          "type": "string",
+          "minLength": 4,
+          "description": "What is wrong. One short sentence."
+        },
+        "fix": {
+          "type": "string",
+          "minLength": 4,
+          "description": "Concrete remediation. Not 'refactor this' — actionable guidance."
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/test-gap.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/test-gap.schema.json",
+  "version": "1.0.0",
+  "title": "Multi-Agent Pipeline — Phase 5 test gap report",
+  "description": "Output of test-gap-scan.mjs. Lists symbols added/changed in the diff that have no paired test file or no matching test method. Advisory in default mode; opt-in blocking via prefs.testGap.blockingThreshold.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "stack", "totals", "gaps"],
+  "properties": {
+    "schemaVersion": { "type": "string", "const": "1.0.0" },
+    "stack": {
+      "type": "string",
+      "enum": ["ios", "android", "python", "node", "unknown"]
+    },
+    "totals": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sourcesScanned", "testsScanned", "gapCount", "gapBySeverity"],
+      "properties": {
+        "sourcesScanned": { "type": "integer", "minimum": 0 },
+        "testsScanned":   { "type": "integer", "minimum": 0 },
+        "gapCount":       { "type": "integer", "minimum": 0 },
+        "gapBySeverity": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "blocking":   { "type": "integer", "minimum": 0 },
+            "important":  { "type": "integer", "minimum": 0 },
+            "suggestion": { "type": "integer", "minimum": 0 }
+          },
+          "required": ["blocking", "important", "suggestion"]
+        }
+      }
+    },
+    "gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["sourcePath", "symbol", "kind", "severity", "expectedTestPaths", "hint"],
+        "properties": {
+          "sourcePath": { "type": "string", "minLength": 1 },
+          "symbol":     { "type": "string", "minLength": 1 },
+          "kind": {
+            "type": "string",
+            "description": "Pattern id from the rules file (e.g. public_func, composable_fun, named_export)."
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["blocking", "important", "suggestion"]
+          },
+          "expectedTestPaths": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string" },
+            "description": "Likely paths the missing test should live at, in priority order."
+          },
+          "hint": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/token-budget.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/token-budget.json",
+  "description": "Per-phase token budget for lazy-loaded pipeline docs. Enforced by smoke-token-budget.sh.",
+  "phases": {
+    "phase-0-init":      { "max_tokens": 8900, "warn_tokens": 7850 },
+    "phase-1-analysis":  { "max_tokens": 2550, "warn_tokens": 2250 },
+    "phase-2-planning":  { "max_tokens": 4200, "warn_tokens": 3700 },
+    "phase-3-dev":       { "max_tokens": 4950, "warn_tokens": 4350 },
+    "phase-4-review":    { "max_tokens": 6900, "warn_tokens": 6050 },
+    "phase-5-test":      { "max_tokens": 2300, "warn_tokens": 2000 },
+    "phase-6-commit":    { "max_tokens": 5550, "warn_tokens": 4900 },
+    "phase-7-report":    { "max_tokens": 4400, "warn_tokens": 3850 }
+  },
+  "total_max_tokens": 39750,
+  "note": "Token estimate = ceil(chars / 4). Per-phase budget rule: warn = current+10% (rounded to nearest 50), max = current+25%. Gives ~6 edit cycles of headroom before warn trips — intentionally quiet under normal maintenance, loud when a phase grows unusually. Only the active phase is loaded (lazy)."
+}

package/pipeline/schemas/triage-corpus.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/triage-corpus.schema.json",
+  "version": "1.0.0",
+  "title": "Multi-Agent Pipeline — Triage corpus row",
+  "description": "Shape of one row in the JSONL triage corpus at $HOME/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl. Append-only. Each row records a single accepted/deferred/rejected finding from a past triage run plus minimal task context. Used by Phase 1 (similar-task enrichment) and Phase 4 (prior-art lookup).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["v", "ts", "task_id", "classification", "severity", "file", "issue"],
+  "properties": {
+    "v": { "type": "string", "const": "1.0.0" },
+    "ts": { "type": "string", "format": "date-time" },
+    "task_id": { "type": "string", "minLength": 1 },
+    "task_title": { "type": ["string", "null"] },
+    "stack": { "type": ["string", "null"] },
+    "classification": {
+      "type": "string",
+      "enum": ["accepted", "deferred", "rejected"]
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["blocking", "important", "suggestion"]
+    },
+    "file": { "type": "string" },
+    "line": { "type": ["integer", "null"] },
+    "issue": { "type": "string", "minLength": 1 },
+    "fix":  { "type": ["string", "null"] },
+    "reason": { "type": ["string", "null"] },
+    "reviewer": { "type": ["string", "null"] }
+  }
+}

package/pipeline/schemas/triage-output.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/triage-output.schema.json",
+  "version": "3.0.0",
+  "title": "Multi-Agent Pipeline — Phase 4 triage output",
+  "description": "Contract for the Opus triage agent's JSON output in Phase 4 Step 3. Triage consumes merged reviewer findings and splits them into accepted/deferred/rejected. Only `accepted` blocking/important items trigger Phase 3 rework.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["accepted", "deferred", "rejected", "approved"],
+  "properties": {
+    "accepted": {
+      "type": "array",
+      "description": "Findings that are real, in-scope, and must be actioned in this iteration.",
+      "items": { "$ref": "#/$defs/acceptedFinding" }
+    },
+    "deferred": {
+      "type": "array",
+      "description": "Findings that are real but out of current task scope. Surfaced in Phase 7 report; not actioned.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["finding", "reason"],
+        "properties": {
+          "finding": { "$ref": "#/$defs/rawFinding" },
+          "reason": {
+            "type": "string",
+            "minLength": 4,
+            "description": "Why deferred — e.g. 'out of scope: touches payment module, task is auth-only'."
+          }
+        }
+      }
+    },
+    "rejected": {
+      "type": "array",
+      "description": "Findings that are false-positives, duplicates, style-only nitpicks, or already correct. Not actioned; kept for audit.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["finding", "reason"],
+        "properties": {
+          "finding": { "$ref": "#/$defs/rawFinding" },
+          "reason": {
+            "type": "string",
+            "minLength": 4,
+            "description": "Why rejected — e.g. 'false positive: the null check the reviewer wants already happens in the caller'."
+          }
+        }
+      }
+    },
+    "approved": {
+      "type": "boolean",
+      "description": "True if no accepted BLOCKING items remain. The pipeline uses this to gate Phase 5 / Phase 6 entry."
+    }
+  },
+  "if": {
+    "properties": {
+      "accepted": {
+        "contains": {
+          "type": "object",
+          "properties": { "severity": { "const": "blocking" } },
+          "required": ["severity"]
+        }
+      }
+    }
+  },
+  "then": {
+    "properties": { "approved": { "const": false } }
+  },
+  "$defs": {
+    "severity": {
+      "type": "string",
+      "enum": ["blocking", "important", "suggestion"]
+    },
+    "reviewer": {
+      "type": "string",
+      "enum": ["opus", "sonnet"],
+      "description": "Which reviewer produced the raw finding. Haiku was removed in v2.1.0."
+    },
+    "rawFinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["severity", "file", "line", "issue"],
+      "properties": {
+        "severity": { "$ref": "#/$defs/severity" },
+        "file": { "type": "string", "minLength": 1 },
+        "line": { "type": "integer", "minimum": 0 },
+        "issue": { "type": "string", "minLength": 4 },
+        "fix": { "type": "string" },
+        "reviewer": { "$ref": "#/$defs/reviewer" }
+      }
+    },
+    "acceptedFinding": {
+      "allOf": [
+        { "$ref": "#/$defs/rawFinding" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["severity", "file", "line", "issue", "reviewer", "fix"],
+          "properties": {
+            "severity": { "$ref": "#/$defs/severity" },
+            "file": { "type": "string", "minLength": 1 },
+            "line": { "type": "integer", "minimum": 0 },
+            "issue": { "type": "string", "minLength": 4 },
+            "reviewer": { "$ref": "#/$defs/reviewer" },
+            "fix": {
+              "type": "string",
+              "minLength": 4,
+              "description": "Concrete change the dev agent must make. Required for accepted items so Phase 3 re-entry has actionable direction."
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/pipeline/scripts/.last-figma-sync-plan.json

@@ -0,0 +1,23 @@
+{
+  "source": { "path": "/Users/M_ERDEN3/turkish-airlines-ios-figma", "branch": "develop", "commit": "6702673562d797e5bb77364922f211a4b5d5c0ae", "lastCommit": "cd0cde2f25abbc2524f3f20407d8c0d9ff6c2245" },
+  "summary": { "changedSkills": 12 },
+  "changes": [
+    { "upstream": "figma-cli-iterate", "local": "figma-cli-iterate", "tree": "figma-common", "renamed": false, "overlaySkip": false },
+    { "upstream": "figma-cli-lean-iterate", "local": "figma-cli-lean-iterate", "tree": "figma-common", "renamed": false, "overlaySkip": false },
+    { "upstream": "figma-form-integration", "local": "figma-form-integration", "tree": "figma-common", "renamed": false, "overlaySkip": false },
+    { "upstream": "figma-issue", "local": "figma-issue", "tree": "figma-common", "renamed": false, "overlaySkip": false },
+    { "upstream": "figma-iterate", "local": "figma-iterate", "tree": "figma-common", "renamed": false, "overlaySkip": false },
+    { "upstream": "figma-iteration-commit", "local": "figma-iteration-commit", "tree": "figma-common", "renamed": false, "overlaySkip": false },
+    { "upstream": "figma-to-swift-ui-implement", "local": "figma-component-implement", "tree": "figma-ios", "renamed": true, "overlaySkip": true },
+    { "upstream": "figma-to-swift-ui-start", "local": "figma-component-start", "tree": "figma-common", "renamed": true, "overlaySkip": false },
+    { "upstream": "figma-to-swiftui", "local": "figma-to-component", "tree": "figma-ios", "renamed": true, "overlaySkip": false },
+    { "upstream": "figma-ui-patterns", "local": "figma-ui-patterns", "tree": "figma-common", "renamed": false, "overlaySkip": false },
+    { "upstream": "performance-swiftui", "local": "performance-swiftui", "tree": "figma-common", "renamed": false, "overlaySkip": false },
+    { "upstream": "performance-tour", "local": "performance-tour", "tree": "figma-common", "renamed": false, "overlaySkip": false }
+  ],
+  "postActions": [
+    "run `npm run test:smoke` — all 28 suites must stay green",
+    "review figma-ios/REVIEW_CHECKLIST.md for skills still WIP",
+    "commit with \"chore(sync): upstream @ 6702673562d797e5bb77364922f211a4b5d5c0ae\""
+  ]
+}

package/pipeline/scripts/README-figma-smokes.md

@@ -0,0 +1,34 @@
+# Figma Smoke Suite Index
+
+v6.0.0 audit flagged "figma smoke consolidation (7 → 5 suites)" as a potential improvement. On closer inspection, the six figma-prefixed smoke scripts turn out to cover **distinct, non-overlapping contracts**. Merging them would produce a single giant harness that's harder to debug ("which sub-contract failed?") without meaningfully reducing assertion surface.
+
+Instead of a forced merge, v6.0.0 documents the full family here so a new maintainer can see at a glance what each file is for, what it enforces, and why none of them are redundant.
+
+| Script | Scope | Assertions | What it enforces |
+|---|---|---|---|
+| `smoke-figma-android-parity.sh` | Android platform skills | 32 | Android tree mirrors iOS for every platform-specific skill required by the orchestrator; Kotlin/Compose-specific details (Paparazzi / Roborazzi refs, file-name conventions) |
+| `smoke-figma-config-schema.sh` | `figma-project-config.schema.json` v2.0.0 | 18 | Schema shape + `figma-config-1.0.0-to-2.0.0.mjs` migration path; v2 envelope correctness |
+| `smoke-figma-cross-cli-inventory.sh` | Cross-CLI inventory parity | 39 | Every figma skill on Claude side also ships on Copilot side — source-tree parity (complements `smoke-cross-cli-behavior.sh` installed-tree check) |
+| `smoke-figma-dispatch.sh` | Phase 3 → figma-to-component dispatch | 12 | multi-agent Phase 3 delegates to the figma orchestrator (doesn't embed figma logic inline) — verifies the WS-4 contract |
+| `smoke-figma-skill-import.sh` | iOS import transform consistency | 19 | iOS figma-ios/ tree is well-formed; placeholder-map (`figma-placeholder-map.json`) was applied without unresolved tokens; frontmatter present on every SKILL.md |
+| `smoke-figma-sync.sh` | `sync-figma-source.sh` script contract | 15 | Sync script exists + executable, handles missing `figmaSource` gracefully, enforces the `prefs.global.figmaSource` shape |
+
+**Total: 6 suites, 135 assertions** (each group's `→ N.` header-pass count summed; individual assertion count is higher — each `→` group has multiple sub-asserts).
+
+## Why these stay separate
+
+Each script tests a different contract surface:
+
+- **Schema shape** (`config-schema`) vs **tree structure** (`skill-import`, `android-parity`) vs **orchestration wire-up** (`dispatch`, `sync`) vs **inventory parity** (`cross-cli-inventory`) — merging two of these would produce an assertion file that mixes concerns and forces a future maintainer to read twice as much to understand "why did this fail".
+- **iOS-only vs Android-only vs cross-platform** — splitting by platform keeps failure messages precise. A single combined parity smoke would need to name the platform on every assertion, doubling the log noise.
+- **Pre-deploy vs post-deploy** — `smoke-figma-cross-cli-inventory.sh` checks source tree (runs before `install.js`), `smoke-cross-cli-behavior.sh` checks installed tree (runs after). Merging would collapse the distinction and make the "did install.js ship the files correctly?" question harder to answer in isolation.
+
+## When a merge would make sense
+
+If the ratio of duplicated assertions between two files ever exceeds ~40%, revisit this decision. Measure: `grep -E '^echo "→'` both files and diff the assertion labels.
+
+## See also
+
+- `smoke-cross-cli-behavior.sh` — parent cross-CLI behavior smoke (installed-tree parity)
+- `smoke-commands-skills-parity.sh` — multi-agent command ↔ dash-form skill parity (not figma-specific)
+- `pipeline/commands/multi-agent/refs/cross-cli-contract.md` § 1.1 — source of truth for the figma inventory matrix

package/pipeline/scripts/README.md

@@ -0,0 +1,104 @@
+# Pipeline Scripts — Category Index
+
+The `pipeline/scripts/` directory holds 59 shell scripts + 12 Node.js `.mjs` scripts in a flat layout. v6.0.0 evaluated moving them into `smoke/`, `hooks/`, `runtime/` subdirs and decided against it: each path change would need to propagate through `package.json` globs, `install.js` deploy logic, npm scripts, sibling script calls, and CI workflow references — a 40+ file touch radius with high regression risk for minor polish value.
+
+Instead, this README is the category index. Use it to navigate.
+
+## Smoke scripts (42 files — `smoke-*.sh`)
+
+Validate contracts. Each emits `══ <name> smoke: N passed, M failed ══` on completion (the `smoke-personal-data.sh` + `smoke-token-budget.sh` suites use `PASS:` / `warnings:` variants). Run via `npm test` (chained) or individually.
+
+### Cross-CLI contract + parity
+- `smoke-cross-cli-behavior.sh` — parent parity smoke, agent/skill deployment on both sides
+- `smoke-commands-skills-parity.sh` — colon-form command ↔ dash-form skill directory parity (50 assertions)
+- `smoke-compliance-skills.sh` — v5.8.1+ store-compliance wiring contract (45 assertions)
+- `smoke-figma-cross-cli-inventory.sh` — figma skill cross-CLI source-tree parity (39 assertions)
+
+### Figma pipeline (see `pipeline/scripts/README-figma-smokes.md` for the full index)
+- `smoke-figma-android-parity.sh`, `smoke-figma-config-schema.sh`, `smoke-figma-dispatch.sh`, `smoke-figma-skill-import.sh`, `smoke-figma-sync.sh`
+
+### Phase contracts
+- `smoke-phase-0-multi-repo.sh` — Phase 0 multi-repo mode fetch + worktree atomicity
+- `smoke-phase-6-multi.sh` — Phase 6 multi-repo commit/PR cross-linking
+- `smoke-phase-banner.sh` + `smoke-phase-tracker.sh` — Phase UI output contracts
+- `smoke-phase4-triage.sh` — Phase 4 reviewer → triage flow
+
+### Schema + state
+- `smoke-schema-validation.sh` — all JSON schemas validate
+- `smoke-migrate-state.sh` — `migrate-state.mjs` runner behavior
+- `smoke-pref-migration.sh` — prefs 2.0.0 → 2.1.0 → 2.2.0 migration chain (22 assertions)
+- `smoke-write-state.sh` — atomic state writer concurrency
+
+### Quality + security
+- `smoke-personal-data.sh` — guards against corporate hostname / private Jira key / personal domain leaks (13 patterns; full catalog in the script itself)
+- `smoke-pat-audit.sh` — PAT lookup telemetry contract
+- `smoke-token-budget.sh` — per-phase token budget enforcement (9 phases)
+- `smoke-skill-scan.sh` — skill security scanner tiered pattern catalog
+
+### Command / Feature contracts
+- `smoke-channels-flow.sh` — `/multi-agent:channels` multi-select + humanizer + Bitbucket PUT (44 assertions)
+- `smoke-wiki-integration.sh` — v5.7+ wiki Case A/B + 4-adapter contract
+- `smoke-add-detail.sh` — legacy Bitbucket PUT reviewer-preservation
+- `smoke-issue-jira-triad.sh` — Issue → Jira → Wiki triad
+- `smoke-url-enrichment.sh` — Phase 0 Step 1b URL context parsing
+- `smoke-plan-approval-gate.sh` — Phase 2 clarification + free-text edit loop
+- `smoke-push-retry.sh` — 5-retry policy + 4-option fail flow
+- `smoke-identity-isolation.sh` — cross-identity PAT leak guard
+- `smoke-sync-delegation.sh`, `smoke-sync-parity.sh` — `/multi-agent:sync` behavior
+
+### Sub-systems
+- `smoke-multi-repo-integration.sh` — v5.6.0 integration build + learn-once registry (20 assertions)
+- `smoke-multi-repo-worktree.sh` — serial worktree creation with atomicity rollback
+- `smoke-prefs-language.sh` — `prefs.global.promptLanguage` contract
+- `smoke-progress-contract.sh` — progress-line quiet/normal/verbose
+- `smoke-search.sh` — `/multi-agent:search` log search + smart ranking
+- `smoke-stack-swap.sh` — `/multi-agent:stack` auto-detect + manual override
+- `smoke-subagent-validators.sh` — Phase 1/2 validator schemas
+- `smoke-telemetry.sh` — opt-in telemetry contract
+- `smoke-validator-contradiction.sh` — Phase 4 approved/blocking contradiction detection
+- `smoke-pre-commit.sh` — pre-commit hook integration
+
+## Hook scripts (3 files)
+Installed into `~/.claude/scripts/` and invoked by settings.json hook configuration.
+
+- `pre-commit-check.sh` — runs before `git commit` (secret scan + personal-data leak check)
+- `pre-push-check.sh` — runs before `git push` (smoke-cross-cli-behavior + smoke-personal-data)
+- `output-quality-check.sh` — runs after PR body / Jira comment generation (newline / HTML entity guard)
+
+## Runtime helpers (13 files)
+Shell scripts invoked during pipeline execution.
+
+- `phase-banner.sh` — renders phase headers
+- `phase-tracker.sh` — live tracker state + tokens accumulation + render
+- `stack-swap.sh` — stack detection + skill set swap
+- `keychain-save.sh` — store PAT in macOS Keychain
+- `audit-log.sh` + `audit-log-rotate.sh` — opt-in audit trail
+- `log-metric.sh` — opt-in metric capture
+- `search-logs.sh` — backs `/multi-agent:search`
+- `scan-skills.sh` — backs `/multi-agent:scan`
+- `benchmark-phase-0.sh` — Phase 0 perf harness
+- `sync-figma-source.sh` — WS-9 source sync (figma)
+- `import-figma-skills.sh` — developer-only import harness (not run at runtime)
+- `github-ssh-setup.sh` — first-run SSH key setup helper
+- `sync-parity-check.sh` — manual parity verification helper
+
+## Node.js helpers (12 `.mjs` files)
+
+- `aggregate-metrics.mjs` — collects telemetry aggregates
+- `eval-triage.mjs` — runs the 10 triage eval fixtures
+- `gen-skills-index.mjs` — regenerates `pipeline/skills/shared/README.md` skill catalog
+- `migrate-prefs.mjs` — preference migration driver (v2.0.0 → v2.1.0 → v2.2.0)
+- `migrate-state.mjs` — generic migration runner (reads `schemas/migrations/`)
+- `token-budget-report.mjs` — per-phase token usage report
+- `validate-analysis.mjs`, `validate-planning.mjs`, `validate-reviewer.mjs`, `validate-triage.mjs` — per-phase output validators
+- `validate-schemas.mjs` — top-level schema validity gate (runs every schema through AJV)
+- `write-state.mjs` — atomic state writer with concurrency safety
+
+## Why flat layout (not `smoke/`, `hooks/`, `runtime/`)
+
+The audit (v6.0.0 W3.3) considered moving files into subdirs for clarity. Tradeoffs:
+
+- **Pro:** easier navigation in file tree viewers; clearer categorization at a glance.
+- **Con:** every path reference would need updating — `npm test` glob (`pipeline/scripts/smoke-*.sh`), `install.js` `pipeline/scripts` deploy logic, every smoke's `$HERE/../..` root resolution, sibling calls between scripts, CI workflow references. 40+ file touch radius with no runtime behavior change.
+
+Verdict: flat layout kept, this README plays the navigator role. If the script count doubles and the ratio shifts, revisit.