devrites 3.1.0 → 3.2.1

package/pack/generated/codex/skills/rite-build/reference/spec-drift-guard.md

@@ -21,9 +21,14 @@ other phases reference it here.
    mismatch | design-system mismatch | test/evidence mismatch | external-doc mismatch
    | user-decision required.
 4. Local repair that preserves behavior/scope/architecture/data/UX/security/migration?
-     YES → log in drift.md + decisions.md, $rite-plan repair, resume.
-     NO  → ask the user (format below). Don't continue on the old plan.
-5. Run $rite-plan repair before resuming.
+     YES, active-slice technical/tool failure → log it and use Build's bounded debug
+       recovery. Do not ask for retry authorization and do not re-plan unless the
+       durable remaining-work instructions are wrong.
+     YES, durable plan is wrong → log it, run $rite-plan repair without a question,
+       re-vet, then resume.
+     NO, product/policy/irreversible-risk decision → ask the user (format below).
+5. Never continue on a known-wrong durable plan. A repaired active-slice implementation
+   may continue only after the normal recovery, reconciliation, and integrity gates pass.
 ```
 
 ## User question format
@@ -40,4 +45,5 @@ Which direction should DevRites take?
 4. Custom: describe the intended behavior
 ```
 
-Never continue coding on a known-wrong plan. Always re-plan before resuming.
+Never turn an objective defect, environment repair, tool bug, or proof rerun into a
+human permission question. Re-plan only when the durable plan changed.

package/pack/generated/codex/skills/rite-clarify/SKILL.md

@@ -79,7 +79,8 @@ dispatch uses
    `not-applicable`, or justified `deferred-nonblocking` with owner and validation gate.
    Partial/Missing, an unowned material assumption, or an open blocking/escalating question
    means `NEEDS CLARIFICATION`.
-7. **Write the verdict.** Update `decision-coverage.md`; success requires exactly
+7. **Write the verdict.** Update `decision-coverage.md`; success requires exactly one
+   `DevRites contract: devrites.readiness-artifacts.v2` field and exactly
    `Decision coverage: CLEAR`. Normal state is `Phase: clarify`, `Next step: $rite-temper`.
    A contract-neutral retrofit runs `devrites-engine clarify-return restore <slug>`; a
    changed behavior/acceptance contract leaves the return cursor unconsumed, writes

package/pack/generated/codex/skills/rite-clarify/reference/decision-coverage.md

@@ -26,6 +26,7 @@ environment, credentials/approvals, and evidence limits.
 ```markdown
 # Decision coverage
 
+DevRites contract: devrites.readiness-artifacts.v2
 Decision coverage: <CLEAR | NEEDS CLARIFICATION>
 Coverage inputs SHA-256: <exact value from `devrites-engine readiness-digest coverage <slug>`>
 
@@ -54,6 +55,7 @@ Combine rows only when one decision and owner genuinely close them.
 
 Run the digest command only after `brief.md`, `spec.md`, `decisions.md`,
 `assumptions.md`, and `questions.md` are final for this clarification pass, then
-copy its complete field line verbatim. The build gate recomputes the digest and
+write the current contract field exactly once and copy the digest's complete field line
+verbatim. The build gate recomputes the digest and
 rejects stale coverage. Any open blocking, validating, or escalating question
 also prevents `CLEAR`.

package/pack/generated/codex/skills/rite-define/SKILL.md

@@ -126,7 +126,8 @@ Pull these via `Read` when shaping the plan:
    **Visual acceptance** target (state × viewport × input + target R-id/brief rule)**, so
    the design contract maps to slices as well as acceptance criteria.
    `Tests/proof` names exact command, cwd, expected signal, prerequisites, and mutable
-   provenance inputs; `$rite-vet` preflights them.
+   provenance inputs; `$rite-vet` preflights them. Write the portable repository command,
+   never RTK/local wrappers, user-specific absolute paths, or temporary proof trees.
 4. **Map coverage and wiring:** every `AC-###` spec acceptance criterion maps to ≥1 `SLICE-###`
    (`rite-spec/reference/acceptance-criteria.md`); no orphaned criteria, no slice without a
    criterion. Lift covered/backstop `Edge Coverage` rows and resolved `Prohibitions (must-NOT)`

