harness-everything 0.32.0 → 0.34.0

package/ci/mechanism-2az-step-type-registry.test.js

@@ -832,6 +832,92 @@ checkCase('Claude hook copy is byte-identical and a tracked Codex runtime includ
   compat.uninstall({ codexHome });
 });
 
+checkCase('registered code-review optional binding activates review steps from source and packaged roots', () => {
+  const requirements = [
+    { id: 'req-review', stepType: 'review', summary: 'Review the change', acceptance: 'findings recorded with evidence tiers', optionalBindings: ['code-review'] },
+    { id: 'req-verify', stepType: 'verification', summary: 'Verify the change', acceptance: 'objective checks pass' },
+  ];
+  for (const leg of [
+    { root: ROOT, sessionId: 'code-review-source-root', expected: path.join(ROOT, 'code-review', 'SKILL.md') },
+    { root: path.join(tempRoot, 'code-review-packaged-root'), sessionId: 'code-review-packaged-root', expected: path.join(tempRoot, 'code-review-packaged-root', 'skills', 'code-review', 'SKILL.md') },
+  ]) {
+    if (leg.root !== ROOT) {
+      fs.mkdirSync(leg.root, { recursive: true });
+      for (const directory of ['hooks', 'harness-everything', 'scripts', 'fable-mode']) {
+        fs.cpSync(path.join(ROOT, directory), path.join(leg.root, directory), { recursive: true });
+      }
+      fs.cpSync(path.join(packageRoot, 'skills'), path.join(leg.root, 'skills'), { recursive: true });
+    }
+    const session = planSession(leg.sessionId, requirements, 'iterative-single', leg.root, FIX_PROMPT, 'author-declared plan with an optional code-review binding', leg.root);
+    assert.strictEqual(session.planned.status, 0, session.planned.stderr);
+    const declared = readJson(session.obligationsFile).requirements[0].optionalBindings.find(item => item.id === 'code-review');
+    assert.strictEqual(declared.availability, 'available', 'the registered optional binding must resolve from the declared runtime root');
+    assert.strictEqual(fs.realpathSync(declared.resolvedPath), fs.realpathSync(leg.expected), 'the optional binding resolves to the canonical code-review skill file');
+    const legController = path.join(leg.root, 'hooks/scripts/workflow-disposition.js');
+    const started = run(legController, ['start', '--session-id', leg.sessionId], leg.root);
+    assert.strictEqual(started.status, 0, started.stderr);
+    const load = run(legController, [
+      'binding', '--session-id', leg.sessionId, '--step-id', 'req-review', '--binding-id', 'code-review',
+      '--disposition', 'loaded', '--evidence', 'Read code-review/SKILL.md and applied its evidence-tier rubric.',
+    ], leg.root);
+    assert.strictEqual(load.status, 0, load.stderr);
+    const loaded = readJson(session.obligationsFile).requirements[0].optionalBindings.find(item => item.id === 'code-review');
+    assert.strictEqual(loaded.status, 'loaded');
+    assert.strictEqual(fs.realpathSync(loaded.resolvedPath), fs.realpathSync(leg.expected), 'the loaded binding keeps its canonical resolved path');
+    const passed = run(legController, [
+      'step', '--session-id', leg.sessionId, '--step-id', 'req-review', '--disposition', 'pass',
+      '--evidence', 'Review findings filed against the diff with evidence tiers.',
+    ], leg.root);
+    assert.strictEqual(passed.status, 0, passed.stderr);
+  }
+
+  const notNeeded = planSession('code-review-not-needed', requirements, 'iterative-single', ROOT, FIX_PROMPT, 'author-declared plan marks code-review not needed');
+  assert.strictEqual(notNeeded.planned.status, 0, notNeeded.planned.stderr);
+  assert.strictEqual(run(controller, ['start', '--session-id', 'code-review-not-needed'], ROOT).status, 0);
+  assert.strictEqual(run(controller, [
+    'binding', '--session-id', 'code-review-not-needed', '--step-id', 'req-review', '--binding-id', 'code-review',
+    '--disposition', 'not-needed', '--evidence', 'Reviewed inline against the agentic-commons review rubric.',
+  ], ROOT).status, 0, 'an optional binding can be marked not-needed');
+  assert.strictEqual(run(controller, [
+    'step', '--session-id', 'code-review-not-needed', '--step-id', 'req-review', '--disposition', 'pass',
+    '--evidence', 'Review completed without the optional skill.',
+  ], ROOT).status, 0, 'marking code-review not-needed still lets the review step pass');
+
+  const unknown = planSession('code-review-unknown-optional', [
+    { id: 'req-review', stepType: 'review', summary: 'Review the change', acceptance: 'findings recorded with evidence tiers', optionalBindings: ['no-such-skill'] },
+    { id: 'req-verify', stepType: 'verification', summary: 'Verify the change', acceptance: 'objective checks pass' },
+  ]);
+  assert.strictEqual(unknown.planned.status, 0, unknown.planned.stderr);
+  const undeclared = readJson(unknown.obligationsFile).requirements[0].optionalBindings.find(item => item.id === 'no-such-skill');
+  assert.strictEqual(undeclared.availability, 'unknown', 'an unregistered binding id stays unknown');
+  assert.strictEqual(run(controller, ['start', '--session-id', 'code-review-unknown-optional'], ROOT).status, 0);
+  const cannotLoad = run(controller, [
+    'binding', '--session-id', 'code-review-unknown-optional', '--step-id', 'req-review', '--binding-id', 'no-such-skill',
+    '--disposition', 'loaded', '--evidence', 'attempted load without a registered path',
+  ], ROOT);
+  assert.strictEqual(cannotLoad.status, 2, cannotLoad.stderr);
+  assert.match(cannotLoad.stderr, /no registered load path/, cannotLoad.stderr);
+  assert.strictEqual(run(controller, [
+    'step', '--session-id', 'code-review-unknown-optional', '--step-id', 'req-review', '--disposition', 'pass',
+    '--evidence', 'premature pass while the unknown optional binding is pending',
+  ], ROOT).status, 2, 'a pending unknown optional binding still blocks a premature step pass');
+  assert.strictEqual(run(controller, [
+    'binding', '--session-id', 'code-review-unknown-optional', '--step-id', 'req-review', '--binding-id', 'no-such-skill',
+    '--disposition', 'not-needed', '--evidence', 'No Harness skill exists under that id.',
+  ], ROOT).status, 0, 'an unknown optional binding is marked not-needed instead');
+  assert.strictEqual(run(controller, [
+    'step', '--session-id', 'code-review-unknown-optional', '--step-id', 'req-review', '--disposition', 'pass',
+    '--evidence', 'Review completed without any optional skill.',
+  ], ROOT).status, 0, 'marking the unknown optional binding not-needed lets the step pass');
+
+  const forbidden = planSession('code-review-review-still-forbids-tdd', [
+    { id: 'req-review', stepType: 'review', summary: 'Review the change', acceptance: 'the change is reviewed', optionalBindings: ['tdd'] },
+    { id: 'req-verify', stepType: 'verification', summary: 'Verify the change', acceptance: 'objective checks pass' },
+  ]);
+  assert.strictEqual(forbidden.planned.status, 2);
+  assert.match(forbidden.planned.stderr, /review steps cannot bind tdd/);
+});
+
 fs.rmSync(tempRoot, { recursive: true, force: true });
 console.log(`\n${failed === 0 ? 'PASS' : 'FAIL'}: Stage A workflow step-type registry (${failed} failures)`);
 process.exit(failed === 0 ? 0 : 1);

