harness-everything 0.11.6 → 0.12.0

package/plugins/harness-everything/skills/to-spec/templates/feature-spec.md

@@ -56,4 +56,18 @@ A description of the things that are out of scope for this spec.
 
 Any further notes about the feature.
 
+## Contract Requirements
+
+For every normative behavior this document owns, assign a stable requirement identity:
+
+```md
+### REQ-001 — <short behavior name>
+**Status:** CURRENT
+**Revision:** 1
+**Decision lineage:** ADR-0001 (or None)
+<observable behavior / acceptance boundary>
+```
+
+Do not recycle requirement IDs. When approved behavior changes, increment the revision and reconcile the living spec before implementation completion.
+
 </spec-template>

package/plugins/harness-everything/skills/to-spec/templates/schema-doc.md

@@ -28,4 +28,18 @@ What breaks for existing consumers, if anything, and what the mitigation is (dua
 
 One realistic, complete example instance of the schema.
 
+## Contract Requirements
+
+For every normative schema behavior this document owns, assign a stable requirement identity:
+
+```md
+### REQ-001 — <short behavior name>
+**Status:** CURRENT
+**Revision:** 1
+**Decision lineage:** ADR-0001 (or None)
+<observable validation, compatibility, or migration contract>
+```
+
+Do not recycle requirement IDs. A changed schema/validation contract increments the revision before implementation completion.
+
 </spec-template>

package/plugins/harness-everything/skills/to-tickets/SKILL.md

@@ -4,7 +4,7 @@ description: Break a to-spec feature-spec, a plan, or a conversation into tracer
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.12.0
 ---
 
 # To Tickets

package/plugins/harness-everything/skills/to-tickets/references/publishing-and-templates.md

@@ -48,6 +48,19 @@ Give each ticket its **blocking edges** — the other tickets that must complete
 
 **Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there.
 
+# Contract lineage and change impact
+
+When a ticket comes from an authoritative spec, it must carry the exact source requirement identity and revision. A ticket may refine implementation scope, but it never silently rewrites the approved contract.
+
+Every ticket must classify its impact:
+
+- **none** — bookkeeping/non-behavioral work; explain why no contract changes.
+- **implementation** — implementation changes while approved behavior and architectural rationale stay unchanged.
+- **behavior** — caller/user-visible behavior changes. Update the living spec requirement and revision first, then obtain requirement-linked RED evidence before accepting implementation.
+- **architecture** — a hard-to-reverse decision/rationale changes. Publish a new/superseding ADR, update the living spec requirement/revision, then obtain RED evidence.
+
+If the impact classification changes during implementation, stop treating the original ticket as completion authority. Reconcile the source artifacts first, then update the ticket's source revision.
+
 # Ticket Templates
 
 <local-ticket-template>
@@ -58,9 +71,15 @@ Give each ticket its **blocking edges** — the other tickets that must complete
 
 **Blocked by:** the numbers/titles of the tickets that gate this one, or "None — can start immediately".
 
+**Source requirements:** `REQ-001@rev1` (add every requirement this ticket changes or proves).
+
+**Change impact:** `none | implementation | behavior | architecture`
+
+**Impact rationale:** one sentence explaining why this classification is correct.
+
 **Status:** ready-for-agent
 
-- [ ] Acceptance criterion 1
+- [ ] [REQ-001] Acceptance criterion 1
 - [ ] Acceptance criterion 2
 
 </local-ticket-template>

package/plugins/harness-everything/skills/verification-loop/SKILL.md

@@ -4,7 +4,7 @@ description: "Run objective verification gates (build, types, lint, tests, secur
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.12.0
 ---
 
 # Verification Loop
@@ -41,6 +41,7 @@ and rerun from the first affected gate.
 4. Tests and coverage: `npm run test -- --coverage`.
 5. Security scan: secrets and stray logs.
 6. Diff review: `git diff --stat` and unintended-change checks.
-7. Fill `<this-skill-dir>/templates/verification-report.template.md` with evidence.
+7. Contract reconciliation when the work cites `REQ-*` / ADR/spec/ticket lineage or a contract-integrity trace exists: run the strict `<this-skill-dir>/scripts/contract-integrity-audit.js` gate with current #58 evidence. `AUDIT`, `NOT_EVALUATED`, stale source binding, or drift is **not ready** for delivery.
+8. Fill `<this-skill-dir>/templates/verification-report.template.md` with evidence.
 
 Deep dive: `<this-skill-dir>/references/verification-phases.md`

package/plugins/harness-everything/skills/verification-loop/references/verification-phases.md

@@ -10,8 +10,14 @@ flowchart TD
     Lint --> Test[4. Phase 4: Test Suite Execution]
     Test --> Security[5. Phase 5: Security & Secret Scan]
     Security --> Diff[6. Phase 6: Diff Review]
+    Diff --> Contract{7. Contract lineage applicable?}
+    Contract -- Yes --> Reconcile[Run contract-integrity strict reconciliation]
+    Contract -- No --> CheckScript
+    Reconcile --> ContractResult{PASS?}
+    ContractResult -- No --> Fix
+    ContractResult -- Yes --> CheckScript
     
-    Diff --> CheckScript{7. Is verify-gate.js / Template Available?}
+    Diff --> CheckScript{8. Is verify-gate.js / Template Available?}
     
     CheckScript -- Yes --> RunScript[Run harness-everything/scripts/verify-gate.js / Fill verification-report.template.md]
     CheckScript -- No --> DirectReport[Output Verification Report Inline in Response]
@@ -93,6 +99,24 @@ Review each changed file for:
 - Missing error handling
 - Potential edge cases
 
+## Phase 7: Contract Reconciliation
+
+This phase is applicable when any of the following is true:
+
+- the task/spec/ticket cites stable `REQ-*` identities;
+- an ADR/spec/ticket change is classified as `behavior` or `architecture`;
+- the project has a contract-integrity trace for the affected scope.
+
+Use the current trace plus current #58 TDD evidence:
+
+```bash
+node "<this-skill-dir>/scripts/contract-integrity-audit.js" <trace.json> --tdd-evidence <tdd-evidence.json> --output <report.json> --markdown <report.md>
+```
+
+Delivery requires strict **PASS**. Treat `FAIL`, `AUDIT`, `NOT_EVALUATED`, source conflicts/defects, stale spec/test/implementation lineage, surviving required probes, and audit-only output as **NOT READY**. Do not downgrade the gate merely because build/tests are otherwise green.
+
+If this phase is not applicable, record `NOT_APPLICABLE` with a one-line reason. Never use `NOT_APPLICABLE` to hide known requirement lineage.
+
 ## Output Format
 
 After running all phases, fill in `verification-loop/templates/verification-report.template.md` with the actual results and present it.

package/plugins/harness-everything/skills/verification-loop/scripts/contract-integrity-audit.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function resolveAuditRuntime() {
+  const candidates = [
+    path.resolve(__dirname, '../../contract-integrity/scripts/audit.js'),
+    path.resolve(__dirname, '../../../contract-integrity/scripts/audit.js'),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  throw new Error('contract-integrity audit runtime is not packaged with this verification-loop installation');
+}
+
+function main() {
+  try {
+    const target = resolveAuditRuntime();
+    const { runCli } = require(target);
+    if (typeof runCli !== 'function') throw new Error('contract-integrity audit runtime does not export runCli');
+    process.exitCode = runCli([process.execPath, target, ...process.argv.slice(2)]);
+  } catch (error) {
+    console.error('[Verification Contract Gate] ' + error.message);
+    process.exitCode = 2;
+  }
+}
+
+if (require.main === module) main();
+module.exports = { resolveAuditRuntime };

package/plugins/harness-everything/skills/verification-loop/templates/verification-report.template.md

@@ -7,6 +7,9 @@ Lint:      [PASS/FAIL] (X warnings)
 Tests:     [PASS/FAIL] (X/Y passed, Z% coverage)
 Security:  [PASS/FAIL] (X issues)
 Diff:      [X files changed]
+Contract:  [PASS/FAIL/NOT_APPLICABLE] (REQ IDs / trace report / reason)
+            Strict PASS required when contract lineage is applicable.
+            AUDIT or NOT_EVALUATED is NOT READY.
 
 Overall:   [READY/NOT READY] for PR
 

package/scripts/sync-openai-plugin.js

@@ -68,6 +68,18 @@ syncTree(path.join(ROOT, 'scripts', 'lib', 'workspace.js'), packageWorkspace);
 const packageAdvisoryText = path.join(pluginRoot, 'scripts', 'lib', 'advisory-text.js');
 syncTree(path.join(ROOT, 'scripts', 'lib', 'advisory-text.js'), packageAdvisoryText);
 
+// Contract-integrity is shared runtime, not a directly-routed 27th skill.
+// Package it under the plugin root and rewrite its one canonical TDD import
+// to the packaged skill tree.
+const packageContractAudit = path.join(pluginRoot, 'contract-integrity', 'scripts', 'audit.js');
+syncTree(path.join(ROOT, 'contract-integrity', 'scripts', 'audit.js'), packageContractAudit);
+const contractAuditSource = fs.readFileSync(packageContractAudit, 'utf8');
+fs.writeFileSync(
+  packageContractAudit,
+  contractAuditSource.replace("require('../../tdd/scripts/quality-gate')", "require('../../skills/tdd/scripts/quality-gate')"),
+  'utf8'
+);
+
 // The source hook state module is shared with Claude and uses the repository
 // layout. Rewrite only that import in the packaged copy; all other relative
 // imports remain inside the package tree.

package/self-evolve/SKILL.md

@@ -4,7 +4,7 @@ description: "Extract root causes from resolved problems and persist them as def
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.11.0
+  version: 0.12.0
 ---
 
 # Self-evolve

package/self-evolve/scripts/lesson-candidate.js

@@ -6,6 +6,18 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { contentHash, scoreRuleQuality, screenMemoryForPersistence } = require('./persist-memory');
 
+let emitLessonTelemetry = () => ({ ok: false, unavailable: true });
+for (const relative of [
+  '../../hooks/scripts/lib/telemetry.js',
+  '../../../hooks/scripts/lib/telemetry.js',
+]) {
+  const candidate = path.resolve(__dirname, relative);
+  if (fs.existsSync(candidate)) {
+    ({ emitLessonTelemetry } = require(candidate));
+    break;
+  }
+}
+
 let getWorkspaceRoot;
 let getWorkspaceStateDir;
 try {
@@ -69,6 +81,24 @@ function pushState(candidate, state, reasonCode, evidenceRef = null) {
   }].slice(-32);
 }
 
+function emitCandidateLifecycle(input, candidate, event, state, status = 'unknown') {
+  const history = [...(candidate.history || [])].reverse().find(item => item.state === state);
+  const reasonCodes = [
+    history && history.reasonCode,
+    candidate.trigger && candidate.trigger.type ? `trigger:${candidate.trigger.type}` : null,
+    ...(candidate.evaluation && Array.isArray(candidate.evaluation.reasonCodes) ? candidate.evaluation.reasonCodes : []),
+  ].filter(Boolean);
+  return emitLessonTelemetry({
+    event,
+    root: input.workspace,
+    sessionId: input.sessionId || (candidate.provenance && candidate.provenance.sessionId),
+    candidateId: candidate.candidateId,
+    observedAt: history && history.observedAt,
+    status,
+    reasonCodes,
+  });
+}
+
 function replayability(candidate) {
   if (candidate.trigger?.type === 'verifier-fail-pass' &&
       candidate.evidence?.previousStatus === 'fail' &&
@@ -134,6 +164,8 @@ function evaluateCandidate(input) {
     };
     pushState(candidate, 'rejected', 'candidate-screening-or-quality-failed');
     atomicWriteJson(file, candidate);
+    emitCandidateLifecycle(input, candidate, 'lesson_screened', 'screened', screening.allowed ? 'success' : 'failure');
+    emitCandidateLifecycle(input, candidate, 'lesson_rejected', 'rejected', 'failure');
     return { file, candidate };
   }
 
@@ -150,6 +182,15 @@ function evaluateCandidate(input) {
   pushState(candidate, 'evaluated', replay.reasonCode);
   pushState(candidate, disposition, disposition === 'accepted' ? 'eligible-for-governed-promotion' : 'paired-or-later-evidence-required');
   atomicWriteJson(file, candidate);
+  emitCandidateLifecycle(input, candidate, 'lesson_screened', 'screened', 'success');
+  emitCandidateLifecycle(input, candidate, 'lesson_evaluated', 'evaluated', 'success');
+  emitCandidateLifecycle(
+    input,
+    candidate,
+    disposition === 'accepted' ? 'lesson_accepted' : 'lesson_inconclusive',
+    disposition,
+    disposition === 'accepted' ? 'success' : 'unknown',
+  );
   return { file, candidate };
 }
 
@@ -212,6 +253,7 @@ function promoteCandidate(input) {
   if (persisted) pushState(candidate, 'persisted', 'accepted-and-authorized-memory-write');
   else pushState(candidate, 'accepted', 'memory-governance-held-as-review-candidate');
   atomicWriteJson(file, candidate);
+  if (persisted) emitCandidateLifecycle(input, candidate, 'lesson_persisted', 'persisted', 'success');
   return { ok: true, exitCode: 0, persisted, stdout: result.stdout, stderr: result.stderr, candidate };
 }
 
@@ -234,6 +276,16 @@ function observeCandidate(input) {
   };
   pushState(candidate, next, `lesson-${next}`, evidenceRef);
   atomicWriteJson(file, candidate);
+  // Retrieval telemetry is emitted by the actual scoped retrieval path so the
+  // funnel measures exposure, not an operator-authored lifecycle annotation.
+  if (next !== 'retrieved') {
+    const event = {
+      validated: 'lesson_validated',
+      regressed: 'lesson_regressed',
+      superseded: 'lesson_superseded',
+    }[next];
+    if (event) emitCandidateLifecycle(input, candidate, event, next, next === 'regressed' ? 'failure' : 'success');
+  }
   return { file, candidate };
 }
 

package/telemetry/schemas/event.schema.json

@@ -4,36 +4,155 @@
   "title": "Harness Telemetry Event",
   "type": "object",
   "required": [
-    "schemaVersion", "eventId", "event", "host", "observedAt",
-    "sessionId", "turnId", "agentId", "invocationId", "skillName",
-    "skillVersion", "toolName", "status", "retryCount", "timing", "reasonCodes"
+    "schemaVersion",
+    "eventId",
+    "event",
+    "host",
+    "observedAt",
+    "sessionId",
+    "turnId",
+    "agentId",
+    "invocationId",
+    "skillName",
+    "skillVersion",
+    "toolName",
+    "status",
+    "retryCount",
+    "timing",
+    "reasonCodes"
   ],
   "properties": {
-    "schemaVersion": { "const": 1 },
-    "eventId": { "type": "string", "minLength": 1 },
-    "event": { "enum": ["skill.invoke", "skill.loaded", "skill.complete", "tool.observed"] },
-    "host": { "enum": ["claude", "codex", "opencode", "unknown"] },
-    "observedAt": { "type": "string", "format": "date-time" },
-    "sessionId": { "type": ["string", "null"] },
-    "turnId": { "type": ["string", "null"] },
-    "agentId": { "type": ["string", "null"] },
-    "invocationId": { "type": ["string", "null"] },
-    "skillName": { "type": ["string", "null"] },
-    "skillVersion": { "type": ["string", "null"] },
-    "toolName": { "type": ["string", "null"] },
-    "status": { "enum": ["unknown", "success", "failure", "aborted"] },
-    "retryCount": { "type": "integer", "minimum": 0 },
+    "schemaVersion": {
+      "const": 1
+    },
+    "eventId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "event": {
+      "enum": [
+        "skill.invoke",
+        "skill.loaded",
+        "skill.complete",
+        "tool.observed",
+        "learning_opportunity",
+        "lesson_proposed",
+        "lesson_screened",
+        "lesson_evaluated",
+        "lesson_accepted",
+        "lesson_rejected",
+        "lesson_inconclusive",
+        "lesson_persisted",
+        "lesson_retrieved",
+        "lesson_validated",
+        "lesson_regressed",
+        "lesson_superseded"
+      ]
+    },
+    "host": {
+      "enum": [
+        "claude",
+        "codex",
+        "opencode",
+        "unknown"
+      ]
+    },
+    "observedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "sessionId": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "turnId": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "agentId": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "invocationId": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "skillName": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "skillVersion": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "toolName": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "status": {
+      "enum": [
+        "unknown",
+        "success",
+        "failure",
+        "aborted"
+      ]
+    },
+    "retryCount": {
+      "type": "integer",
+      "minimum": 0
+    },
     "timing": {
       "type": "object",
-      "required": ["skillLoadDurationMs", "activeWindowMs", "attributedToolDurationMs"],
+      "required": [
+        "skillLoadDurationMs",
+        "activeWindowMs",
+        "attributedToolDurationMs"
+      ],
       "properties": {
-        "skillLoadDurationMs": { "type": ["number", "null"], "minimum": 0 },
-        "activeWindowMs": { "type": ["number", "null"], "minimum": 0 },
-        "attributedToolDurationMs": { "type": ["number", "null"], "minimum": 0 }
+        "skillLoadDurationMs": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "activeWindowMs": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "attributedToolDurationMs": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "minimum": 0
+        }
       },
       "additionalProperties": false
     },