package/pack/generated/codex/skills/rite-define/reference/plan-template.md

@@ -58,6 +58,8 @@ slices above the cut, and no slice above it depends on one below.
 After which slices to run tests / build / browser proof. For UI slices, name the visual
 acceptance targets from `design-brief.md`, not a generic "looks good" check.
 Each proof names exact command/cwd/signal, prerequisites, and mutable provenance inputs.
+Use portable repository commands; runtime wrappers and local absolute/temp paths do not
+belong in a durable plan.
 
 **Key links** — the wiring the assembled feature must exhibit, one row each:
 `<from> → <to> via <mechanism>` (route → handler via registration; producer → consumer via
@@ -93,7 +95,7 @@ decisions.md / evidence.md when used.
 - [ ] Every `Mode: HITL` slice has `Gate`, `SLA`, and `Checkpoint` populated
 - [ ] Human-owned choices are resolved; surviving checkpoints need unavailable pre-code
       evidence or action-time approval
-- [ ] Slice proof commands, cwd, prerequisites, and provenance inputs are preflightable
+- [ ] Slice proof commands, cwd, prerequisites, and provenance inputs are portable and preflightable
 - [ ] Every UI slice names `Design brief states` and binary `Visual acceptance`
 - [ ] `Key links` rows cover every cross-slice wiring (or state `none`)
 - [ ] Cross-boundary contracts name producer, consumer, invariants/errors/order, and proof

package/pack/generated/codex/skills/rite-doctor/SKILL.md

@@ -35,7 +35,7 @@ It is **read-only**: it never edits the workspace, never advances a phase, never
 ## Workflow
 1. Run the diagnose core verbosely (resolve across install layouts):
    ```bash
-   devrites-engine doctor --verbose; echo "doctor rc=$?"
+   devrites-engine doctor; echo "doctor rc=$?"
    ```
 1a. **Surface the learnings nudge**: point the user at `$rite-learn` when a pattern recurs across
    shipped features (read-only; silent when there's nothing to say):
@@ -84,7 +84,7 @@ progress`, but it follows the compact labels and one-next-action rule from
 ```
 Done: DevRites health checked; <OK | n issues>.
 Changed: workspace only
-Evidence: devrites-engine doctor --verbose rc=<0|1>; health <skipped|PASS|WARN|FAIL>; reindex <skipped|result>; learnings nudge <summary|none>; extensions/overrides <ok|n issues>
+Evidence: devrites-engine doctor rc=<0|1>; health <skipped|PASS|WARN|FAIL>; reindex <skipped|result>; learnings nudge <summary|none>; extensions/overrides <ok|n issues>
 Open: <none | issue count and top issue>
 Next: <single command for the most urgent issue>
 Record: not applicable

package/pack/generated/codex/skills/rite-plan/SKILL.md

@@ -80,7 +80,10 @@ Pull `development-workflow.md` via `Read` when reshaping slice cadence or DoD cr
      scope, not a new negotiation.
    - **revise:** apply a requested planning-artifact revision and reconcile existing artifacts in
      any direction; propose the file edit set first, confirm each file before writing, and **never
-     edit source code**. **Gate first: revise or new?** Same intent? More than 50% of existing scope
+     edit source code**. The one confirmation exception is an explicit `$rite-upgrade`: its
+     validated `upgrade-assessment` authorizes one atomic, behavior-neutral normalization of
+     active planning artifacts, provided source, completed slices, answered questions, and
+     historical evidence remain unchanged. **Gate first: revise or new?** Same intent? More than 50% of existing scope
      survives? original *not* completable without this? Two "no"s → new work: recommend
      sealing/shipping the current workspace (MVP cut if named) then `$rite-spec` for the new
      intent, and stop. Revise preserves context; a new workspace separates the work.

package/pack/generated/codex/skills/rite-upgrade/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: rite-upgrade
+description: User-invoked semantic upgrade for an active legacy DevRites workspace. Reconciles unfinished planning with the installed workflow contract while preserving completed work and history.
+argument-hint: "[feature-slug]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+## Codex compatibility
+
+This is the Codex mirror of a DevRites skill. In Codex:
+
+- Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
+- Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
+- **Invocation and dispatch are different:** invoke means run a skill in this context; dispatch means start a fresh agent with `spawn_agent`, await it, and reconcile its result. Never describe inline skill work as a dispatch.
+- For every DevRites specialist or writer dispatch, first call `spawn_agent` with the named `devrites-<role>` custom role. The matching project contract is `.codex/agents/devrites-<role>.toml`.
+- If `spawn_agent` is callable but a named read-only role is unavailable, use generic `explorer` only when the host proves that run has a runtime-enforced read-only sandbox. Tell it to read `.codex/agents/devrites-<role>.toml`, follow its `developer_instructions`, and execute the unchanged packet. A missing read-only custom role is not evidence that spawning is unavailable.
+- Never dispatch generic `worker` for `devrites-slice-wright` unless the host proves that worker run carries exact DevRites identity and the same `.wright-allowlist` enforcement as the named role. Codex reports a generic run as `agent_type=worker`, so the generated global hooks cannot prove that binding. Reject that unsafe rung and use the documented labelled inline wright path with `.reconcile-inline` plus the full reconcile gate.
+- If the host cannot prove the generic explorer is runtime read-only, reject that rung too. Only when no spawn primitive exists or a higher-priority policy rejects a safe spawn may the root run the documented discipline inline. Label it `independence: fallback`, never call it independent, and apply every fallback risk gate. An unbound generic wright or unconfined generic explorer is such a safety rejection, not evidence that no agents exist.
+- Wait for every required fresh-context dispatch before reconciling or advancing. A backgrounded or lost result is incomplete.
+- Codex project hooks are installed in `.codex/hooks.json`; declared-leaf hooks are scoped inside `.codex/agents/devrites-*.toml`. Review and trust them with `/hooks` before relying on hook enforcement.
+- When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
+
+
+# $rite-upgrade: bring an active workspace onto the current contract
+
+Use this when a workspace created under older DevRites rules cannot safely continue with
+the installed pack. It reconciles the workspace to the current desired state; it does not
+replay a chain of release-specific scripts. Structural `devrites-engine migrate` remains a
+separate first step.
+
+Current semantic contract: `devrites.readiness-artifacts.v2`.
+
+## Rules consulted
+
+Read `devrites-lib/reference/standards/core.md`,
+`devrites-lib/reference/standards/agents.md`,
+`devrites-lib/reference/workspace-artifact-schema.md`, and the current Clarify, Define,
+Plan, Vet, Converge, and Build phase contracts needed by the assessment.
+
+## Invariants
+
+- Never edit application source, tests, dependencies, Git state, or historical evidence.
+- Preserve completed-slice identity, status, acceptance, dependencies, historical proof,
+  answered questions, and `touched-files.md`.
+- Reassess only unfinished planning. Archived or `done` workspaces are a no-op.
+- Never downgrade a workspace that names a future semantic contract.
+- This is a recovery command, not a lifecycle phase; never write `Phase: upgrade`.
+- Durable plans contain portable repository commands, not RTK/local aliases, user-specific
+  absolute paths, or temporary proof trees. Runtime packets may name an execution adapter;
+  evidence may record both logical and executed forms.
+- Ask at most one coherent question, and only for product, policy, irreversible risk, or
+  human-only access/action. Retry and repair authorization is agent-owned.
+- The explicit `$rite-upgrade` invocation authorizes the bounded workspace reconciliation.
+  The root remains the only canonical writer.
+
+## Workflow
+
+0. **Orient and normalize structure.** Read the active slug or `$ARGUMENTS`. Run:
+   ```bash
+   devrites-engine doctor; echo "doctor rc=$?"
+   ```
+   A binary/pack integrity mismatch stops at `$rite-doctor`; do not run migration or
+   mutate semantic artifacts. Once healthy, orient without writing:
+   ```bash
+   devrites-engine preamble [feature-slug]
+   devrites-engine snapshot [feature-slug]
+   ```
+   A missing workspace stops at `$rite-spec`; an archived or `Status: done` workspace is
+   a no-op. For an active healthy workspace, run:
+   ```bash
+   devrites-engine migrate
+   devrites-engine preamble [feature-slug]
+   devrites-engine snapshot [feature-slug]
+   ```
+   If every semantic artifact names the current contract and `build-readiness` passes,
+   report a no-op.
+1. **Freeze the preservation baseline.** Create the standard orchestrator-controlled
+   `agent-packet/v1` baseline. Include exact paths for current phase/artifact contracts,
+   `state.md`, `spec.md`, `decision-coverage.md`, `architecture.md`, `plan.md`, `tasks.md`,
+   `traceability.md`, `test-plan.md`, `eng-review.md`, `questions.md`, `decisions.md`,
+   `assumptions.md`, `drift.md`, `evidence.md`, and `touched-files.md` when present. Record
+   the source diff identity plus the protected identity/status/acceptance/dependency
+   fields for every completed slice and each preserved artifact identity. Freeze the
+   workspace while it is assessed.
+2. **Classify from fresh context.** Dispatch `devrites-upgrade-planner` with objective
+   `reconcile this workspace with devrites.readiness-artifacts.v2`, the exact baseline,
+   and budgets `25 files / 2,000 loaded lines / 180 result lines`. Require one validated
+   `upgrade-assessment`. The agent writes nothing and asks nothing.
+3. **Reconcile ownership.** Reject stale, malformed, or preservation-breaking advice.
+   Dispatch `devrites-evidence-scout` only for a bounded missing fact. Drop an open
+   retry/tool-repair question with `devrites-engine resolve --drop <qid>
+   "superseded by explicit semantic upgrade; agent-owned recovery"` and continue. Keep a
+   genuine existing human gate intact; if a newly discovered human-owned choice is
+   unavoidable, persist one option packet and stop.
+4. **Apply current desired state in the root.**
+   - Remove obsolete old-engine reconstruction, old workflow hashes, temporary proof
+     recipes, and host-local wrappers from active `plan.md`, `tasks.md`, and
+     `test-plan.md`. Keep historical evidence unchanged.
+   - Re-run Clarify against unfinished intent until `Decision coverage: CLEAR`; it writes
+     exactly one `DevRites contract: devrites.readiness-artifacts.v2` field. Do not stamp a
+     marker over stale content.
+   - Re-run Temper only where unfinished scope still needs strategic review.
+   - For unstarted planning, use the current Define contract. When active planning needs
+     normalization, dispatch `devrites-plan-drafter` in repair mode and reconcile only
+     pending slices. Preserve all completed slices without changing their protected fields.
+     For all-built active work, normalize only gate-required planning fields. Use Converge
+     only when live code and recorded intent genuinely differ.
+   - Invalidate stale engineering readiness after any planning edit. Run the full current
+     Vet contract, including its fresh plan reviewer, portable proof commands, preflight,
+     and digest refresh. Vet writes exactly one current contract field to `test-plan.md`
+     and `eng-review.md`.
+5. **Verify preservation and readiness.** Recompute the frozen source diff, every protected
+   completed-slice field, `evidence.md`, answered-question records, and `touched-files.md`;
+   any mismatch is a hard stop and must be restored before proceeding. Then run:
+   ```bash
+   devrites-engine build-readiness [feature-slug]; echo "readiness rc=$?"
+   ```
+   Follow the gate's current route for `2` through `7`; `8` means the semantic
+   reconciliation is still incomplete. Finish only at `0`. Preserve the original active
+   build cursor when it still names the next pending slice; otherwise use the current
+   deterministic next action.
+6. **STOP.** Do not start Build. A second `$rite-upgrade` must take the current-contract
+   no-op path.
+
+## Output
+
+Run `devrites-engine progress`, then use the shared completion reply contract in
+`devrites-lib/reference/reply-contract.md`:
+
+```text
+Done: workspace <slug> upgraded to devrites.readiness-artifacts.v2.
+Changed: <active planning artifacts only | none; already current>
+Evidence: build-readiness rc=0; source/completed slices/history preserved
+Open: <none | one genuine human gate>
+Next: <snapshot next command>
+Record: .devrites/work/<slug>/state.md
+↻ Hygiene: /clear before the next lifecycle step
+```
+
+On a no-op, say so and keep the snapshot's current next command.

package/pack/generated/codex/skills/rite-upgrade/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/pack/generated/codex/skills/rite-vet/SKILL.md

@@ -126,7 +126,9 @@ Pull the standard named by the active axis: `principles.md`, `patterns.md`,
    ```
    Completion: every scenario and acceptance criterion maps to planned proof, every slice is
    one-pass implementable, the Build-entry preflight is green or names an owned prerequisite,
-   and developer-facing plans have a predicted `devex.md` scorecard.
+   and developer-facing plans have a predicted `devex.md` scorecard. Durable proof commands
+   are portable repository commands; host-local wrappers belong only in runtime packets and
+   recorded execution evidence.
 4a. **Forge gate.** `$rite-define` leaves `no` / `none` / `none`; Vet alone promotes under
    [`rite-build/reference/forge.md`](../rite-build/reference/forge.md). Require a costly
    unresolved architecture fork, 2–3 distinct complete contiguous `A`–`C` strategies, every
@@ -149,7 +151,9 @@ Pull the standard named by the active axis: `principles.md`, `patterns.md`,
    devrites-engine analyze; echo "final analyze rc=$?"
    ```
    Any non-zero result blocks the handoff. Then update `state.md`:
-   write one typed field to `eng-review.md`: `Implementation readiness: READY`,
+   write exactly one `DevRites contract: devrites.readiness-artifacts.v2` field to both
+   `test-plan.md` and `eng-review.md`, plus one typed field to `eng-review.md`:
+   `Implementation readiness: READY`,
    `NEEDS CLARIFICATION`, or `NEEDS REPLAN`. Only READY sets `Phase: vet` and
    `Next step: $rite-build`, after a final sweep leaves no foreseeable human choice except a
    justified action-time checkpoint. Technical failure records its reproduction and

package/pack/generated/codex/skills/rite-vet/reference/artifacts.md

@@ -10,6 +10,7 @@ clobber.
 ```markdown
 # Eng review: <slug>
 Vetted: <iso>   Cross-model: ran (codex) | off
+DevRites contract: devrites.readiness-artifacts.v2
 Implementation readiness: <READY | NEEDS CLARIFICATION | NEEDS REPLAN>
 Readiness inputs SHA-256: <exact value from `devrites-engine readiness-digest engineering <slug>`>
 
@@ -74,6 +75,7 @@ test and where*, not implementation detail.
 ```markdown
 # Test plan: <slug>
 From $rite-vet on <iso>. Runner + conventions: <detected framework + command>.
+DevRites contract: devrites.readiness-artifacts.v2
 
 ## Build-entry preflight
 | Gate | Command | Cwd | Expected | Prerequisites | Provenance to recapture |
@@ -83,6 +85,10 @@ From $rite-vet on <iso>. Runner + conventions: <detected framework + command>.
 Link any disposable parser fixture. Build evidence recomputes every digest; preflight values
 are not post-build proof.
 
+Commands in this durable artifact are portable repository commands: no RTK or local shell
+aliases, user-specific absolute paths, or temporary proof trees. A runtime packet may name
+an execution adapter, and evidence may record the portable and executed forms.
+
 ## Coverage diagram
 <the ASCII code-paths + user-flows diagram from review-axes.md, with COVERAGE / GAPS / REGRESSIONS line>
 
@@ -163,6 +169,8 @@ acceptance/behavior changes route through the **Spec Drift Guard**.
   `devrites-engine readiness-digest coverage <slug>` and replace the complete
   `Coverage inputs SHA-256` line in `decision-coverage.md`. Only then run
   `devrites-engine readiness-digest engineering <slug>` and copy its complete
-  field line into `eng-review.md`. The build gate rejects a stale digest,
+  field line into `eng-review.md`. Write
+  `DevRites contract: devrites.readiness-artifacts.v2` exactly once in both artifacts
+  only after their current-contract review is complete. The build gate rejects a stale digest,
   placeholders, non-passing preflight/readiness rows, empty tables, or an
   acceptance criterion with no test mapping.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devrites",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "DevRites: a disciplined senior-engineer workflow pack for Claude Code and Codex",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/ViktorsBaikers/DevRites#readme",
@@ -54,7 +54,7 @@
     "test:fast": "node scripts/run-tests.mjs --fast",
     "test:parallel": "node scripts/run-tests.mjs",
     "test:serial": "node scripts/run-tests.mjs --serial",
-    "audit": "npm audit --audit-level=moderate",
+    "audit": "node scripts/check-npm-audit.mjs",
     "size:baseline": "node scripts/check-instruction-size-baseline.mjs --write",
     "release": "semantic-release",
     "release:dry": "semantic-release --dry-run --no-ci"

package/scripts/check-npm-audit.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const args = process.argv.slice(2);
+const option = (name, fallback) => {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : fallback;
+};
+const input = option('--input', '');
+const exceptionsPath = resolve(option('--exceptions', resolve(root, 'scripts', 'npm-audit-exceptions.json')));
+const blocking = new Set(['moderate', 'high', 'critical']);
+const failures = [];
+const fail = (message) => failures.push(message);
+const load = (path) => JSON.parse(readFileSync(path, 'utf8'));
+
+let report;
+if (input) {
+  report = load(resolve(input));
+} else {
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const result = spawnSync(npm, ['audit', '--json'], { cwd: root, encoding: 'utf8' });
+  if (result.error || ![0, 1].includes(result.status)) {
+    console.error(result.stderr || result.error?.message || `npm audit exited ${result.status}`);
+    process.exit(1);
+  }
+  try {
+    report = JSON.parse(result.stdout);
+  } catch {
+    console.error('FAIL: npm audit did not return valid JSON');
+    process.exit(1);
+  }
+}
+
+const concrete = new Map();
+let affected = 0;
+for (const [packageName, vulnerability] of Object.entries(report.vulnerabilities || {})) {
+  if (!blocking.has(vulnerability.severity)) continue;
+  affected++;
+  for (const via of vulnerability.via || []) {
+    if (!via || typeof via !== 'object' || !blocking.has(via.severity)) continue;
+    const id = via.url?.match(/GHSA-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}/i)?.[0];
+    if (!id) {
+      fail(`${packageName}: blocking advisory has no GHSA identifier`);
+      continue;
+    }
+    const finding = concrete.get(id) || {
+      id,
+      package: via.name || packageName,
+      range: via.range || vulnerability.range,
+      source: via.url,
+      nodes: [],
+    };
+    finding.nodes = [...new Set([...finding.nodes, ...(vulnerability.nodes || [])])].sort();
+    concrete.set(id, finding);
+  }
+}
+if (affected > 0 && concrete.size === 0) fail('blocking audit findings have no concrete advisory records');
+
+const exceptions = load(exceptionsPath);
+if (!Array.isArray(exceptions)) fail('npm audit exceptions must be a JSON array');
+const today = new Date().toISOString().slice(0, 10);
+const seen = new Set();
+for (const exception of Array.isArray(exceptions) ? exceptions : []) {
+  const required = ['id', 'package', 'range', 'source', 'owner', 'reason', 'expires'];
+  const missing = required.filter((field) => !exception?.[field]);
+  if (!Array.isArray(exception?.nodes) || exception.nodes.length === 0) missing.push('nodes');
+  if (missing.length) {
+    fail(`${exception?.id || 'unknown exception'}: missing ${missing.join(', ')}`);
+    continue;
+  }
+  if (!/^GHSA-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}$/i.test(exception.id) || !/^\d{4}-\d{2}-\d{2}$/.test(exception.expires)) {
+    fail(`${exception.id}: invalid id or expiry`);
+    continue;
+  }
+  if (seen.has(exception.id)) fail(`${exception.id}: duplicate exception`);
+  seen.add(exception.id);
+  if (exception.expires < today) fail(`${exception.id}: exception expired ${exception.expires}`);
+
+  const finding = concrete.get(exception.id);
+  if (!finding) {
+    fail(`${exception.id}: exception is stale; advisory is absent`);
+    continue;
+  }
+  for (const field of ['package', 'range', 'source']) {
+    if (exception[field] !== finding[field]) {
+      fail(`${exception.id}: ${field} mismatch (expected ${finding[field]})`);
+    }
+  }
+  if (JSON.stringify([...exception.nodes].sort()) !== JSON.stringify(finding.nodes)) {
+    fail(`${exception.id}: nodes mismatch (expected ${finding.nodes.join(', ')})`);
+  }
+}
+for (const finding of concrete.values()) {
+  if (!seen.has(finding.id)) fail(`${finding.id}: blocking advisory is not excepted`);
+}
+
+for (const message of failures) console.error(`FAIL: ${message}`);
+if (failures.length) process.exit(1);
+if (affected === 0) {
+  console.log('npm-audit: no moderate-or-higher advisories');
+} else {
+  for (const exception of exceptions) {
+    console.log(`npm-audit: temporary ${exception.id} exception owned by ${exception.owner}, expires ${exception.expires}`);
+  }
+  console.log(`npm-audit: ${concrete.size} exact temporary exception(s), ${affected} affected package record(s)`);
+}