package/ci/openai-plugin-package.test.js

@@ -104,7 +104,7 @@ const packagedSkillNames = fs.readdirSync(path.join(PLUGIN, 'skills'), { withFil
   .filter(entry => entry.isDirectory())
   .map(entry => entry.name)
   .sort();
-assert.strictEqual(skillNames.length, 26, 'canonical suite should contain 26 skills');
+assert.strictEqual(skillNames.length, 27, 'canonical suite should contain 27 skills');
 assert.deepStrictEqual(packagedSkillNames, skillNames, 'OpenAI package must contain exactly the canonical skill set');
 for (const entry of SOURCE_MANIFEST.skills) {
   const source = path.resolve(ROOT, entry);

package/ci/release-consistency-check.js

@@ -43,6 +43,22 @@ const releaseRenames = new Map([
   ['create-agent-launcher', 'multi-agent-workspace']
 ]);
 
+function logicalSkillName(skill) {
+  return releaseRenames.get(skill) || skill;
+}
+
+function compareSkillCatalogs(tagSkills, currentSkills) {
+  const releaseLogical = new Set(tagSkills.map(logicalSkillName));
+  const currentLogical = new Set(currentSkills.map(logicalSkillName));
+  const missing = [...releaseLogical].filter(skill => !currentLogical.has(skill)).sort();
+  const additions = [...new Set(currentSkills.filter(skill => !releaseLogical.has(logicalSkillName(skill))))].sort();
+  return { missing, additions, exitCode: missing.length ? 1 : 0 };
+}
+
+function formatAdditions(additions) {
+  return additions.length ? `Additions since release tag: ${additions.join(', ')}` : '';
+}
+
 function git(args) {
   return execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
 }
@@ -90,15 +106,13 @@ function main() {
     process.exit(2);
   }
   const current = new Set(discoverSkills(root));
-  const currentLogical = new Set([...current].map(skill => releaseRenames.get(skill) || skill));
-  const releaseLogical = new Set(tagRoot.map(skill => releaseRenames.get(skill) || skill));
-  const missing = [...releaseLogical].filter(skill => !currentLogical.has(skill));
-  const extra = [...currentLogical].filter(skill => !releaseLogical.has(skill));
+  const comparison = compareSkillCatalogs(tagRoot, [...current]);
   console.log(`Release ${tag}: ${tagRoot.length} skill(s); current tree: ${current.size} skill(s).`);
-  if (missing.length || extra.length) {
-    if (missing.length) console.error(`Missing from current tree: ${missing.join(', ')}`);
-    if (extra.length) console.error(`Not present in release tag: ${extra.join(', ')}`);
-    process.exit(1);
+  const additionsLine = formatAdditions(comparison.additions);
+  if (additionsLine) console.log(additionsLine);
+  if (comparison.exitCode !== 0) {
+    console.error(`Missing from current tree: ${comparison.missing.join(', ')}`);
+    process.exit(comparison.exitCode);
   }
 
   let references = 0;
@@ -140,7 +154,10 @@ function main() {
     console.error(`CURRENT RELEASE CHECK FAILED: ${currentReferences.failures.length} dangling reference(s).`);
     process.exit(1);
   }
-  console.log(`RELEASE SKILL CATALOG PASSED for ${tag}; current source has the same logical skill catalog (${tagRoot.length} release entries, ${current.size} current directories after merges).`);
+  const additionLabel = comparison.additions.length === 1 ? 'addition' : 'additions';
+  console.log(`RELEASE SKILL BASELINE PASSED for ${tag}: all ${tagRoot.length} release-tag skills remain present; current source has ${current.size} skill(s), including ${comparison.additions.length} ${additionLabel} not yet in the tag.`);
 }
 
 if (require.main === module) main();
+
+module.exports = { compareSkillCatalogs, formatAdditions };

package/ci/release-consistency-check.test.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const assert = require('assert');
+const { compareSkillCatalogs, formatAdditions } = require('./release-consistency-check');
+
+const addedSkill = compareSkillCatalogs(
+  ['existing-skill'],
+  ['code-review', 'existing-skill']
+);
+assert.deepStrictEqual(addedSkill.missing, [], 'a release-tag skill must remain present');
+assert.deepStrictEqual(addedSkill.additions, ['code-review']);
+assert.strictEqual(addedSkill.exitCode, 0, 'an extra current skill is informational');
+assert.strictEqual(formatAdditions(addedSkill.additions), 'Additions since release tag: code-review');
+
+const missingSkill = compareSkillCatalogs(
+  ['existing-skill', 'removed-skill'],
+  ['existing-skill']
+);
+assert.deepStrictEqual(missingSkill.missing, ['removed-skill']);
+assert.strictEqual(missingSkill.exitCode, 1, 'a released skill missing from current source must fail');
+
+const renamedSkill = compareSkillCatalogs(
+  ['build-multi-agent-system'],
+  ['multi-agent-workspace']
+);
+assert.deepStrictEqual(renamedSkill.missing, [], 'the established rename must satisfy the released entry');
+assert.deepStrictEqual(renamedSkill.additions, [], 'a rename must not be reported as a new addition');
+assert.strictEqual(renamedSkill.exitCode, 0);
+
+console.log('Release consistency catalog additions, missing-skill failures, and rename mapping verified.');

package/ci/router-workflow-plan.test.js

@@ -27,6 +27,12 @@ function check(condition, message) {
   }
 }
 
+function reviewBindingIds(run) {
+  const text = `${run.result.stdout || ''}\n${run.result.stderr || ''}`;
+  const line = text.match(/Candidate step binding ids: ([^\r\n]+)/);
+  return line ? line[1].split(',').map(id => id.trim()).filter(Boolean) : [];
+}
+
 function runTier(prompt, options = {}) {
   const contractPath = path.join(os.tmpdir(), `harness-router-test-${process.pid}-${Math.random().toString(16).slice(2)}.json`);
   const context = options.context || null;
@@ -91,6 +97,36 @@ if (validContract(iterative, 'iterative-single')) {
   check(!plan.requiredInvariants.includes('tdd'), 'binding ids remain step-local rather than workflow invariants');
 }
 
+const reviewPositives = [
+  'Review PR #412 before we merge it',
+  'Review pull request #412',
+  'Review this PR before merge',
+  'Review the diff',
+  'Review the implementation',
+  'Re-review the fix at the new HEAD',
+];
+const reviewNegatives = [
+  'review project plan',
+  'review proposal',
+  'review process',
+  'preview pr environment',
+  'Review this proposal',
+  'Review the project plan',
+  'Review my process',
+  'Re-review the problem statement',
+  'Review my implementation plan, ask one question at a time',
+  'Preview the diff rendering',
+  'Preview PR #412 environment',
+];
+for (const prompt of reviewPositives) {
+  const run = runTier(prompt);
+  check(reviewBindingIds(run).includes('code-review'), `review signal: ${JSON.stringify(prompt)} yields the code-review candidate`);
+}
+for (const prompt of reviewNegatives) {
+  const run = runTier(prompt);
+  check(!reviewBindingIds(run).includes('code-review'), `review signal: ${JSON.stringify(prompt)} stays code-review-free`);
+}
+
 const memoryPersist = runTier('Persist this lesson as memory after resolving the checkout regression.');
 if (validContract(memoryPersist, 'self-evolve persistence')) {
   const plan = memoryPersist.contract.workflowPlan;

package/code-review/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: code-review
+description: "Independently review a PR, diff or finished implementation for correctness, contract and negative-path defects, with source-anchored findings labelled executed, source-traced or inconclusive; read-only by default. USE FOR: \"review this PR before merge\", \"re-review the fix at the new HEAD\". DO NOT USE FOR: \"security threat modeling\", \"implementing or fixing the code\"."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.33.0
+---
+
+# Code Review
+
+Independently review completed changes for correctness, contract violations, and negative-path defects. Default to read-only.
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Requested review of a PR, diff, implementation, or revised HEAD. |
+| **Expected Output** | Source-anchored findings and an evidence-qualified summary. |
+| **State Mutations** | None unless the user explicitly authorizes an action. |
+| **Enforcement Gate** | Apply the checklist in `<this-skill-dir>/references/review-playbook.md`. |
+
+## USE FOR:
+- Review a PR / diff / finished implementation before merge
+- Re-review a revised HEAD: prior-finding disposition + new risks
+
+## DO NOT USE FOR:
+- Security-only threat modeling / secrets / OWASP (use `security-review`)
+- Design or plan stress-testing (use `grill-me`); running gates (use `verification-loop`); writing the fix (use `tdd`)
+
+## Workflow
+
+1. Pin repository, contract, base/head, changed scope, and CI state; inspect relevant callers and consumers.
+2. Independently trace behavior and test applicable counterexamples. Separate severity from safety conditions.
+3. Report only supported findings with evidence tier, smallest correction, regression, and positive control. Use `<this-skill-dir>/templates/finding.template.md`.
+4. On re-review, disposition every prior finding at the new HEAD, then inspect for regressions.
+5. Keep review read-only unless explicitly authorized. Do not claim “bug-free.”
+
+In the interim, bind explicitly on an existing review step: `{"stepType":"review","optionalBindings":["code-review"]}`.
+
+Deep dive: <this-skill-dir>/references/review-playbook.md

package/code-review/references/review-playbook.md

@@ -0,0 +1,40 @@
+# Review Playbook
+
+Use this checklist for the applicable risks; do not force irrelevant categories.
+
+## Establish scope and evidence
+
+- [ ] Pin repository, PR, base/head SHA, user requirement or PRD/ADR, changed files, relevant callers/callees, and current CI state. Avoid unrelated checkout areas.
+- [ ] Make an independent pass. Treat author explanations and tests as leads, not proof; derive expected behavior from contracts and source.
+- [ ] Label evidence honestly: **executed/reproduced** (command, result, environment, SHA); **source-traced** (concrete path and preconditions); **inconclusive** (missing facts or ambiguous semantics; do not present as a proven blocker).
+- [ ] Inventory user-facing entry points and configuration handoffs (CLI flags, cwd, path spellings, config loading). Exercise them end-to-end, not only the recently edited internals.
+- [ ] Reproduce a candidate finding against the PR base before classifying it as new. Pre-existing defects are follow-ups, not new blockers.
+
+## Try applicable counterexamples
+
+- [ ] Missing, null, malformed input; old persisted state; base-to-candidate transitions; tenant/scope boundaries.
+- [ ] Missing or broken dependencies: enumerate every entry point, including help, recovery, and stop paths; inspect fallback behavior.
+- [ ] OS/shell differences; concurrency, crash, retry; user paths and symlinks; API/migration compatibility; downstream or generated views.
+- [ ] Follow each important diagnostic/fact through every consumer and ancestor. Check whether required facts are computed before derived authority, indexes, or output.
+- [ ] Compare new rules with previously accepted rules and controls. Separate display severity from safety prerequisites.
+
+## Check tests and output
+
+- [ ] Ask whether each test still passes if the behavior is disabled, bypassed, or broken (mutation thought experiment). Confirm the test is included in CI.
+- [ ] When output text changes, compare the intended changed lines with literal templates; do not exclude changed lines from assertions.
+- [ ] Dedupe findings. Use P1 for severe merge blockers, P2 for meaningful correctness/contract defects, P3 for low-risk issues; avoid speculation.
+- [ ] For each finding, include exact path:line or diff anchor at HEAD SHA, trigger, observed behavior, violated contract and impact, evidence tier, smallest fix, negative regression, positive control, and disposition.
+
+## Re-review and conclude
+
+- [ ] Pin the new HEAD. Disposition every prior finding separately: resolved, still open, superseded, or inconclusive. Then inspect fix-induced side effects and new changes.
+- [ ] Stay read-only unless the user/workflow explicitly authorizes action. Do not edit, comment, label, or merge on review authority alone.
+- [ ] Summarize scope/SHA, CI, covered and unexamined risks, fixed/open/new counts, and evidence-grounded merge recommendation. “No actionable findings in examined scope” does not mean “bug-free.” Distinguish repository tests from live-host evidence.
+
+## Per-finding format
+
+`[P1/P2/P3] Title` — `path:line @ <HEAD SHA>`
+
+**Trigger** → **behavior** → **contract violation / impact**. **Evidence:** executed / source-traced / inconclusive. **Minimal correction:** … **Regression:** negative case …; positive control … **Disposition:** blocker / follow-up / owner decision.
+
+Use `<this-skill-dir>/templates/finding.template.md` for the complete findings and summary form.

package/code-review/templates/finding.template.md

@@ -0,0 +1,33 @@
+# Code Review — <PR or change>
+
+## Scope and evidence
+
+- Repository / PR:
+- Base SHA → reviewed HEAD SHA:
+- Requirement / PRD / ADR:
+- Changed files and relevant callers/consumers:
+- CI state and commands observed:
+- Counterexample categories covered:
+- Risks not examined / evidence limits:
+
+## Findings
+
+### [P1/P2/P3] <Short, specific title>
+
+- **Location:** `<path>:<line or diff anchor> @ <HEAD SHA>`
+- **Trigger:** <minimal input, state transition, or interleaving>
+- **Behavior → impact:** <observed or source-traced behavior and violated contract>
+- **Evidence tier:** <executed/reproduced | source-traced | inconclusive; include exact command/result or preconditions>
+- **Minimal correction:** <smallest feasible fix>
+- **Regression:** Negative case: <case that fails before fix>; positive control: <valid behavior that remains valid>
+- **Disposition:** <blocker | follow-up | owner decision; for re-review, resolved | still open | superseded | inconclusive>
+
+<!-- Duplicate this finding section as needed. Remove headings for which there are no findings. -->
+
+## Summary
+
+- **Scope / reviewed SHA:**
+- **CI evidence:**
+- **Covered / unexamined risks:**
+- **Findings:** <fixed / open / new counts on re-review>
+- **Conclusion:** <merge recommendation grounded in evidence; “no actionable findings in examined scope” is not a claim of bug-free code>

package/docs/document-lifecycle.md

@@ -0,0 +1,206 @@
+# Document Lifecycle Contract (#325)
+
+Contract for the documentation family: project docs configuration (D5), document roles and revision metadata (D6.1–D6.3), domain-scoped IDs (D6.8) and the generated index. Owner decisions live in [#325](https://github.com/dyphn1/Harness-everything/issues/325); this file is the implementation contract that tests cite.
+
+Documentation is a **consumer** of the #320 workflow/obligation abstractions. Nothing here is a second router, a standing maintenance loop or a cognitive lock: every check is a pure function that reports diagnostics.
+
+## Scope of this slice
+
+| Phase | Status here |
+| --- | --- |
+| 0 — contract + RED fixtures | This file; fixtures under `ci/fixtures/doc-lifecycle/` |
+| 1a — `project-docs.json` loader | `multi-agent-workspace/scripts/project-docs-resolver.js` |
+| 2 — roles, IDs, aliases, legacy, supersession, index, D6.9 PRD revisions | `harness-everything/scripts/doc-lifecycle.js` |
+| 1b, 3 (`doc-change`, `requirement-sync`) | Not started: blocked by #320 family metadata, D1 obligation schema and D3 evidence states |
+| 4 — derived-view generators, `describes:` drift | Not started |
+
+## Configuration (D5)
+
+| Source | Rule |
+| --- | --- |
+| `.agents/harness-everything/project-docs.json` | Committed, host-neutral. When present it **wholly overrides** host-manifest `projectDocs` (no field merge); warn `project-overrides-host` when a host value differs |
+| Invalid project file | Status `invalid` with diagnostics; no fallback to host manifests; config-dependent MUSTs report unresolved |
+| No project file, active host known and declares `projectDocs` | Status `host`; record that manifest as the source |
+| No project file, active host known but its manifest has no `projectDocs` | **Owner decision 2026-10-17:** `none`, recording the active host; never inherit another host's config. Warn and suggest `project-docs.json` |
+| No project file, host unknown | All declaring hosts canonically equal → `host` (all sources recorded); they differ → `ambiguous`; none → `none` |
+| AGENTS.md | Never a configuration source |
+
+- Canonical comparison: object keys sorted recursively, array order preserved, whitespace irrelevant.
+- The project file may also carry the existing zone fields (`decisionLocation`, `domainLocation`, `architectureLocation` and their aliases). Zone resolution uses the project file when present, so the override is total.
+- Host manifests that fail to parse are skipped with an `invalid-host-config` diagnostic naming the source; they never count as agreeing or disagreeing.
+- **Generator security (MUST):** reading or validating config never executes `derived[].generator`. Execution belongs to an authorized verification step only.
+
+```json
+{
+  "governed": [
+    { "path": "docs/prd/**", "role": "prd" },
+    { "path": "docs/adr/**", "role": "adr" }
+  ],
+  "domains": ["GRPH", "IFCE"],
+  "legacy": ["docs/adr/legacy/**"],
+  "derived": [{ "path": "docs/roadmap/index.md", "generator": "npm run docs:index" }],
+  "tickets": "tracker"
+}
+```
+
+| Field | Validation |
+| --- | --- |
+| `governed` | Array of `{ path: glob, role }`; `role` from the fixed vocabulary below |
+| `domains` | Array of unique `^[A-Z][A-Z0-9]{1,9}$`. Reserved for ID prefixes: a legacy string value in a host manifest is read as `domainLocation` with a `deprecated-domains-string` warning; in `project-docs.json` it is a schema error |
+| `legacy` | Array of globs |
+| `derived` | Array of `{ path, generator }`, both non-empty strings |
+| `tickets` | `"tracker"` or a repo-relative path |
+| Unknown keys | Warning, not error |
+
+Globs are repo-relative POSIX paths supporting `*` (one segment) and `**` (any depth).
+
+## Roles and status (D6.1, D6.3)
+
+| Role | Status vocabulary | `id` |
+| --- | --- | --- |
+| `prd` | `draft` / `approved` / `effective` / `rejected` / `withdrawn` (D6.9); pre-migration `active` / `superseded` warn unchanged and error when added or changed | Required: `PRD-<DOMAIN>-NNN` plus `revision` (D6.9) |
+| `adr` | `proposed` / `accepted` / `rejected` / `superseded` | Required: `<DOMAIN>-NNN` |
+| `ticket` | `open` / `blocked` / `done` / `withdrawn` | Optional |
+| `reference` | `active` / `deprecated` | Optional |
+| `log`, `report` | `final` / `archived` | Optional |
+
+- Role comes from the first matching `governed` entry; a frontmatter `role` must agree with it.
+- **Legacy immutability:** Legacy files remain outside the active ID namespace. With an observed trusted base, a path is frozen only when some base source's `legacy` matches it and no base source positively governs it after that source's own legacy exclusion; parsed frontmatter stays deep-equal while body/editorial/link edits remain allowed. A surviving path is reclassified when it is no longer legacy under the same per-source rule for candidate sources and emits `legacy-frozen-modified`; deletion/move relies on existing escalation for surviving explicit `legacy:ID@path` references. Without a trusted base, legacy immutability is not-observed or unavailable.
+- Frontmatter fields: `id`, `role`, `status`, `supersedes`, `aliases`. `superseded_by` and `amends` are not stored; `superseded_by` is derived in the index.
+- **Ratchet:** schema checks (role/status/ID) apply to governed files named in `changedPaths`. Full mode is explicit (`--all` / `{ all: true }`); the CLI refuses to run without `--changed`, `--changed-path` or `--all`. Cross-file integrity diagnostics are errors when any involved file is changed (deleted and renamed paths count as changed), warnings otherwise. Warnings that affect resolution still appear in the index's unresolved list. CLI `--changed` entries resolve against `--workspace`, normalize to repo-relative POSIX paths, and fail as usage errors when outside the workspace; `--changed` takes one comma-separated argument and cannot represent filenames containing commas, so repeat `--changed-path <path>` (one occurrence per path, never comma-split, normalizes and resolves like the CSV form, and mutually exclusive with `--all`; may be combined with `--changed`) when a filename contains a comma. Occurrences of either changed selector accumulate: repeated `--changed` or `--changed-path` flags add to the changed set instead of overwriting earlier declarations. The CSV form trims whitespace around its comma-separated items; `--changed-path` preserves commas and outer whitespace while resolving paths and normalizing separators. Both `/` and `\` are separators on every host; literal backslashes in POSIX filenames cannot be selected through these CLI flags — use `--all` or the API `changedPaths` for those files. Relative `--config` paths also resolve from `--workspace`. Without a trusted base, escalation for deleted or renamed targets covers explicit `legacy:ID@path` selectors only; ID-only references escalate when a trusted base (`--base` or a supplied inventory, see D6.9) maps the ID to a changed path.
+- Parsing conventions: role comes from the first matching `governed` entry; frontmatter is the leading `---` block in a YAML subset (scalars, inline `[a, b]` lists, `- a` block lists); references inside fenced code blocks are ignored.
+
+## IDs, aliases and references (D6.2, D6.8)
+
+- ADR: `<DOMAIN>-NNN` (three or more digits). REQ: `REQ-<DOMAIN>-NNN`, defined only in a PRD as a heading `REQ-<DOMAIN>-NNN` at the start of a Markdown heading line (`### REQ-GRPH-012: …`).
+- **REQ aliases — owner decision 2026-10-17:** declared on the REQ heading itself, `### REQ-GRAPH-012 (aliases: REQ-GRPH-012, REQ-GRPH-099): title`. Each alias resolves directly to that REQ; collision rules match document aliases. Document-level `aliases` never rename REQs.
+- `DOMAIN` must be declared in `domains`. Aliases keep their historical domain, which need not be declared.
+- `aliases: [...]` lists every previous ID; each alias resolves **directly** to the declaring document. Reject duplicate canonical IDs, an alias equal to another active canonical ID or alias, and unresolved references.
+
+| Reference | Resolution |
+| --- | --- |
+| `GRPH-007` | Active canonical IDs and aliases only; never falls through to legacy |
+| `legacy:GRPH-007` | The unique legacy document with that ID. Several matches → `ambiguous-legacy-ref` listing every candidate path; never the first match |
+| `legacy:GRPH-007@docs/adr/legacy/v2/GRPH-007.md` | **Owner decision 2026-10-17:** the repo-relative path is the archive discriminator; resolves only when that file is legacy and carries that ID |
+
+Selector grammar: `legacy:` + ID, optionally `@` + path, split at the **first** `@`. The path is a repo-relative POSIX path compared byte-exactly with the collected path (case-sensitive on every OS). Backslashes, leading `/`, drive letters, `.` or `..` segments, and paths outside the workspace are `invalid-ref`; they are never normalized into a match. A renamed archive path leaves old selectors `unresolved-ref` until updated.
+
+- A legacy document's ID is its frontmatter `id`, else its file stem when that matches an ID pattern. Duplicate legacy IDs are allowed; only bare references to them are ambiguous.
+- An active alias equal to a legacy ID is allowed (the rename case).
+- Aliases are strings matching an ADR or REQ ID pattern. The `legacy:` prefix is reserved for references and is `invalid-alias` inside `aliases`, as are self-aliases and non-strings.
+
+## Supersession (D6.3, D6.4)
+
+- `supersedes` is written on the new document and means real normative replacement, never an identity rename.
+- Active target: the target must carry `status: superseded`, else `supersede-status-mismatch`. This is the only required two-file edit.
+- **Legacy target — owner decision 2026-10-17 (external projection):** reference it with an explicit `legacy:` ref that resolves uniquely. The legacy file is never edited; the generated index projects its status as superseded by the active document. This is the explicit legacy exception to both the D6.3 two-file lint and the D6.6 "ADR superseded → old status `superseded`" event: for legacy targets the obligation is met by the projection. The index shows the stored status and the projected effective status side by side, with the source edge.
+- A plain ref that matches only a legacy ID is `unresolved-ref` with a hint to use `legacy:`.
+- Self-supersession and supersession cycles are errors.
+- **Branching and eligibility — owner decision 2026-10-17:** a target may have several successors; the index lists them sorted. Only edges from an `accepted` ADR or an `active` PRD are effective: they require the active target's `superseded` status and drive legacy projection. Edges from other statuses (`draft`, `proposed`, …) are shown as pending, do not require the target's status change, and do not project.
+- Only explicit `supersedes` or a recorded owner decision resolves a conflict.
+- **Recorded conflicts — owner decision 2026-10-17:** semantic PRD/ADR contradictions are not detected from prose. Whoever finds one records `conflicts_with: [<ID>]` on either document; the pair stays in the unresolved list (`recorded-conflict`, both IDs and paths) until an effective `supersedes` between them exists. Owner adjudication is recorded by that `supersedes` edge or by removing the entry in the same change that updates the canonical document. Structural conflicts are detected automatically.
+
+## Diagnostics
+
+Each diagnostic is `{ code, severity, path, id?, message, candidates? }`, sorted by `path`, `code`, `id`, then `message`.
+
+Anchors for cross-file diagnostics: `supersede-*`, `unresolved-ref`, `ambiguous-legacy-ref`, `invalid-ref` and `recorded-conflict` attach to the document that declares the reference or edge. `legacy-frozen-modified` attaches to the trusted-base archive path. `duplicate-id`, `alias-collision` and `duplicate-req` emit one diagnostic on **every** involved document, each listing the others in `candidates`.
+
+| Code | Trigger |
+| --- | --- |
+| `malformed-frontmatter` | Unparseable frontmatter block |
+| `role-mismatch` | Frontmatter `role` differs from path role |
+| `missing-status` / `invalid-status` | Status absent or outside the role vocabulary |
+| `missing-id` / `invalid-id` / `unknown-domain` | ADR ID absent, malformed, or domain undeclared |
+| `duplicate-id` | Two active documents share a canonical ID |
+| `alias-collision` | Alias equals another active canonical ID or alias |
+| `duplicate-req` / `missing-req` | REQ defined twice in active PRDs, or referenced in a governed doc but never defined |
+| `unresolved-ref` / `ambiguous-legacy-ref` / `invalid-ref` | Reference resolves to nothing, to several legacy documents, or is malformed |
+| `legacy-frozen-modified` | With a trusted base, legacy frontmatter changed or a surviving archive was reclassified out of legacy scope (error) |
+| `invalid-alias` | Alias is not a string ID, is self-referential, or uses the reserved `legacy:` prefix |
+| `invalid-host-config` | A host manifest's `projectDocs` failed to parse or validate |
+| `supersede-status-mismatch` / `supersede-cycle` | Effective edge to an active target that is not `superseded`; self or cyclic supersession |
+| `recorded-conflict` | `conflicts_with` pair without an effective `supersedes` between them |
+
+## Contract-style PRD revisions (D6.9)
+
+**Owner direction 2026-10-17:** an effective PRD is a contract. A change creates a new **complete** revision copied from the current effective revision; the effective snapshot is never edited in place. This replaces the D6.1 "living PRD" model for PRDs only; ADRs, tickets and other roles are unchanged. Where this section conflicts with earlier PRD rules (optional PRD `id`, PRD status vocabulary, PRD `supersedes`), this section wins.
+
+### Identity and graph
+
+| Concept | Rule |
+| --- | --- |
+| Logical PRD | `id: PRD-<DOMAIN>-NNN`, shared by every revision; grouped by canonical identity (aliases preserved) |
+| Revision | `revision: <N>` positive integer, no leading zeros; canonical form `PRD-GRPH-001@r3` |
+| Parent | `previous_revision: <N>`; must name an existing revision of the same logical PRD with a smaller number. Exactly one baseline (no parent) per logical PRD |
+| Layout | Not mandated (recommended `docs/prd/<slug>/r003.md`); identity comes from frontmatter only |
+| Uniqueness | `(logical id, revision)` unique. Repeated logical IDs and inherited aliases across revisions are not `duplicate-id` / `alias-collision` |
+
+### Status, approval, activation
+
+| Stored status | Editable | Notes |
+| --- | --- | --- |
+| `draft` | Yes | Never authoritative; drafts may fork |
+| `approved` | Activation fields only | Approval bound to content |
+| `effective` | **No**, from the change that sets it | Frozen artifact |
+| `rejected` / `withdrawn` | Not enforced in this slice | Never selectable as current |
+
+- **Approval record (owner decision 2026-10-17):** `approval: { by, at, ref, content_digest }`. `by` is a human or an independent cold verifier, never the drafting agent. `ref` is a URL or an in-repo record path (offline-checkable). `content_digest` covers the revision body plus non-activation frontmatter; a content edit after approval invalidates it (`approval-content-mismatch`).
+- **Activation:** sets `status: effective` and `effective_at`; only these fields may change between `approved` and `effective`. The file path must also stay the same as in the trusted approved baseline. An `approved` revision is frozen except for activation; any other edit, including rebinding `approval`, requires returning it to `draft` and re-approving (`invalid-transition`). Deleting an approved revision or moving it outside the candidate inventory is also an `invalid-transition`. Timestamps are ISO 8601 with timezone; `effective_at` must not precede `approval.at`. Activation requires the parent to be the current effective revision (`stale-draft-base`).
+- **Current effective** is derived after validating the whole graph: a connected chain of `effective` revisions from the baseline; two effective children of one parent → `revision-fork`; no effective revision → explicit pre-activation state. Older effective revisions are derived `historical`; their files are never edited.
+
+### Digests and evidence envelope
+
+- **Stored bytes:** the bytes Git stores for the file (after `git add` end-of-line normalization). Base content comes from the trusted base tree; candidate content is normalized the same way. Comparisons may use Git blob object IDs; frontmatter digests are `sha256:<hex>` over stored bytes. Pure API callers pass stored bytes directly.
+- **Artifact digest** (`previous_digest`, immutability): sha256 over the complete stored bytes of the revision file.
+- **Approval content digest** (`approval.content_digest`): sha256 over `JSON(frontmatter without status, effective_at, approval; keys sorted; UTF-8) + "\n" + body` (body in stored bytes). Excluding `approval` avoids self-reference; excluding activation fields lets activation keep the digest valid.
+- **Independence:** `drafted_by` (required on `approved` and `effective` revisions; missing → `approval-missing`) names the drafting author; `approval.by` equal to `drafted_by` → `approval-not-independent`. `approval.role` is `human` or `cold-verifier`. The checker verifies the record's presence, binding and independence, not that a review actually happened.
+- **Evidence envelope:** `analyzeDocs(docs, config, opts)` returns `{ diagnostics, evidence }` with `evidence.immutability` = `observed` | `not-observed` | `unavailable`. `lintDocs` stays the diagnostics-only projection. CLI JSON prints the envelope; exit 1 only for error diagnostics, and `not-observed` is always printed, never folded into success.
+- **Offline base inventory:** `analyzeDocs(docs, config, { baseInventory: [{ id, revision, path, status, bytes }] })` supplies stored baseline bytes for offline checks. For Git-equivalent legacy freezing, supply either per-entry boolean `legacy` classifications computed under the per-source rule or `baseConfigSources`; when both are supplied, `baseConfigSources` takes precedence and applies the source rule. The supplied historical sources also govern migration checks, REQ identity lookup, and changed-scope calculations. Without either, legacy classification is not established for unflagged rows, which are not frozen, and `evidence.legacyImmutability` reports `not-observed` while byte-based `evidence.immutability` remains `observed`. Candidate classification uses `options.configSources` when supplied, otherwise `config`; equivalent trusted bytes and authority inputs must yield the same diagnostics as `--base`.
+- Tests isolate Git (no global/system config, hooks, templates or signing; explicit `core.autocrlf` and attributes) and compute expected digests independently of the system under test.
+
+### Immutability evidence
+
+- **Byte basis (owner decision 2026-10-17):** digests use the repository-stored content (Git blob bytes, or an exported snapshot of them), so checkout line-ending conversion cannot change identity.
+- `previous_digest` in each revision is an **internal consistency** check only; editing a parent and its child's digest together stays self-consistent.
+- **Immutability** needs a trusted baseline: CLI `--base <git-rev>` or a supplied snapshot inventory. Base and candidate inventories are compared by `(logical id, revision)` and by path: a base-effective revision must remain present with identical bytes regardless of status edits, moves, deletions or config exclusions (`immutable-revision-modified`, `immutable-revision-deleted`). Without a trusted baseline the result is `not-observed`, never pass. The immutability scope is the **union** of governed, legacy and PRD globs from the current config and from every config source in the base tree (`project-docs.json`, each host manifest's `projectDocs`, and the base copy of an explicit `--config` path); narrowing the current config never removes a base-effective revision from checking. Stored-byte normalization follows Git's text/binary decision (including NUL detection for `text=auto` and for `core.autocrlf` without attributes); content Git stores unchanged is compared unchanged. Git is read with argument arrays, never shell interpolation; missing history is never fetched.
+
+### REQ continuity
+
+- Every REQ of the parent appears in the child unless accounted for by `removed_reqs: [...]` or a `replaces` edge; otherwise `req-dropped`. Each REQ block needs non-empty acceptance content (`incomplete-snapshot`). ID continuity is structural evidence only; semantic completeness still needs review.
+- Unchanged and editorial REQs keep their IDs. A REQ whose text changed is reported as changed and needs a review classification (normative vs editorial); IDs are never recycled for unrelated meaning.
+- Heading clauses: `### REQ-GRPH-020 (replaces: REQ-GRPH-012, REQ-GRPH-013; aliases: REQ-GRAPH-020): title`. Clauses are `;`-separated, comma lists, each at most once; unknown or duplicate clauses are errors. `replaces` allows splits and merges; a REQ ID may not be both alias and replaced target; replacement cycles are errors.
+- `duplicate-req` applies within each revision and across the current effective revisions of different logical PRDs.
+- Plain `REQ-…` resolves only in current effective revisions; a removed or replaced REQ is `unresolved-ref` with a historical/replacement hint, never auto-followed.
+
+### References
+
+| Ref | Resolves to |
+| --- | --- |
+| `PRD-GRPH-001` | Current effective revision |
+| `PRD-GRPH-001@r2` | Exactly revision 2, returned with status, digest and provenance |
+| `PRD-GRPH-001@r2#REQ-GRPH-012` | That REQ inside revision 2 (aliases resolved as of r2) |
+
+- Parse the namespace first: `legacy:` refs keep their exact path grammar; `@r<N>` and `#REQ` apply only to PRD logical IDs. Whole-token anchored parsing; a valid prefix of an invalid ref never resolves.
+- Pins to `draft`/`approved` revisions are provisional and never satisfy governed-implementation evidence; audit evidence pins an effective revision plus its digest.
+
+### Cross-PRD replacement and migration
+
+- **Retirement eligibility:** only an `effective` source revision retires a target or resolves a recorded conflict; edges from `draft`/`approved`/`rejected` revisions are pending (same rule as ADR effective edges).
+- **Retirement is a historical event (owner decision 2026-10-17):** once any revision that was effective declares the edge, the target stays retired even if later revisions of the source omit it; omission never revives a target. The index records the revision that issued the retirement.
+- **Retirement (owner decision 2026-10-17):** `supersedes: [PRD-GRPH-001@r4]` on another logical PRD retires that contract by external projection, like legacy targets: no file is edited, splits and merges are allowed, the exact source/target revisions are recorded, and the retired PRD stays addressable.
+- **Baseline adoption (owner decision 2026-10-17):** an existing non-legacy living PRD gets one reviewed metadata-only edit adding `revision: 1`, approval and a `migrated_from_digest` of its prior content, recorded in a migration record. The baseline frontmatter names the record with `migration_record: <repo-relative path>`; the record is JSON `{ record: "prd-baseline-migration", id, revision, source, migrated_from_digest, approved_by }` and must match the frontmatter and the base content of `source` (`migration-record-missing` / `migration-record-mismatch`). `baseline` status never exempts later edits. Legacy PRDs stay frozen outside the graph.
+
+### Diagnostics (D6.9)
+
+`invalid-prd-id`, `invalid-revision`, `duplicate-revision`, `missing-parent`, `multiple-baselines`, `revision-cycle`, `revision-fork`, `stale-draft-base`, `invalid-transition`, `approval-missing`, `approval-content-mismatch`, `revision-digest-mismatch`, `immutable-revision-modified`, `immutable-revision-deleted`, `req-dropped`, `incomplete-snapshot`, `invalid-req-clause`, `replacement-alias-overlap`, `replacement-cycle`. `not-observed` is an evidence disposition, not a diagnostic and not a pass.
+
+## Packaging
+
+Source checkout, Codex plugin and Claude plugin copy whole skill trees. Callers locate `doc-lifecycle.js` and the resolver relative to their own skill directory, never the source-tree root. A to-spec-only install must use the same resolver implementation (copied byte-identically and checked), and a broken shared module is an error, never a silent fallback to older host scanning.
+
+## Generated index
+
+`buildIndex` returns Markdown with no timestamps or environment data, so two runs over the same tree are byte-identical. Sections: active documents (sorted by ID then path, with derived `superseded by`), legacy documents (sorted by ID then path, with projected status), and the unresolved list (resolution-affecting error diagnostics).
+
+The shared `AUTHORITY_BLOCKER_DIAGNOSTICS` taxonomy covers `invalid-prd-id`, `invalid-revision`, `invalid-status`, `invalid-alias`, `duplicate-revision`, `missing-parent`, `multiple-baselines`, `revision-cycle`, `revision-fork`, `revision-digest-mismatch`, `req-dropped`, `incomplete-snapshot`, `invalid-req-clause`, `duplicate-req`, `replacement-alias-overlap`, `replacement-cycle`, `approval-missing`, `approval-not-independent`, `approval-content-mismatch`, `invalid-transition`, `stale-draft-base`, `migration-record-missing`, `migration-record-mismatch`, `immutable-revision-modified`, `immutable-revision-deleted`, `legacy-frozen-modified`, `duplicate-id`, `alias-collision`, `unknown-domain`, `invalid-id` and `role-mismatch`. Retirement eligibility uses the validated effective prefix and blocks on these authority findings regardless of ratchet severity; this prevents a known identity, alias or REQ collision from authorizing a new retirement. Namespace and REQ collisions are computed before the final prefix and supersession/conflict projection. Index current-state display uses the same blocker taxonomy with error severity: an error on the graph-selected current revision or a required effective ancestor produces `state: invalid; current: none`, while warnings stay visible in Unresolved without revoking `valid/current`. A pending descendant cannot discard an earlier valid effective prefix or its historical retirement event. The unresolved list also includes resolution diagnostics `malformed-frontmatter`, `missing-id`, `missing-req`, `unresolved-ref`, `ambiguous-legacy-ref`, `invalid-ref`, `missing-status`, `supersede-status-mismatch`, `supersede-cycle`, `recorded-conflict` and `prd-migration-required`; these remain visible at their reported severity but do not themselves block retirement eligibility or current-state display. When `buildIndex` receives no `diagnostics`, it runs `analyzeDocs` with the supplied options (including trusted-base inputs) and renders that result; callers that provide precomputed diagnostics must provide diagnostics from the same analysis context, with its graph and validated-prefix set, for equivalent retirement and current-state output.

package/docs/openai-plugin.md

@@ -74,7 +74,7 @@ The local package path is distinct from the general `--codex` installer. The gen
 The package tests prove the following repository-side contract:
 
 - the portable root manifest and `.codex-plugin` compatibility manifest agree on identity, version, interface, and hook entry point;
-- the root `skills/` tree contains exactly the 26 canonical skills;
+- the root `skills/` tree contains exactly the 27 canonical skills;
 - Windows and POSIX hook commands resolve through `PLUGIN_ROOT`;
 - session start emits the compact policy and prompt submission invokes invariant-first routing;
 - supported local `Bash` and `apply_patch` calls receive the packaged guards and state tracking;