-    "reasonCodes": { "type": "array", "items": { "type": "string" } }
+    "reasonCodes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
   },
   "additionalProperties": false
 }

package/telemetry/scripts/report.js

@@ -4,6 +4,7 @@
 const fs = require('fs');
 const path = require('path');
 const {
+  LESSON_EVENT_TYPES,
   readEvents,
   telemetryFile,
 } = require('../../hooks/scripts/lib/telemetry');
@@ -28,8 +29,20 @@ function buildReport(events) {
   const valid = events.filter(event => event && !event.invalid);
   const invalid = events.filter(event => event && event.invalid);
   const groups = new Map();
+  const lessonCandidateIds = new Set();
+  const lessonEvents = {};
+  const lessonCandidatesByEvent = new Map();
 
   for (const event of valid) {
+    if (LESSON_EVENT_TYPES.has(event.event)) {
+      lessonEvents[event.event] = (lessonEvents[event.event] || 0) + 1;
+      if (event.invocationId) {
+        lessonCandidateIds.add(event.invocationId);
+        if (!lessonCandidatesByEvent.has(event.event)) lessonCandidatesByEvent.set(event.event, new Set());
+        lessonCandidatesByEvent.get(event.event).add(event.invocationId);
+      }
+      continue;
+    }
     const key = `${event.host}::${event.skillName || '(unknown)'}`;
     if (!groups.has(key)) groups.set(key, {
       host: event.host,
@@ -80,11 +93,34 @@ function buildReport(events) {
     attributedToolDurationMs: metric(g.attributedToolDurations),
   })).sort((a, b) => `${a.host}/${a.skillName}`.localeCompare(`${b.host}/${b.skillName}`));
 
+  const uniqueLessonCount = event => lessonCandidatesByEvent.get(event)?.size || 0;
+  const selfEvolve = {
+    candidateCount: lessonCandidateIds.size,
+    eventCount: Object.values(lessonEvents).reduce((sum, value) => sum + value, 0),
+    funnel: {
+      opportunities: uniqueLessonCount('learning_opportunity'),
+      proposed: uniqueLessonCount('lesson_proposed'),
+      screened: uniqueLessonCount('lesson_screened'),
+      evaluated: uniqueLessonCount('lesson_evaluated'),
+      accepted: uniqueLessonCount('lesson_accepted'),
+      rejected: uniqueLessonCount('lesson_rejected'),
+      inconclusive: uniqueLessonCount('lesson_inconclusive'),
+      persisted: uniqueLessonCount('lesson_persisted'),
+      retrieved: uniqueLessonCount('lesson_retrieved'),
+      validated: uniqueLessonCount('lesson_validated'),
+      regressed: uniqueLessonCount('lesson_regressed'),
+      superseded: uniqueLessonCount('lesson_superseded'),
+    },
+    events: lessonEvents,
+    semantics: 'Counts are privacy-safe lifecycle observations. Acceptance/persistence/retrieval counts do not by themselves prove behavioral improvement.',
+  };
+
   return {
     schemaVersion: 1,
     eventCount: valid.length,
     invalidEventCount: invalid.length,
     skills,
+    selfEvolve,
     semantics: {
       skillLoadDurationMs: 'PreToolUse(Skill) to correlated PostToolUse(Skill); framework/load latency only.',
       activeWindowMs: 'Successful skill load to host Stop/turn boundary; context exposure window, not CPU time.',
@@ -104,6 +140,12 @@ function markdown(report) {
     const pair = value => value.count ? `${value.p50}/${value.p95}` : '-';
     lines.push(`| ${row.host} | ${row.skillName || '(unknown)'} | ${row.invocationCount} | ${row.completeEvents} | ${row.status.failure} | ${pair(row.skillLoadDurationMs)} | ${pair(row.activeWindowMs)} | ${pair(row.attributedToolDurationMs)} |`);
   }
+  lines.push('', '## Self-Evolve Lifecycle Funnel', '');
+  const f = report.selfEvolve.funnel;
+  lines.push('| Opportunity | Proposed | Accepted | Rejected | Inconclusive | Persisted | Retrieved | Validated | Regressed |');
+  lines.push('| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |');
+  lines.push(`| ${f.opportunities} | ${f.proposed} | ${f.accepted} | ${f.rejected} | ${f.inconclusive} | ${f.persisted} | ${f.retrieved} | ${f.validated} | ${f.regressed} |`);
+  lines.push('', '> Lesson funnel counts are lifecycle evidence, not proof that a persisted lesson improved behavior.');
   lines.push('', `Events: ${report.eventCount}; invalid lines: ${report.invalidEventCount}.`);
   lines.push('', '> Active window is not CPU/runtime. Attributed tool time is observational and non-exclusive when skills overlap.');
   return `${lines.join('\n')}\n`;

package/to-spec/SKILL.md

@@ -4,7 +4,7 @@ description: "Turn the conversation into a written spec — feature PRD, CLI/API
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.12.0
 ---
 
 # To Spec

package/to-spec/references/process.md

@@ -60,6 +60,32 @@ What "confirm" means depends on the shape picked:
 
 Skip this step only if the conversation already pinned down the relevant surface explicitly (e.g. a prior `grill-with-docs` pass already fixed the schema).
 
+## Stable contract identity
+
+When the published artifact is an authoritative behavior contract, every normative requirement must have a stable identity instead of relying on prose position.
+
+Use this compact shape in the selected template:
+
+```md
+## Contract Requirements
+
+### REQ-001 — <short behavior name>
+**Status:** CURRENT
+**Revision:** 1
+**Decision lineage:** ADR-0001 (or `None`)
+<normative behavior and observable acceptance boundary>
+```
+
+Rules:
+
+- Never recycle a `REQ-*` ID for different behavior.
+- Behavior changes increment the requirement revision and update the living spec **before** implementation is accepted.
+- Superseded behavior remains traceable; do not erase the old requirement history merely because a ticket changed.
+- If a ticket is classified `changeImpact: architecture`, publish the new/superseding ADR first and link it from the affected requirement.
+- If the document is informative rather than authoritative, say so explicitly and link the authoritative requirement instead of inventing a parallel source of truth.
+
+The detailed ADR -> spec -> ticket -> test -> implementation lineage belongs in the structured contract trace; keep the human spec concise.
+
 ## Publishing details
 
 Write the doc using the adapted template at the resolved storage path:

package/to-spec/templates/cli-reference.md

@@ -28,4 +28,18 @@ Every distinct exit code or error response: what triggers it, what the caller sh
 
 Other commands/endpoints this one is commonly paired with, supersedes, or is superseded by.
 
+## Contract Requirements
+
+For every normative behavior this document owns, assign a stable requirement identity:
+
+```md
+### REQ-001 — <short behavior name>
+**Status:** CURRENT
+**Revision:** 1
+**Decision lineage:** ADR-0001 (or None)
+<observable command/API behavior or error contract>
+```
+
+Do not recycle requirement IDs. A changed caller-visible contract increments the revision before implementation completion.
+
 </spec-template>

package/to-spec/templates/dev-doc.md

@@ -24,4 +24,18 @@ What this decision costs, even though it was the right call.
 
 How this ships (flag, gradual, all-at-once) and how to undo it if it's wrong.
 
+## Contract Requirements
+
+If this document owns normative behavior, assign stable requirement identities:
+
+```md
+### REQ-001 — <short behavior name>
+**Status:** CURRENT
+**Revision:** 1
+**Decision lineage:** ADR-0001 (or None)
+<observable behavior / acceptance boundary>
+```
+
+If this document is informative only, say so and link the authoritative requirement instead. Do not create a second source of truth.
+
 </spec-template>