package/scripts/npm-audit-exceptions.json

@@ -0,0 +1,14 @@
+[
+  {
+    "id": "GHSA-r292-9mhp-454m",
+    "package": "tar",
+    "range": "<=7.5.20",
+    "nodes": [
+      "node_modules/npm/node_modules/tar"
+    ],
+    "source": "https://github.com/advisories/GHSA-r292-9mhp-454m",
+    "owner": "release-maintainers",
+    "reason": "npm@11.18.0 bundles tar@7.5.19 through @semantic-release/npm. The plugin invokes npm for authentication and publishing operations over trusted local source; it does not select or extract members from untrusted tar archives. Remove this exception as soon as npm bundles tar@7.5.21 or newer.",
+    "expires": "2026-08-07"
+  }
+]

package/scripts/run-outcome-evals.sh

@@ -83,11 +83,13 @@ stage_workspace() {
   mkdir -p "$ws"
   cp -R "$GOOD/." "$ws/"
   if [ "$mode" = "readiness" ]; then
-    python3 - "$ws/state.md" <<'PY'
+    python3 - "$ws" "$READINESS" <<'PY'
 from pathlib import Path
+import json
 import sys
 
-path = Path(sys.argv[1])
+workspace, contract_path = map(Path, sys.argv[1:])
+path = workspace / "state.md"
 text = path.read_text()
 for old, new in (
     ("| phase | done |", "| phase | build |"),
@@ -97,6 +99,35 @@ for old, new in (
         raise SystemExit(f"{path}: expected exactly one {old!r}")
     text = text.replace(old, new)
 path.write_text(text)
+
+contract = json.loads(contract_path.read_text())
+field = contract["contractField"]
+declaration = f"{field}: {contract['schema']}"
+for name in ("decision-coverage.md", "test-plan.md", "eng-review.md"):
+    artifact = workspace / name
+    lines = [
+        line for line in artifact.read_text().splitlines()
+        if not line.startswith(f"{field}:")
+    ]
+    lines[1:1] = ["", declaration]
+    artifact.write_text("\n".join(lines) + "\n")
+PY
+    local engineering_digest
+    engineering_digest="$(
+      env DEVRITES_ROOT="$project" "$ENGINE" readiness-digest engineering "$slug"
+    )"
+    python3 - "$ws/eng-review.md" "$engineering_digest" <<'PY'
+from pathlib import Path
+import sys
+
+path = Path(sys.argv[1])
+field = sys.argv[2]
+lines = path.read_text().splitlines()
+matches = [i for i, line in enumerate(lines) if line.startswith("Readiness inputs SHA-256:")]
+if len(matches) != 1:
+    raise SystemExit(f"{path}: expected exactly one engineering digest")
+lines[matches[0]] = field
+path.write_text("\n".join(lines) + "\n")
 PY
   fi