session-orchestrator 3.16.0 → 3.19.0

package/agents/schemas/test-writer.schema.json

@@ -9,9 +9,9 @@
   "properties": {
     "status": {
       "type": "string",
-      "enum": ["done", "partial", "blocked"],
+      "enum": ["done", "no-tests-needed", "partial", "blocked"],
       "deprecated": true,
-      "description": "DEPRECATED (#472): emit `verdict` instead. Removed in v4.0. Mapping: done→PROCEED, partial→PROCEED_WITH_FOLLOWUPS, blocked→BLOCKED."
+      "description": "DEPRECATED (#472): emit `verdict` instead. Removed in v4.0. Mapping: done→PROCEED, partial→PROCEED_WITH_FOLLOWUPS, blocked→BLOCKED. `no-tests-needed` is a SUCCESS status (also →PROCEED): the scope was analysed and no test was worth adding; it requires a written justification and is neither `partial` nor `blocked`."
     },
     "verdict": {
       "type": "string",
@@ -38,10 +38,68 @@
         }
       }
     },
+    "test_delta": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Net effect on the test suite. Supersedes `coverage_delta` — removals and merges are first-class outcomes, not regressions. A negative `net_loc` alongside a green suite is a good result.",
+      "properties": {
+        "added": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Tests added. Each one needs a matching `justifications[]` entry."
+        },
+        "removed": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Tests deleted because they failed the falsification check, duplicated a sibling, or only exercised framework/language/prose-presence behaviour. Each removal is justified individually in the prose report."
+        },
+        "consolidated": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Pre-existing tests folded into parameterised or merged cases (counted as the number of source tests absorbed)."
+        },
+        "net_loc": {
+          "type": "integer",
+          "description": "Signed line delta across all touched test files. MAY be negative."
+        },
+        "happy_path": { "type": "integer", "minimum": 0 },
+        "error_path": { "type": "integer", "minimum": 0 },
+        "boundary": { "type": "integer", "minimum": 0 },
+        "falsification_check": {
+          "type": "string",
+          "description": "Summary of falsification check results."
+        }
+      }
+    },
+    "justifications": {
+      "type": "array",
+      "description": "One entry per ADDED test, naming the concrete bug it catches that no existing test catches. Required in substance whenever `test_delta.added > 0`; kept structurally optional for backward-compatibility with pre-#472 consumers. 'Improves coverage' is not a bug and is not an acceptable `bug_caught` value. Omit when `added` is 0.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["test", "bug_caught"],
+        "properties": {
+          "test": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The test name as written in the suite."
+          },
+          "bug_caught": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The specific bug this test catches that no existing test catches."
+          }
+        }
+      }
+    },
     "coverage_delta": {
       "type": "object",
       "additionalProperties": false,
+      "deprecated": true,
+      "description": "DEPRECATED: emit `test_delta` instead. Retained as an alias so pre-existing consumers keep validating; counts only additions and therefore cannot express consolidation. Do not emit alongside `test_delta`.",
       "properties": {
+        "added": { "type": "integer", "minimum": 0 },
+        "removed": { "type": "integer", "minimum": 0 },
         "happy_path": { "type": "integer", "minimum": 0 },
         "error_path": { "type": "integer", "minimum": 0 },
         "boundary": { "type": "integer", "minimum": 0 },

package/agents/security-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: security-reviewer
 description: Use this agent for security analysis — OWASP checks, authentication flows, input validation, authorization, and vulnerability assessment. Read-only analysis with actionable findings. Prioritizes high-confidence exploitable issues over theoretical ones. <example>Context: Quality wave includes security review of new endpoints. user: "Review the new API endpoints for security vulnerabilities" assistant: "I'll dispatch the security-reviewer agent to audit the new endpoints." <commentary>Security review after implementation catches auth gaps, injection risks, and missing validation.</commentary></example> <example>Context: Pre-deployment security check. user: "Run a security audit on the authentication changes" assistant: "I'll use the security-reviewer to verify the auth changes are secure." <commentary>Auth changes are high-risk — dedicated security review prevents vulnerabilities in production.</commentary></example>
-model: sonnet
+model: inherit
 color: red
 tools: Read, Grep, Glob, Bash
 sandbox-tier: read-only

package/agents/session-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: session-reviewer
 description: Use this agent between waves or at session end to verify work quality against the session plan. Checks implementation correctness, test coverage, TypeScript health, security basics, and issue tracking accuracy. <example>Context: Impl-Core wave is complete, coordinator needs quality check before Impl-Polish. user: "Impl-Core wave done, review before continuing" assistant: "I'll dispatch the session-reviewer to verify Impl-Core outputs." <commentary>Inter-wave quality gate ensures issues are caught early, not at session end.</commentary></example> <example>Context: Session end, verifying all work before committing. user: "/close" assistant: "Running session-reviewer to verify all session work before committing." <commentary>Final quality gate before any code is committed.</commentary></example>
-model: sonnet
+model: inherit
 color: pink
 tools: Read, Grep, Glob, Bash
 sandbox-tier: read-only

package/agents/test-writer.md

@@ -1,7 +1,7 @@
 ---
 name: test-writer
-description: Use this agent for writing unit tests, integration tests, and improving test coverage. Creates test files following project conventions and testing patterns. <example>Context: Quality wave needs tests for newly implemented features. user: "Write tests for the invoice service" assistant: "I'll dispatch the test-writer agent to create comprehensive tests for the invoice service." <commentary>Test creation after implementation ensures coverage without slowing down the impl agents.</commentary></example> <example>Context: Coverage gap identified during quality review. user: "Add edge case tests for the authentication flow" assistant: "I'll use the test-writer to add targeted edge case tests for authentication." <commentary>Filling specific coverage gaps requires understanding both the code and its failure modes.</commentary></example>
-model: sonnet
+description: Use this agent to close NAMED test gaps and to consolidate redundant tests. It writes the specific missing test, and it deletes, merges, or parameterises tests that do not earn their keep. <example>Context: Quality wave named one concrete gap — the invoice service never exercises the declined-payment branch. user: "The invoice service has no test for a declined payment" assistant: "I'll dispatch the test-writer to add that one error-path test and run the falsification check on it." <commentary>A named gap states a bug that would ship undetected; 'improve coverage' names nothing and is not a dispatchable task.</commentary></example> <example>Context: The auth test file has 14 tests — 6 assert the same validation branch and 3 only pin prose strings. user: "Clean up the auth test file" assistant: "I'll use the test-writer to merge the 6 duplicates into one parameterised test and delete the 3 prose-pinning tests — net test count falls 14 to 6 while catch-power rises, reported as test_delta.removed plus test_delta.consolidated." <commentary>Consolidation is a success outcome: fewer tests that each catch a distinct bug beat many that catch none, and a scope with no real gap legitimately ends with status no-tests-needed.</commentary></example>
+model: inherit
 color: orange
 tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*)
 sandbox-tier: repo-write
@@ -16,7 +16,8 @@ You are a focused testing agent. You write tests — unit, integration, and edge
 2. **Integration Tests**: Test interactions between modules with realistic fixtures
 3. **Edge Cases**: Cover boundary conditions, error paths, empty inputs, Unicode, and unusual values
 4. **Test Quality**: Write behavioral tests (test what code does, not how it's structured); enforce assertion specificity
-5. **Coverage Gaps**: Read existing tests, identify what's untested, and fill the gaps without duplicating
+5. **Named Gaps**: Read existing tests, name each untested behaviour as a concrete bug that would ship, and close exactly those gaps
+6. **Consolidation**: Delete, merge, and parameterise tests that fail the falsification check, duplicate a sibling, or only pin framework/language/prose behaviour
 
 ## Test Process
 
@@ -31,6 +32,10 @@ You are a focused testing agent. You write tests — unit, integration, and edge
 ## Rules
 
 - Do NOT modify production code — only test files (`*.test.*`, `*.spec.*`, `__tests__/`, `tests/`).
+- **You MAY delete, merge, and parameterise existing test files.** Removal is in scope — and expected — when (a) a test fails the falsification check, (b) two or more tests verify the same behaviour, or (c) a test only exercises framework, language, or prose-presence behaviour (`expect(typeof fn).toBe('function')`, a snapshot of a doc string, an assertion that a Markdown heading exists). Count every removal in `test_delta.removed` and justify each one individually in the report. **A deletion is a success, not a regression** — a suite that shrinks while its catch-power rises is the intended outcome.
+- Do NOT delete a test merely because it fails or is inconvenient. Deletion requires one of the three named grounds above; a failing test that *would* catch a real bug is a bug report, not a deletion candidate.
+- Do NOT write a test you cannot justify. Every added test needs a one-line answer to *"which concrete bug does this catch that no existing test catches?"* — recorded in `justifications[]`. If you cannot answer, do not write the test.
+- If the scope genuinely has no gap worth a new test, report `no-tests-needed` with the reasoning. Writing filler tests to avoid an empty diff is the failure mode this status exists to prevent.
 - Do NOT mock what you can test directly. Mock only external I/O (DB, HTTP, filesystem, time). Pure functions should never be mocked.
 - Do NOT write trivial tests. `expect(typeof add).toBe('function')` does not test behavior.
 - Do NOT add test utilities unless the same pattern appears 3+ times. Premature abstraction in tests obscures what's being tested.
@@ -80,20 +85,27 @@ Report back in this shape:
 - src/services/invoice.test.ts — added 8 unit tests
 - tests/integration/auth-flow.test.ts — added 3 integration tests
 
-### Coverage delta
-- New tests: <N> happy-path + <N> error-path + <N> boundary
+### Test delta
+- Added: <N> (<N> happy-path + <N> error-path + <N> boundary) — net LOC <±N>
+- Removed: <N> — each with its ground (falsification-fail | duplicate | framework-only)
+- Consolidated: <N> tests merged into <N> parameterised cases
 - Falsification-check: all pass (<N> tests verified would fail if logic removed)
 
+### Justifications (one per added test)
+- "<test name>" → catches: <the concrete bug this test catches that no existing test catches>
+
 ### Run results
 - All tests pass: <suite> — <N> passed, 0 failed
 - New tests run in <seconds>s
 
 ### Blockers / Notes
-- Coverage gaps not addressed (e.g., "rate-limit middleware integration deferred — needs test fixture")
+- Named gaps not addressed (e.g., "rate-limit middleware integration deferred — needs test fixture")
 
-Status: done | partial | blocked
+Status: done | no-tests-needed | partial | blocked
 ```
 
+`no-tests-needed` is a **success status**, equal in standing to `done`: the scope was analysed and no test was worth adding (behaviour already covered by an existing test, code is a trivial pass-through, or the only candidate tests would fail the falsification check). It is NOT `partial` and NOT `blocked` — nothing is outstanding. It REQUIRES a written justification naming what was examined and why each candidate test was rejected; an unjustified `no-tests-needed` is indistinguishable from doing nothing. A scope where the only work was consolidation reports `done` with `test_delta.added: 0` and a non-zero `removed`/`consolidated`.
+
 ### Machine-readable contract (#417)
 
 Append a fenced ```json block per `agents/schemas/test-writer.schema.json`:
@@ -103,14 +115,21 @@ Append a fenced ```json block per `agents/schemas/test-writer.schema.json`:
   "status": "done",
   "verdict": "PROCEED",
   "task_id": "<wave-id>",
-  "files_changed": ["tests/path/file.test.mjs"],
-  "coverage_delta": {"added": 12, "removed": 0},
+  "files_changed": [{"path": "tests/path/file.test.mjs", "tests_added": 3}],
+  "test_delta": {"added": 3, "removed": 5, "consolidated": 6, "net_loc": -118},
+  "justifications": [
+    {"test": "rejects the invoice when the payment is declined", "bug_caught": "a declined payment currently persists the invoice as PAID; no existing test enters the decline branch"}
+  ],
   "run_results": {"passed": 12, "failed": 0, "skipped": 0},
   "blockers": []
 }
 ```
 
-Required: `status`, `task_id`, `files_changed`, `blockers`. Optional: `verdict`. **Emit `verdict` alongside `status` (status→verdict mapping: done→PROCEED, partial→PROCEED_WITH_FOLLOWUPS, blocked→BLOCKED). `status` is deprecated and will be removed in v4.0 (#472).** The coordinator parses the LAST fenced ```json block.
+Required: `status`, `task_id`, `files_changed`, `blockers`. Optional: `verdict`, `test_delta`, `justifications`, `run_results`. **Emit `verdict` alongside `status` (status→verdict mapping: done→PROCEED, partial→PROCEED_WITH_FOLLOWUPS, blocked→BLOCKED; `no-tests-needed` also maps to PROCEED — it is a success outcome).** **`status` is deprecated and will be removed in v4.0 (#472).** The coordinator parses the LAST fenced ```json block.
+
+**`test_delta` supersedes `coverage_delta`.** Emit `test_delta` — `{added, removed, consolidated, net_loc}` — so removals and merges are first-class numbers rather than invisible work. `net_loc` is the signed line delta across all touched test files and MAY be negative; a negative `net_loc` paired with a green suite is a good result. `coverage_delta` is retained in the schema as a deprecated alias for older consumers; do not emit both.
+
+**`justifications` is required in substance whenever `test_delta.added > 0`** (the schema keeps it structurally optional for backward-compatibility with pre-existing consumers): one entry per added test, each naming a concrete bug that no existing test catches. "Improves coverage", "tests the happy path", and "good practice" are not bugs and are not acceptable `bug_caught` values. When `test_delta.added` is 0, omit the field.
 
 ## Edge Cases
 

package/agents/ui-developer.md

@@ -1,7 +1,7 @@
 ---
 name: ui-developer
 description: Use this agent for frontend implementation — UI components, pages, styling, accessibility, and responsive design. Handles React/Next.js components, CSS, and design system work. <example>Context: Implementation wave includes UI component work. user: "Build the invoice list page with filters and pagination" assistant: "I'll dispatch the ui-developer agent to implement the invoice list UI." <commentary>Frontend page implementation with interactive components is the ui-developer's specialty.</commentary></example> <example>Context: Accessibility improvements needed. user: "Fix WCAG violations in the dashboard components" assistant: "I'll use the ui-developer to audit and fix the accessibility issues." <commentary>WCAG compliance requires understanding semantic HTML, ARIA attributes, and keyboard navigation.</commentary></example>
-model: sonnet
+model: inherit
 color: magenta
 tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*)
 sandbox-tier: repo-write

package/commands/contract-version-bump.md

@@ -0,0 +1,28 @@
+---
+description: Classify and apply a version bump to a machine-readable contract (JSON Schema, API spec, config schema) — version literals, consumer compatibility, changelog entry, downstream drift
+argument-hint: "[--contract <path>]"
+---
+
+# Contract Version Bump
+
+The user wants to bump the version of a machine-readable contract (JSON Schema, API spec, or
+config schema) after changing it. Invoke the contract-version-bump skill with arguments:
+**$ARGUMENTS**.
+
+Runs six phases: classify the change against the CONTRACT'S OWN versioning rule (not generic
+semver instinct), find every version literal and vendored copy across this repo and every repo
+in the instruction file's `cross-repos:` list (`CLAUDE.md`, or `AGENTS.md` on Codex CLI — the two
+are transparent aliases), check whether every known consumer actually evaluates each
+new/changed schema keyword, apply the bump consistently (with written exceptions, never silent
+ones), write a Keep-a-Changelog entry that calls out breaking-for-consumers risk explicitly
+regardless of version tier, and report any dependent repo/copy left un-synced as follow-up work.
+
+**Usage:**
+
+- `/contract-version-bump` — infer the contract file from conversation context
+- `/contract-version-bump --contract docs/spec/estate.schema.json` — target a specific contract file explicitly
+
+Codifies three traps from a real case (GitLab issue #17, `aiat-enablement` repo, 2026-07-25): a
+missing Patch clause that silently forbade a legitimate constraint tightening, five version-
+literal locations including a vendored copy in a different repo, and a `maxLength` keyword a
+hand-written consumer would have silently ignored.

package/commands/portfolio.md

@@ -62,7 +62,7 @@ gitlab-portfolio:
   enabled: true
   mode: warn          # warn | strict | off
   stale-days: 30
-  critical-labels: ["priority:critical", "priority:high"]
+  critical-labels: ["priority::critical", "priority::high"]
 ```
 
 ## Output Format

package/docs/README.md

@@ -91,7 +91,8 @@ Two things worth knowing about this split:
 | `docs/examples/` | Living reference | Example Session Config blocks per project shape (Express API, integration test, Next.js, Swift/iOS). |
 | `docs/recipes/` | Living reference | Narrow how-to write-ups for a specific recurring pattern (e.g. the quality-gate container test-runner pattern). |
 | `docs/templates/` | Living reference | Copy-paste config snippets referenced directly by the setup guides (e.g. the `AGENTS.md` Session Config template). |
-| `docs/telemetry/` | Living reference | `telemetry-claims.md` — provenance/methodology notes for cross-repo telemetry numbers cited elsewhere in the docs. |
+| `docs/telemetry.md` (root) | Living reference | Public transparency page for the opt-in usage-telemetry client — exact field list, kill switches, consent precedence, retention. |
+| `docs/telemetry/` | Living reference | `telemetry-claims.md` — provenance/methodology notes for cross-repo telemetry numbers cited elsewhere in the docs (a separate, local-corpus data flow from the opt-in client telemetry above). |
 | `docs/adr/` | Public decision history | Architecture Decision Records — permanent, never archived, cited externally. |
 | `docs/prd/` | Active work document | PRDs of currently open epics only. Auto-archived to the Meta-Vault on epic close. |
 | `docs/plans/` | Active work document | `/write-executable-plan` artifacts for in-progress work. May not exist when nothing is mid-plan. |

package/docs/USER-GUIDE.md

@@ -155,7 +155,7 @@ Suitable for: a small SaaS product, an internal admin tool, a personal project y
 Sets up everything in Fast, plus:
 - Standard `CLAUDE.md` with full Session Config
 - Baseline directory structure per archetype
-- VCS labels created (`priority:*`, `status:*`, `type:*`)
+- VCS labels created (`priority::*`, `status:*`, `type:*`)
 - Initial `STATUS.md` SSOT file
 
 #### Deep — customer-facing systems, team repos, production
@@ -397,6 +397,9 @@ Add a `## Session Config` section to your project's Session Config host file to
 | `discovery-exclude-paths` | list | `[]` | Glob patterns to exclude from discovery scanning (e.g., `vendor/**`, `dist/**`). |
 | `discovery-severity-threshold` | string | `low` | Minimum severity for reported findings: `critical`, `high`, `medium`, `low`. |
 | `discovery-confidence-threshold` | integer | `60` | Minimum confidence score (0-100) for discovery findings to be reported. Findings below this threshold are auto-deferred. |
+| `issue-budget.max-per-session` | integer | `12` | Per-session cap on non-exempt issue creations. A **quantity** gate — unlike the two `discovery-*-threshold` filters above, which score individual findings and cannot bound volume. `priority::critical`, the carryover class and `broken-window` issues are exempt. |
+| `issue-budget.mode` | string | `strict` | `strict` blocks over-cap creations and parks them; `warn` allows with a stderr notice; `off` disables the gate. |
+| `issue-budget.overflow` | string | `collect-issue` | Where parked creations are drained at session-end: `collect-issue` (one `[Backlog-Sammel]` issue) or `vault-note` (one file under `vault/00-inbox/`). |
 | `persistence` | boolean | `true` | Enable session resumption via STATE.md and session memory files. |
 | `plan-baseline-path` | string | none | Path to projects-baseline directory (e.g., `~/Projects/projects-baseline`). Optional. When absent, `/bootstrap` falls back to plugin-bundled minimal templates. Only required if you want to scaffold from your own baseline during `/plan new`. |
 | `plan-default-visibility` | string | `internal` | Default repo visibility for `/plan new`: `internal`, `private`, or `public`. |
@@ -481,6 +484,8 @@ One or two agents update SSOT files, close or update issues, write session hando
 
 The `agents-per-wave` config value caps the maximum. These counts are guidelines — the orchestrator adjusts based on task complexity.
 
+The **Quality column is a cap, not a target**: since this version, test-writing capacity is need-gated on measured demand — roughly one test-writer per three HIGH/MED gaps the review panel actually found, capped by the number above. If no gaps were measured, the Quality wave writes no tests and is skipped (the read-only review panel still runs); with no measurement signal at all, the orchestrator allocates a conservative 1-2 rather than the full cap.
+
 ### Inter-Wave Checkpoints
 
 Between each wave, the orchestrator:
@@ -725,7 +730,7 @@ Before any code is committed, `/close` runs all checks:
 | Debug artifacts | No `console.log`, `debugger`, or `TODO: remove` in changed files |
 | Git status | All changes accounted for |
 
-If any check fails and cannot be quickly fixed, the orchestrator creates a `priority:high` issue for immediate follow-up rather than committing broken code.
+If any check fails and cannot be quickly fixed, the orchestrator creates a `priority::high` issue for immediate follow-up rather than committing broken code.
 
 ### Deterministic Scripts
 
@@ -808,7 +813,7 @@ Enable ecosystem health and configure your endpoints in Session Config:
 Each configured endpoint is queried with a simple HTTP check. If the endpoint returns JSON with a `status` field, that value is reported. Otherwise, the check reports OK or unreachable.
 
 **Cross-repo critical issues:**
-For each related repository, the orchestrator queries open issues with `priority:critical` or `priority:high` labels. This surfaces blocking problems in other parts of your ecosystem before you start working.
+For each related repository, the orchestrator queries open issues with `priority::critical` or `priority::high` labels. This surfaces blocking problems in other parts of your ecosystem before you start working.
 
 **CI pipeline status:**
 The latest CI pipeline runs are checked for the current repository.

package/docs/ci-setup.md

@@ -20,8 +20,69 @@ token or PAT stored as the masked CI variable `SCHEMA_DRIFT_TOKEN`.
 |---|---|---|---|---|
 | `SCHEMA_DRIFT_TOKEN` | Variable | Yes | Optional | deploy token or PAT (see below) |
 
-If `SCHEMA_DRIFT_TOKEN` is **not set**, the job prints a warning and exits 0
-(no pipeline failure). Set the variable to activate the real drift check.
+If `SCHEMA_DRIFT_TOKEN` is **not set**, the job prints a `NOT VERIFIED` notice
+and exits **3** — which `allow_failure.exit_codes` renders as an amber *warning*,
+never as a pass — provided `SCHEMA_DRIFT_OPTIONAL` is still `"true"`. Once that
+flag is flipped, the same missing token exits **4** and hard-fails. Set the
+variable to activate the real drift check; the full exit taxonomy is the table
+in the next section.
+
+Until 2026-07-30 this path exited **0**, so a job that had checked nothing
+reported exactly the same green tick as a job that had checked everything. It
+was visible in the timings: in pipeline 6815 `schema-drift-check` reported
+success after 17 seconds, which is not enough time to clone the baseline repo,
+let alone diff a schema against it. Issue #933.
+
+### Activating the hard gate (`SCHEMA_DRIFT_OPTIONAL`)
+
+`schema-drift-check` carries a committed job variable:
+
+```yaml
+variables:
+  SCHEMA_DRIFT_OPTIONAL: "true"
+```
+
+It is the review-visible declaration that "no token" is *currently* an accepted
+state. The behaviour matrix:
+
+| `SCHEMA_DRIFT_TOKEN` | `SCHEMA_DRIFT_OPTIONAL` | Exit | State | Pipeline effect |
+|---|---|---|---|---|
+| unset | `"true"` | 3 | `SKIPPED` | amber warning; `pipeline-gate` prints `schema-drift: NOT VERIFIED` |
+| unset | anything else | 4 | `MISCONFIGURED` | hard failure — the token is required and the check never ran |
+| set, clone fails | either | 5 | `UNAVAILABLE` | hard failure — token scope/expiry/masking or network, **not** drift |
+| set, clone works | either | 0 | `IN-SYNC` | pass; writes the `.ci-markers/schema-drift.ok` marker |
+| set, clone works | either | 1 | `DRIFT` | hard failure — **the only code that means drift** |
+
+**One code per fact.** Exit 1 is reserved for a real schema divergence; 3, 4 and
+5 all mean NOT VERIFIED and none of them is a drift verdict. That split is the
+point of the taxonomy: before it, "you forgot the token" and "the schema has
+diverged" were the same red, so the first person to see the failure went hunting
+a schema diff that does not exist. Only 3 is listed in
+`allow_failure.exit_codes`; 4 and 5 are hard failures by construction. Every
+outcome also prints its own `[schema-drift] RESULT: <STATE>` line, so the job log
+answers "what happened" without the reader having to know this table.
+
+**After completing the token setup below, change `SCHEMA_DRIFT_OPTIONAL` to
+`"false"` in `.gitlab-ci.yml`** — in **both** places: the `schema-drift-check`
+job and `pipeline-gate`. One flag, two enforcement points;
+`tests/ci/schema-drift-check.test.mjs` asserts the mirroring, so a half-flip
+fails the suite locally rather than silently leaving one point advisory. The
+flip is what converts a missing token from a tolerated warning into a hard red,
+and it is the whole point of the flag: the opt-out is a line in a reviewed file,
+not the accidental side effect of an unset CI variable.
+
+> **Before you flip it, run ONE pipeline with the token present while
+> `SCHEMA_DRIFT_OPTIONAL` is still `"true"`, and check the job's DURATION.**
+> A `schema-drift-check` that "succeeds" in under ~20 seconds did not clone the
+> baseline repo — that is the signature of the exit-3 soft-skip path, i.e. the
+> token is still not reaching the job (misspelled key, protected-variable on an
+> unprotected branch, or masking rejection). Flipping the flag on that state
+> converts a silent skip into a red pipeline whose message points at the wrong
+> problem. Confirm a real run first: the log must show
+> `RESULT: IN-SYNC (exit 0)` and the job must produce the
+> `.ci-markers/schema-drift.ok` artifact. This job has a recorded history of
+> exactly this failure — pipeline 6815 reported SUCCESS in 17 s having checked
+> nothing (issue #933).
 
 ### Option A — Deploy Token (recommended, least-privilege)
 
@@ -60,11 +121,21 @@ After setting the variable:
 1. Push to a feature branch or open an MR against `main`.
 2. Observe the `schema-drift-check` job in the pipeline — it should now clone
    `infrastructure/projects-baseline` and run the sync check instead of
-   printing the skip warning.
-3. A passing job (exit 0) means the vendored schema matches the canonical
-   source. A failing job (exit 1) means drift was detected — run
-   `node scripts/sync-vault-schema.mjs --update` locally and commit the
-   refreshed copy.
+   printing the skip warning. Read the job's `[schema-drift] RESULT:` line; it
+   names the state directly, and the duration corroborates it (a real run
+   clones a repo, so it cannot finish in seconds).
+3. Read the exit code against the table above before diagnosing anything:
+   - **0 (`IN-SYNC`)** — the vendored schema matches the canonical source.
+   - **1 (`DRIFT`)** — and only 1 — means drift was detected. Run
+     `node scripts/sync-vault-schema.mjs --update` locally and commit the
+     refreshed copy.
+   - **3 (`SKIPPED`)** — the token still is not reaching the job. Nothing was
+     compared; do not read the amber tick as a pass.
+   - **4 (`MISCONFIGURED`)** — `SCHEMA_DRIFT_OPTIONAL` is no longer `"true"` and
+     the token is missing. Provision the variable; there is no schema diff to
+     look for.
+   - **5 (`UNAVAILABLE`)** — the clone failed. Check the token's
+     `read_repository` scope, its expiry, and its masking. Also not drift.
 
 ### Why not configure the CI Job Token allowlist in projects-baseline?
 
@@ -79,3 +150,46 @@ Documenting it here for completeness:
   and `SCHEMA_DRIFT_TOKEN` is not needed.
 - Issue #279 chose the deploy-token path because it requires no admin action
   in the foreign project and works immediately after variable creation.
+
+## `pipeline-gate` — the fan-in job
+
+The last stage holds one job that depends on every blocking gate. It exists
+because until #933 nothing depended on anything: a gate could be deleted, or
+ruled out for a whole pipeline type, and the pipeline still went green.
+
+Two mechanisms, because "the gate is gone" and "the gate ran but verified
+nothing" are different failures:
+
+1. **Hard `needs:`** on every gate that runs on all non-scheduled pipelines.
+   On GitLab 18.11, needing a job that is absent from the pipeline is a
+   pipeline-*creation* error, not a silent skip (verified via
+   `POST /projects/74/ci/lint` with `dry_run`). Removing a gate from
+   `.gitlab-ci.yml` therefore produces no pipeline at all instead of a green
+   one — which is exactly the alarm we want, so these needs are intentionally
+   **not** `optional`.
+2. **Marker artifacts** for the two conditional jobs, `coverage` and
+   `schema-drift-check`. Each writes `.ci-markers/<name>.ok` as the final line
+   of its script, so the marker is reachable only from the path where the job
+   really verified something. `pipeline-gate` reads those markers and prints one
+   line per gate. This is what catches an amber `schema-drift-check`: an
+   `allow_failure` job never blocks a dependent job, so `needs:` alone is blind
+   to it.
+
+Coverage is required only on merge-request and default-branch pipelines (it is
+the slowest job at ~148s, and it re-runs a suite `test` has already run). On a
+plain branch pipeline `pipeline-gate` states that coverage was not measured —
+absent, but never silently absent.
+
+## Local pre-push gate
+
+`.husky/pre-push` runs `npm run quality-gate`
+(`scripts/run-quality-gate.mjs --variant full-gate`: typecheck + full vitest
+suite + lint) and blocks the push on any non-zero exit.
+
+- `full-gate` is used because it is the only **blocking** variant — the
+  `incremental` handler ends in an unconditional `process.exit(0)` and reports
+  rather than gates.
+- Delete-only pushes skip the gate (no code ships).
+- `SKIP_QUALITY_GATE=1 git push` is the named bypass. Prefer it over
+  `git push --no-verify`, which disables every hook silently and leaves no
+  record of what was skipped.

package/docs/codex-setup.md

@@ -90,7 +90,7 @@ The plugin bundle includes the Codex role definitions under `.codex-plugin/agent
 
 The Codex hook command uses Codex's native `${PLUGIN_ROOT}` expansion. The wrapper also exports `CODEX_PLUGIN_ROOT="${PLUGIN_ROOT}"` for shared compatibility code and sets `SO_PLATFORM=codex` so Codex wins when multiple harness variables are present.
 
-Claude-only events (`SessionEnd`, `PostToolUseFailure`, `PostToolBatch`, and `CwdChanged`) are intentionally absent because Codex 0.144.4 does not expose them as supported project events. Claude Edit/Write payload handlers are also absent: Codex emits canonical `apply_patch` data, while those handlers currently expect Claude's Edit/Write payload shape. They will remain unwired until a real `apply_patch` adapter exists; pretending the payloads are compatible would create false enforcement.
+Claude-only events (`SessionEnd`, `PostToolUseFailure`, `PostToolBatch`, and `CwdChanged`) are intentionally absent because Codex 0.144.4 does not expose them as supported project events. Claude Edit/Write payload handlers are also absent: Codex emits canonical `apply_patch` data, while those handlers currently expect Claude's Edit/Write payload shape. They will remain unwired until a real `apply_patch` adapter exists; pretending the payloads are compatible would create false enforcement. The same applies to the Bash-payload handlers, including `post-bash-write-verify.mjs` (#942): they gate on Claude's `tool_name === 'Bash'`, which no Codex bridge delivers, so wiring them today would be a silent no-op (the #919-P2 class). These per-event gaps are tracked as documented asymmetries in `scripts/lib/validate/check-hooks-symmetry.mjs` (Check 6, `handlerAsymmetries`) — an UNDOCUMENTED one-platform-only handler now fails validation.
 
 An empty `PreToolUse` or `SubagentStart` array means the event belongs to the validated Codex surface but currently has no payload-compatible handler. It does not mean installation or hook trust failed.
 

package/docs/components.md

@@ -7,8 +7,8 @@ Detailed component inventory and architecture reference for Session Orchestrator
 ```mermaid
 flowchart LR
     USER([Operator]) -->|invokes /session| COORD[Coordinator]
-    COORD -->|reads| SK[Skills<br/>44 user-facing]
-    COORD -->|invokes| CMD[Commands<br/>24 slash-cmds]
+    COORD -->|reads| SK[Skills<br/>46 user-facing]
+    COORD -->|invokes| CMD[Commands<br/>25 slash-cmds]
     COORD -->|dispatches| AG[Agents<br/>15 typed sub-agents]
     AG -.->|parallel waves| W1[code-implementer]
     AG -.-> W2[test-writer]
@@ -18,22 +18,22 @@ flowchart LR
     COORD -->|writes| METRIC[.orchestrator/metrics/<br/>sessions · learnings · events]
 ```
 
-## Skills (44 user-facing)
+## Skills (46 user-facing)
 
 - **Lifecycle:** `session-start`, `session-plan`, `wave-executor`, `session-end`, `quality-gates`, `using-orchestrator`
-- **Authoring:** `skill-creator`, `mcp-builder`, `hook-development`, `frontmatter-guard`
+- **Authoring:** `skill-creator`, `mcp-builder`, `hook-development`, `frontmatter-guard`, `contract-version-bump`
 - **Planning & discovery:** `plan`, `discovery`, `repo-audit`, `brainstorm`, `write-executable-plan`, `debug`, `claude-md-drift-check`, `grill`
 - **Architecture:** `architecture`, `domain-model`, `ubiquitous-language`
 - **Cross-session:** `evolve`, `convergence-monitoring`, `memory-cleanup`, `reconcile`, `sunset-review`, `eval`
 - **Vault & docs:** `vault-sync`, `vault-mirror`, `daily`, `docs-orchestrator`
-- **Ecosystem:** `bootstrap`, `gitlab-ops`, `gitlab-portfolio`, `ecosystem-health`, `mode-selector`, `autopilot`, `dispatcher`, `spinout`
+- **Ecosystem:** `bootstrap`, `gitlab-ops`, `gitlab-portfolio`, `ecosystem-health`, `mode-selector`, `autopilot`, `dispatcher`, `spinout`, `npm-publish`
 - **Testing:** `test-runner`, `playwright-driver`, `peekaboo-driver`
 - **Content review:** `persona-panel`
 - **Visualization:** `tmux-layout` (opt-in operator side-channel — [ADR-0007](adr/0007-tmux-visualization-substrate.md))
 
-## Commands (24)
+## Commands (25)
 
-`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, `/harness-audit`, `/autopilot`, `/autopilot-multi`, `/repo-audit`, `/test`, `/memory-cleanup`, `/portfolio`, `/brainstorm`, `/debug`, `/persona-panel`, `/grill`, `/sunset-review`, `/templates-ack`, `/dispatcher`, `/reconcile`, `/spinout`, `/eval`.
+`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, `/harness-audit`, `/autopilot`, `/autopilot-multi`, `/repo-audit`, `/test`, `/memory-cleanup`, `/portfolio`, `/brainstorm`, `/debug`, `/persona-panel`, `/grill`, `/sunset-review`, `/templates-ack`, `/dispatcher`, `/reconcile`, `/spinout`, `/eval`, `/contract-version-bump`.
 
 ## Agents (15 typed sub-agents)
 

package/docs/cursor-setup.md

@@ -47,12 +47,25 @@ vcs: github
 
 Note: `agents-per-wave` is ignored on Cursor since tasks execute sequentially (no parallel Agent dispatch).
 
-### Hooks (Optional)
-
-Cursor supports hooks via Settings > Hooks. Configure:
-
-- **afterFileEdit**: Run `hooks/enforce-scope.sh` for scope enforcement (post-hoc warning)
-- **beforeShellExecution**: Run `hooks/enforce-commands.sh` to block dangerous commands
+### Hooks (Optional — not yet enforcing)
+
+> **The hook handlers do not currently fire on Cursor (#919).** Both are written
+> against Claude Code's `PreToolUse` payload — they require `tool_name === "Bash"`
+> plus `tool_input.command`, and they signal a decision with a Claude Code
+> `hookSpecificOutput` envelope. Fed a Cursor `beforeShellExecution` payload,
+> `hooks/enforce-commands.mjs` short-circuits at its first gate and writes **0
+> bytes to stdout and 0 bytes to stderr, exit 0** — so the harness sees no
+> decision and **the command runs**. It is a silent no-op, not a block and not
+> even a warning. Making this real needs a Cursor input/output adapter, the way
+> Pi has `scripts/lib/pi-hook-bridge.mjs`; no such adapter exists yet.
+>
+> Until then, treat `hooks/hooks-cursor.json` as the *intended* mapping and do
+> not rely on it for command or scope enforcement on Cursor.
+
+Cursor supports hooks via Settings > Hooks. The intended mapping is:
+
+- **afterFileEdit**: `hooks/enforce-scope.mjs` for scope enforcement (post-hoc warning)
+- **beforeShellExecution**: `hooks/enforce-commands.mjs` for dangerous-command enforcement
 
 See `hooks/hooks-cursor.json` for the hook mapping reference.
 
@@ -75,15 +88,15 @@ Commands work the same as in Claude Code:
 | State directory | .claude/ | .cursor/ |
 | Config file | CLAUDE.md | CLAUDE.md (same!) |
 | Task tracking | TaskCreate/TaskUpdate | Text-based checklists |
-| Pre-edit enforcement | PreToolUse hook (blocks) | afterFileEdit hook (warns after) |
-| Command enforcement | PreToolUse hook (blocks) | beforeShellExecution hook (blocks) |
+| Pre-edit enforcement | PreToolUse hook (blocks) | None today — `afterFileEdit` handler is a no-op (#919) |
+| Command enforcement | PreToolUse hook (blocks) | None today — `beforeShellExecution` handler is a no-op (#919) |
 | Model | Claude via API | Model selected in Cursor settings |
 | Plan mode | EnterPlanMode tool | Instruction-based |
 
 ## Limitations
 
 1. **No parallel agents** — All wave tasks execute sequentially. Sessions take longer than in Claude Code.
-2. **Post-hoc scope enforcement** — Cursor's `afterFileEdit` fires after the edit, not before. It can warn but not prevent out-of-scope edits.
+2. **No hook enforcement yet (#919)** — the handlers in `hooks/hooks-cursor.json` are Claude Code `PreToolUse` handlers. On a Cursor payload both `enforce-commands.mjs` and `enforce-scope.mjs` short-circuit at their first gate and produce **0 bytes on stdout and stderr with exit 0** — a silent no-op, so nothing is blocked and nothing is warned. Two independent adapters are missing: Cursor's payload field names differ from `tool_name` / `tool_input.*`, and Cursor does not read Claude Code's `hookSpecificOutput` decision envelope. Even once adapted, Cursor's `afterFileEdit` fires *after* the edit, so scope enforcement could at best warn, never prevent.
 3. **Model preference advisory** — The `model-preference-cursor` frontmatter in skills is advisory only. Select your model in Cursor settings.
 4. **No native plugin loader** — Skills are delivered as `.cursor/rules/*.mdc` files, not loaded from a plugin directory.
 

package/docs/events-schema.md

@@ -59,10 +59,14 @@ namespace we own. The validator + regex live in `scripts/lib/events-schema.mjs`
 | `orchestrator.session.ended` | `hooks/on-session-end.mjs` | SessionEnd |
 | `orchestrator.session.stopped` | `hooks/on-stop.mjs` | Stop |
 | `orchestrator.session.lock.acquired` | `hooks/_lib/lock-bootstrap.mjs` | SessionStart |
+| `orchestrator.session.lock.released` | `hooks/on-session-end.mjs` · `scripts/lib/autopilot/worktree-pipeline.mjs` (`teardownWorktree`) | after a `release()` that matched ownership (#952). Payload: `session_id`, `caller` (`on-session-end`\|`worktree-pipeline`), `outcome` (`deleted`\|`already-gone`), `verified`; hook-side additionally `lock_session_id`, `semantic_session_id`, `end_reason` (the SessionEnd reason — deliberately NOT `reason`, which the sibling `release_failed` uses for the failure reason); pipeline-side additionally `worktree_path`, `issue_iid`. `outcome: 'already-gone'` means the lock had ALREADY vanished between `readLock()` and `release()` — the forensically interesting case, since a successful release previously left no trace at all and a missing lock was therefore indistinguishable from a lock someone else deleted (#914 residual 3) |
+| `orchestrator.session.lock.release_failed` | `hooks/on-session-end.mjs` · `scripts/lib/autopilot/worktree-pipeline.mjs` (`teardownWorktree`) | ownership matched but `release()` did NOT delete the lock (#724). Payload: `session_id`, `reason` (`fs-error`\|`session-mismatch`\|`not-deleted`\|`threw`), `caller`; pipeline-side additionally `worktree_path`, `issue_iid` |
+| `orchestrator.session.lock.reconcile_attempted` | `hooks/_lib/lock-reconcile.mjs` | SessionEnd, when NEITHER ownership check matched the recorded lock (#748). Payload: `session_id`, `action` (`reaped`\|`skipped`\|`unknown`), `reason` (e.g. `own-host-pid-alive`) |
+| `orchestrator.session.lock.reaped` | `scripts/lib/lock-reaper.mjs` | a dead lease was reaped. Payload: `session_id`, `semantic_session_id`, `host`, `pid`, `age_hours`, `reap_mode`, `current_session` |
 | `orchestrator.agent.stopped` | `hooks/on-stop.mjs` | SubagentStop |
 | `orchestrator.memory.propose_invoked` | `hooks/pre-bash-memory-propose-audit.mjs` | PreToolUse(Bash) |
 | `orchestrator.wave.started` / `.completed` | `hooks/post-tool-batch-wave-signal.mjs` | PostToolBatch — fires live via `.claude/wave-scope.json` `.wave` increase (mechanical fallback, #612); an explicit injected `wave_signal` still takes precedence |
-| `orchestrator.quality_gate.passed` / `.failed` | `scripts/run-quality-gate.mjs` | per gate-CLI run (live) |
+| `orchestrator.quality_gate.passed` / `.failed` | `scripts/run-quality-gate.mjs` (the gate CLI — live between waves) · `scripts/lib/quality-gate.mjs` (`emitGateEvent` inside `runQualityGateWithRetry`, reached ONLY under `verification-auto-fix.enabled: true` — default `false`, and `false` in this repo) | CLI: once per gate-CLI run. Library: once per `runQualityGateWithRetry` **call**, never per retry attempt (`attempts` carries that detail). The two paths never nest, so one run passes through exactly one emitter. **Payload (both):** `variant`, `exit_code`, plus `session_id` / `semantic_session_id` when `sessionAttribution()` finds a session lock (both omitted when it does not). CLI `variant` is the `--variant` value (`baseline`\|`incremental`\|`full-gate`\|`per-file`); the library pins `variant: 'auto-fix-loop'`. **CLI only:** `wave_number`. **Library only:** `attempts` (1…`maxRetries+1`) and `gate` (`lint`\|`typecheck`\|`test` — the fail-fast gate of the last attempt; omitted on the passing path). **Optional on both:** `counts: {passed, failed, total}`. **Absent is not zero — for both optional fields.** `counts` is admitted by the ONE shared policy `admitSuiteCounts()` (`scripts/lib/gates/gate-helpers.mjs`, #967 item 2), which returns `null` — never a zero triple — for an unmeasured or inconsistent input (test gate skipped/stubbed, fail-fast on lint or typecheck before the test step, no parseable `<N> passed` marker, or `passed + failed !== total`); both callers spread `...(counts ? { counts } : {})`, so the KEY is missing in those runs. A present `counts.failed: 0` therefore means "measured, zero failures", while an absent `counts` means "not measured" — reading a missing field as `0` mis-analyses the ledger in both directions. Same contract for `wave_number` (CLI, #966 step 1): resolved from the `.{pi,cursor,codex,claude}/wave-scope.json` sidecar, **omitted** — never `0` — when there is no sidecar or its `wave` is non-numeric/non-positive; a human running `npm run quality-gate` from a `git push` has no wave at all, so an invented wave 0 would have to be special-cased by every consumer. Note `total` is `passed + failed` and EXCLUDES skipped/todo (see `extractTestCounts`) |
 | `orchestrator.grounding.injected` | `scripts/compute-grounding-injection.sh` (via `scripts/emit-event.mjs`) | grounding injection, when `PERSISTENCE=true` |
 | `orchestrator.handover.gated` | `skills/session-end/SKILL.md` Phase 1.65 (skill-prose, via `scripts/emit-event.mjs`) | Handover-Alignment-Gate outcome (#773). Payload: `candidates_total`, `auto_carry`, `asked`, `dropped`, `questions_asked`, `questions_answered`, `questions_deferred`, `path` (`fast_path`\|`triage`\|`weiterarbeiten`\|`fail_open`). Emitted exactly once per close — including the fail-open skip and the "Weiterarbeiten" abort — so never-measured paths become observable |