@dev-loops/core 1.0.2-pre.0 → 1.0.2-slim.0

package/src/loop/review-dispatch-plan.mjs

@@ -1,39 +1,13 @@
 /**
- * review-dispatch-plan.mjs — cache-aware review dispatch plan + request-prefix
- * fingerprinting + stable/volatile request separation (issue #1468 slices 1-2).
+ * review-dispatch-plan.mjs — cache-aware review dispatch: harness capability
+ * model, request-prefix fingerprinting, stable/volatile request separation,
+ * and the deterministic per-gate-round dispatch-plan builder.
  *
- * This module is the mechanically-checkable foundation for the cache-efficient
- * review dispatch design (Section A/B/C/D of the #1468 spec). It owns:
- *
- *  1. Harness capability model — explicit representation of what a harness can
- *     observe/control about provider prompt caching
- *     (breakpointControl / barrierSignal / cacheTtlControl / usageTelemetry).
- *     Opaque capabilities are represented as such and are NEVER described as
- *     verified cache hits.
- *  2. Request-prefix fingerprinting — a deterministic sha256 over every
- *     cache-relevant value the dev-loops layer observes or controls (concrete
- *     model, tool definitions/order, system/project/agent instructions,
- *     thinking/tool-choice settings, content-block boundaries, shared artifact
- *     bytes, and breakpoint/TTL intent). Values owned opaquely by a harness are
- *     represented as a placeholder, never assumed identical.
- *  3. Stable/volatile request separation — physically separates stable handoff
- *     content from volatile `gateState` at the request/artifact boundary, so a
- *     provider-visible cache boundary sits after the stable materialized
- *     briefing block and before the late volatile tail + angle suffix.
- *  4. Dispatch-plan builder — one deterministic per-gate-round artifact that
- *     records the complete cache-relevant request shape without duplicating
- *     briefing content (Section A). `buildAngleRequestGroups` partitions a
- *     caller's angle -> concrete-model resolutions into that plan's
- *     `requestGroups` shape, bucketing angles with no override into an
- *     explicit "inherit" key rather than merging them into a concrete group.
- *  5. Primer-form default — deterministic default by harness capability
- *     (Section C/D): first-output-observable harnesses may let a lead reviewer
- *     prime; completion-only harnesses default to a short dedicated primer
- *     unless an adequate TTL is explicit; multiple concrete models partition
- *     into one primer group per model/request-prefix.
- *
- * This module is pure and offline: no GitHub, no harness, no clock. All runtime
- * execution adapters consume it; it never executes a reviewer itself.
+ * Pure and offline: no GitHub, no harness, no clock; runtime execution
+ * adapters consume it, it never executes a reviewer itself. A capability a
+ * harness owns opaquely (breakpoints/TTL/telemetry it cannot observe) is
+ * always represented as opaque/unavailable rather than assumed identical —
+ * this module never claims a verified cache hit it cannot prove.
  */
 import { createHash } from "node:crypto";
 
@@ -198,20 +172,16 @@ function isPlainObject(value) {
 }
 
 /**
- * Recursively sort object keys for a byte-deterministic serialization (arrays
- * keep their order — order is itself cache-relevant for tool definitions and
- * content-block boundaries).
+ * Recursively sort object keys for byte-deterministic serialization (array
+ * order is preserved — order is itself cache-relevant).
  *
- * Trust-boundary validation, refusing loudly rather than silently colliding
- * two distinct inputs onto one fingerprint: a non-finite number (NaN/
- * Infinity) is rejected rather than let `JSON.stringify` collapse it to
- * `null`, a non-plain object (Date/Map/Set/...) is rejected rather than let
- * `Object.keys` see it as keyless (and therefore indistinguishable from
- * `{}`), and undefined/function/symbol/bigint are rejected rather than
- * silently dropped or crash-serialized by `JSON.stringify` itself. The
- * accumulator is null-prototype so an own `__proto__` key (a realistic shape
- * for JSON.parse'd input) is kept as a plain data property instead of
- * vanishing into the prototype chain.
+ * Fails closed rather than silently colliding distinct inputs onto one
+ * fingerprint: a non-finite number is rejected rather than collapsed to
+ * `null`, a non-plain object (Date/Map/Set/...) is rejected rather than
+ * treated as keyless, and undefined/function/symbol/bigint are rejected
+ * rather than dropped or crash-serialized. The accumulator is null-prototype
+ * so an own `__proto__` key stays a plain data property instead of vanishing
+ * into the prototype chain.
  * @param {*} value
  * @param {string} [keyPath] — dotted path to `value`, for the error message
  * @returns {*}
@@ -241,24 +211,16 @@ function stableStringify(value, keyPath = "$") {
 }
 
 /**
- * Fingerprint the complete observable request prefix (Section A). Every
- * cache-relevant value the dev-loops layer observes or controls is folded into
- * the hash: concrete model, tool definitions/order, system/project/agent
- * instructions, thinking/tool-choice settings, content-block boundaries, shared
- * artifact bytes, and breakpoint/TTL intent. Values owned opaquely by a harness
- * should be passed as `null`-free opaque markers (see `opaqueMarker`).
+ * Fingerprint the complete observable request prefix (Section A): concrete
+ * model, tool definitions/order, system/project/agent instructions,
+ * thinking/tool-choice settings, content-block boundaries, shared artifact
+ * bytes, and breakpoint/TTL intent. Values owned opaquely by a harness should
+ * be passed as `null`-free opaque markers (see `opaqueMarker`).
  *
  * @param {object} input
- * @param {string} input.model - concrete model id for this request group.
- * @param {string[]|object[]} [input.tools] - tool definitions/order.
- * @param {string|string[]} [input.systemInstructions] - system/project/agent instructions.
- * @param {object|string} [input.settings] - thinking/tool-choice settings.
- * @param {object[]} [input.contentBlocks] - content-block boundaries + shared bytes.
- * @param {string} [input.sharedArtifact] - shared artifact reference (path) or bytes.
- * @param {string} [input.cacheBoundary] - e.g. `after_shared_prefix`.
- * @param {string} [input.ttlIntent] - one of TTL_INTENT_VALUES.
- * @param {string[]} [input.angleSuffix] - angle-specific suffix (excluded from the
- *   STABLE prefix fingerprint; included here only when invasive).
+ * @param {string} input.model - non-empty concrete model id.
+ * @param {string[]} [input.angleSuffix] - excluded from the STABLE prefix
+ *   fingerprint elsewhere, but folded in here when present.
  * @returns {{ fingerprint: string, canonical: object }}
  */
 export function fingerprintRequestPrefix(input) {
@@ -543,30 +505,20 @@ export const INHERIT_MODEL_KEY = "inherit";
  * input. Angles resolving to the same concrete model id share one group;
  * angles with no override (`model: null`/`undefined`) form their own explicit
  * {@link INHERIT_MODEL_KEY} bucket, never merged with a concrete id. An angle
- * listed twice with two DIFFERENT models is a caller bug and throws (an angle
- * cannot honestly belong to two request groups). A concrete model literally
- * named {@link INHERIT_MODEL_KEY} also throws — it would otherwise silently
- * collide with the reserved bucket key and become indistinguishable from
- * genuine no-override.
+ * listed twice with two DIFFERENT models throws (it cannot belong to two
+ * request groups); a concrete model literally named {@link INHERIT_MODEL_KEY}
+ * also throws, since it would otherwise collide with the reserved bucket key.
  *
  * Each group's `requestPrefixFingerprint` is computed via
  * {@link fingerprintRequestPrefix} over every cache-relevant input this layer
- * observes for that group (the bucket's model, tool set/order, instructions,
- * settings, content-block boundaries, the shared-prefix bytes, and the
- * declared cache boundary/TTL intent) — changing only the angle set within a
- * bucket never changes its fingerprint.
+ * observes for that group — changing only the angle set within a bucket never
+ * changes its fingerprint.
  *
  * @param {object} input
  * @param {Array<{angle: string, model: string|null}>} input.angleModels
- * @param {string} [input.sharedPrefixHash] — folded in as the fingerprint's shared-artifact reference.
- * @param {Array<string|object>} [input.toolDefinitions] — tool names/definitions in dispatch order
- * @param {string|string[]} [input.instructions] — system/project/agent instruction bytes (or a digest)
- * @param {object} [input.settings] — thinking/tool-choice settings
- * @param {string[]} [input.blockBoundaries] — content-block boundary markers, in order
- * @param {string} [input.cacheBoundary]
- * @param {string} [input.ttlIntent] — one of TTL_INTENT_VALUES
- * @returns {RequestGroup[]} sorted by model (code-unit order, never localeCompare — ICU-dependent
- *   sorting could order the same two model ids differently across runtimes); angles sorted within a group.
+ * @returns {RequestGroup[]} sorted by model (code-unit order, never
+ *   localeCompare — ICU-dependent sorting could order the same two model ids
+ *   differently across runtimes); angles sorted within a group.
  */
 export function buildAngleRequestGroups({
   angleModels,
@@ -730,11 +682,11 @@ export function partitionPrimerGroups(requestGroups, capabilities = {}) {
 }
 
 /* ------------------------------------------------------------------ *
- * 6. Dispatch-prompt layout alignment (issue #1841, completes #1468)
+ * 6. Dispatch-prompt layout alignment
  * ------------------------------------------------------------------ */
 
-// Leading-bytes capture cap for a dispatched reviewer prompt (issue #1841's
-// record-dispatch-prompt-layout.mjs). Sized comfortably above
+// Leading-bytes capture cap for a dispatched reviewer prompt (the
+// record-dispatch-prompt-layout.mjs cap). Sized comfortably above
 // write-gate-context.mjs's BRIEFING_PREFIX_INLINE_DIFF_CAP_BYTES (200 KiB) so
 // a full byte-for-byte alignment check never runs out of captured bytes for
 // an inline-mode round.
@@ -765,33 +717,26 @@ export function renderBriefingPointerLine(prefixPath) {
 /**
  * Deterministically compose a full reviewer prompt: the round's
  * byte-identical invariant prefix INLINED as the leading bytes, followed by
- * the (also round-invariant) volatile tail, followed by the per-group angle
- * suffix (issue #1852). This is the ONE function every reviewer prompt on the
- * canonical fan-out path is built from — never a hand-assembled per-group
- * preamble that leads with dynamic prose ahead of the prefix (the
- * "angle-first" / pointer-seeding failure mode `verifyPromptLeadingAlignment`
- * exists to catch).
+ * the round-invariant volatile tail, followed by the per-group angle suffix.
+ * This is the ONE function every reviewer prompt on the canonical
+ * fan-out path is built from — never a hand-assembled per-group preamble that
+ * leads with dynamic prose ahead of the prefix (the "angle-first" failure
+ * mode `verifyPromptLeadingAlignment` exists to catch).
  *
- * Byte-identical-prefix-across-groups falls out of the arguments alone: any
- * two calls sharing the same `prefixBytes`/`volatileBytes` (true for every
- * dispatch unit of one round, since both are round-scoped, not group-scoped)
- * produce prompts whose leading span is identical regardless of
- * `angleSuffix` — the property AC1 requires, provable by construction rather
- * than by review.
+ * Byte-identical-prefix-across-groups follows from the arguments alone: any
+ * two calls sharing `prefixBytes`/`volatileBytes` (true for every dispatch
+ * unit of one round) produce prompts whose leading span is identical
+ * regardless of `angleSuffix` — provable by construction, not by review.
  *
  * Pure and offline: takes already-read bytes, never reads a file itself (the
- * CLI wrapper, `compose-reviewer-prompt.mjs`, owns I/O and the
- * record-dispatch-prompt-layout.mjs capture that makes the composed prompt's
- * layout binding on `verify-dispatch-prompt-layout.mjs`).
+ * CLI wrapper, `compose-reviewer-prompt.mjs`, owns I/O and the capture that
+ * makes the composed prompt's layout binding on
+ * `verify-dispatch-prompt-layout.mjs`).
  *
  * @param {object} input
- * @param {string} input.prefixBytes — the round's invariant-prefix bytes
- *   (`<gate>-<headSha>.briefing-prefix.txt`), non-empty.
- * @param {string} [input.volatileBytes] — the round's volatile-tail bytes
- *   (`<gate>-<headSha>.briefing-volatile.txt`); absent/non-string treated as
- *   "" (best-effort — a round that never wrote one still composes).
- * @param {string} input.angleSuffix — the per-group/angle-specific prompt
- *   text, non-empty (an empty suffix would compose a prompt naming no work).
+ * @param {string} input.prefixBytes — non-empty, the round's invariant-prefix bytes.
+ * @param {string} [input.volatileBytes] — round's volatile-tail bytes; absent treated as "".
+ * @param {string} input.angleSuffix — non-empty per-group angle-specific prompt text.
  * @returns {string} the exact full reviewer prompt text.
  */
 export function composeReviewerPromptText({ prefixBytes, volatileBytes, angleSuffix } = {}) {
@@ -807,26 +752,19 @@ export function composeReviewerPromptText({ prefixBytes, volatileBytes, angleSuf
 
 /**
  * Decide whether a dispatched reviewer prompt's LEADING bytes are
- * cache-aligned (GATE-EXEC-BRIEFING-PREFIX layout, issue #1841): either the
+ * cache-aligned (GATE-EXEC-BRIEFING-PREFIX layout): either the
  * prompt's leading bytes are byte-identical to the round's invariant prefix
  * (inline mode), or the prompt leads with the byte-identical pointer line
  * naming the round's invariant-prefix path (pointer-seeding mode), with any
- * angle-specific text strictly AFTER it. An angle-first prompt (dynamic
- * per-unit prose ahead of the prefix/pointer) matches neither and is
- * REJECTED — this is the mechanical proof the prose-only rule lacked.
+ * angle-specific text strictly AFTER it. An angle-first prompt matches
+ * neither and is REJECTED.
  *
- * Pure and offline: takes the already-captured leading bytes and the already-
- * read prefix bytes/path, never reads a file itself (the CLI wrapper owns
- * I/O), so this is directly unit-testable with in-memory strings.
+ * Pure and offline: takes already-captured bytes, never reads a file itself.
  *
  * @param {object} input
- * @param {string} input.promptLeading — the captured leading bytes of the
- *   ACTUAL reviewer prompt (record-dispatch-prompt-layout.mjs's capture).
- * @param {string} input.prefixBytes — the round's recorded byte-identical
- *   invariant-prefix content (the `<gate>-<headSha>.briefing-prefix.txt`
- *   bytes).
- * @param {string} input.prefixPath — the path used to render this round's
- *   pointer line (must be the SAME path every reviewer was pointed at).
+ * @param {string} input.promptLeading — captured leading bytes of the actual reviewer prompt.
+ * @param {string} input.prefixBytes — the round's recorded invariant-prefix bytes.
+ * @param {string} input.prefixPath — the path used to render this round's pointer line.
  * @returns {{ aligned: boolean, mode: "inline"|"pointer"|null, reason: string|null }}
  */
 export function verifyPromptLeadingAlignment({ promptLeading, prefixBytes, prefixPath } = {}) {
@@ -848,7 +786,7 @@ export function verifyPromptLeadingAlignment({ promptLeading, prefixBytes, prefi
 }
 
 /* ------------------------------------------------------------------ *
- * 7. Diff filtering for the shared per-head block (issue #1853)
+ * 7. Diff filtering for the shared per-head block
  * ------------------------------------------------------------------ */
 
 /**
@@ -983,7 +921,7 @@ function extractDiffBlockPath(blockLines) {
 
 /**
  * Filter a unified diff (`git diff` output) down to the files that should be
- * INLINED into a reviewer prompt's shared per-head block (issue #1853):
+ * INLINED into a reviewer prompt's shared per-head block:
  * lockfiles, generated/vendored trees, and any caller-configured
  * `excludeGlobs` are dropped whole-file (header + all hunks), every other
  * file's block passes through byte-for-byte unchanged. Excluding a file here

package/src/loop/review-lineage.mjs

@@ -1,37 +1,22 @@
 /**
- * review-lineage.mjs — additive review-lineage base + per-fix-round delta
- * composition (issue #1468 slice 5).
+ * Additive review-lineage base + per-fix-round delta composition.
  *
- * A new head after a fix used to rebuild a full head-specific briefing. This
- * module introduces a stable review-lineage base plus deterministic per-round
- * delta artifacts, so round 2+ appends only what changed instead of replacing
- * the whole context.
- *
- * Artifact model (Section E of the #1468 spec):
- *
- *   review-lineage-base
- *     lineage identity + gate + stable contracts/instructions + original
- *     review target + original full diff.
- *
- *   round-N-delta
- *     exact base/reviewed SHAs + the fix diff + validation evidence + an
- *     independent findings verification checklist.
+ * A stable review-lineage base plus deterministic per-round delta artifacts let
+ * round 2+ append only what changed instead of rebuilding a full head-specific
+ * briefing.
  *
  * Composition contract:
- *
- *   round-N request = [lineage base][delta 1][delta 2]...[delta N][angle suffix]
+ *   round-N request = [lineage base][delta 1]...[delta N][angle suffix]
  *
  * Composition is append-only and byte-deterministic: the composed request is
  * the ordered concatenation of the lineage base and the individual delta
- * artifacts, never a parse/reserialize of the full PR context as a replacement
- * block. Round N+1 appends exactly one new delta segment; every prior segment
- * is byte-identical (same ref + same hash) — that is what the
- * "does not rebuild the full PR context" test asserts.
+ * artifacts, never a parse/reserialize of the full PR context. Round N+1 appends
+ * exactly one new delta segment; every prior segment is byte-identical (same
+ * ref + same hash).
  *
- * Carry-forward semantics are unchanged: a carried clean angle still records
- * its original reviewer and prior head. This module only preserves that
- * provenance in the composed request; it does not decide carry-forward (that
- * stays in gate-carry-forward.mjs) and it never fabricates a verdict.
+ * Carry-forward provenance (original reviewer + prior head of a carried clean
+ * angle) is preserved in the composed request but not decided here (that stays
+ * in gate-carry-forward.mjs); a verdict is never fabricated.
  *
  * This module is pure and offline: no GitHub, no harness, no clock.
  */
@@ -226,26 +211,16 @@ export const ANGLE_SUFFIX_SLOT = "angleSuffix";
 
 /**
  * Compose the round-N request as an append-only ordered segment list:
- *
  *   [lineage base][delta 1]...[delta N][angle suffix]
  *
- * The returned `segments` carry individual artifact bytes + hashes so a
- * consumer can render the request by concatenating segment bytes IN ORDER
- * (never parsing/reserializing prior segments). Round N+1 appends exactly one
- * new delta segment: callers should REUSE the prior composed segments (or the
- * base + prior deltas) rather than rebuilding the full PR context, and this
- * function's contract + tests pin that reuse property.
- *
- * Segments before the new delta are byte-identical to the prior round's
- * (same `ref` + same `hash`), which is the mechanical proof of append-only
- * composition (AC-2: does not rebuild the full PR context as a replacement
- * block).
+ * Returned `segments` carry individual artifact bytes + hashes; a consumer
+ * renders the request by concatenating segment bytes IN ORDER. Round N+1 appends
+ * exactly one new delta segment and every earlier segment is byte-identical to
+ * the prior round's (same `ref` + same `hash`).
  *
- * `carriedAngles` provenance is preserved unchanged (carry-forward semantics):
- * each entry is { angle, originalReviewer, priorHead } and is folded into the
- * composed hash so a carried angle's provenance is pinned — but never
- * fabricated. A carried clean angle keeps exactly the original reviewer and
- * prior head it was recorded with.
+ * `carriedAngles` provenance is preserved unchanged: each entry
+ * { angle, originalReviewer, priorHead } is folded into the composed hash so a
+ * carried angle's provenance is pinned, never fabricated.
  *
  * @param {object} input
  * @param {object} input.lineageBase - a valid review-lineage-base artifact.
@@ -384,7 +359,7 @@ export function renderComposedRequest(composed) {
 }
 
 /* ------------------------------------------------------------------ *
- * Compaction / rebase policy (issue #1468 slice 6)
+ * Compaction / rebase policy
  * ------------------------------------------------------------------ */
 
 /**

package/src/loop/spec-authority.mjs

@@ -1,40 +1,26 @@
 /**
- * spec-authority.mjs — the canonical shared contract surface for IMMUTABLE SPEC
- * AUTHORITY across the review / judge / fixer / gate / re-entry pipeline.
+ * spec-authority.mjs — canonical shared contract for IMMUTABLE SPEC AUTHORITY
+ * across the review / judge / fixer / gate / re-entry pipeline. Pure and
+ * side-effect free; persistence is the caller's job.
  *
- * This module is PURE and side-effect free. It owns, in one place (so no harness
- * prompt has to re-state normative rules that could drift):
- *
- *   1. The two INDEPENDENT revision identities every decision must pin:
- *      - `specDigest`     — a deterministic digest of the normalized canonical
- *        tracker AC / DoD / Non-goals. It identifies what the work is REQUIRED
- *        and FORBIDDEN to do. It is NEVER derived from a head SHA.
- *      - reviewed implementation revision — `headSha` plus a `contentDigest`.
- *        It identifies what the reviewer actually evaluated. A new head/content
- *        digest NEVER masquerades as a spec change.
- *
- *   2. The four named, machine-readable judge disposition outcomes. For every
- *      finding the judge evaluates the finding AND each proposed remediation
- *      against the COMPLETE spec (not one supportive criterion) and selects
- *      exactly one outcome.
- *
- *   3. Autonomous vs last-resort escalation: only a `spec_cannot_decide` outcome
- *      routes to a human-spec-decision state. A finding/remediation conflict
- *      resolves autonomously (reject the finding, or reject the remedy and route
- *      to a compliant alternative).
- *
- *   4. Human-only spec change: a material spec change/reinterpretation produces a
- *      NEW `specDigest`; every approval/disposition/gate result derived from the
- *      prior digest is stale and must be re-established.
- *
- *   5. Criterion-scoped invalidation: a fixer push stales only the approvals for
- *      the criteria whose covered content it changed; unaffected criteria carry
- *      forward ONLY with positive deterministic proof that both their governing
- *      spec text and their covered surface are unchanged. Unknown impact fails
- *      closed to fresh review.
- *
- * Persistence is the caller's job; this module validates and decides, it never
- * reads or writes files.
+ * Owns, in one place so no harness prompt re-states rules that could drift:
+ *  1. Two INDEPENDENT revision identities every decision must pin: `specDigest`
+ *     (what the work is REQUIRED/FORBIDDEN to do — never derived from a head
+ *     SHA) and the reviewed revision (`headSha` + `contentDigest`, what was
+ *     actually evaluated — never masquerades as a spec change).
+ *  2. The four named judge disposition outcomes; the judge evaluates every
+ *     finding AND its proposed remediation against the COMPLETE spec (not one
+ *     supportive criterion) and selects exactly one.
+ *  3. Autonomous vs last-resort escalation: only `spec_cannot_decide` routes to
+ *     a human-spec-decision state; a finding/remediation conflict resolves
+ *     autonomously.
+ *  4. Human-only spec change: a material spec change produces a NEW
+ *     `specDigest`, staling every prior-derived approval/disposition/gate
+ *     result.
+ *  5. Criterion-scoped invalidation: a fixer push stales only the approvals for
+ *     criteria whose covered content it changed; an unaffected criterion
+ *     carries forward only with positive proof both its spec text and covered
+ *     surface are unchanged — unknown impact fails closed.
  */
 
 import { sha256Hex } from "./review-dispatch-plan.mjs";
@@ -271,13 +257,11 @@ export function buildRevisionIdentity({ spec, specDigest, headSha, content, cont
   if (resolvedSpecDigest === resolvedContentDigest) {
     throw new Error("SPEC-AUTHORITY-REVISION-IDENTITIES: specDigest and contentDigest must be distinct identities (fail closed)");
   }
-  // The domain separator in computeSpecDigest is the structural guarantee that a
-  // specDigest is never derivable from a head SHA. This is the defensive tripwire
-  // for an explicitly-SUPPLIED digest: reject when the digest's hex body equals or
-  // embeds the head SHA (any length), not only the 64-hex exact case — the
-  // exact-equality-only form was a no-op for a normal 40-hex Git SHA. The
-  // false-positive probability of a real spec digest incidentally embedding the
-  // head SHA is negligible, and the fail-closed direction is safe.
+  // Defensive tripwire for an explicitly-SUPPLIED digest: the domain separator
+  // in computeSpecDigest already guarantees specDigest is never DERIVED from a
+  // headSha, but reject here too when the digest's hex body equals or embeds
+  // the head SHA (any length) — fail-closed, since a real spec digest
+  // incidentally embedding a head SHA is negligible.
   if (resolvedSpecDigest.slice("sha256:".length).includes(sha)) {
     throw new Error("SPEC-AUTHORITY-REVISION-IDENTITIES: specDigest must not be derived from or embed headSha (fail closed)");
   }
@@ -570,7 +554,7 @@ export function resolveCriterionInvalidation({
 }
 
 /**
- * AC1 (issue 2008 / ADR 0061): the ONE shared identity-stamp helper every
+ * AC1 (ADR 0061): the ONE shared identity-stamp helper every
  * gate/fixer record writer threads its revision identity + checked criteria
  * through, so the writers cannot drift from independently-recomputed fields.
  * Validates the pinned trio (reusing {@link assertDigestShape} /
@@ -609,7 +593,7 @@ export function stampSpecAuthorityIdentity(record, { specDigest, headSha, conten
 }
 
 // ---------------------------------------------------------------------------
-// AC7 (issue 2008 / ADR 0061): pure affected-criteria producer
+// AC7 (ADR 0061): pure affected-criteria producer
 // ---------------------------------------------------------------------------
 
 // ponytail: minimal glob subset — exact path, a `dir/**` prefix, or a single
@@ -704,30 +688,16 @@ export function resolveAffectedCriteria({ changedPaths, criterionCoverage } = {}
  * raw (un-normalized) lists; pass the result to {@link computeSpecDigest} /
  * {@link normalizeSpec}.
  *
- * ponytail (#2016 root cause fix): the AC/DoD source is the authoritative
- * AC→DoD mapping MATRIX (`detectAcDodMatrix`, reused byte-identical from
- * `issue-refinement-artifact.mjs` — no second matrix parser) when the body
- * carries one that parses as valid; the list-form AC/DoD checklists
- * (`extractChecklistItems`) are a REDUNDANT presentation projection of that
- * same matrix (`derivePrChecklistsFromIssueMatrix` derives the PR-side
- * checklist from it) and are read only as the fail-closed fallback for older
- * issue bodies that carry no matrix at all. This is the fix for the reported
- * bug: adding/removing/re-heading a checklist alias that projects an
- * UNCHANGED matrix no longer touches `specDigest`, because the checklist is
- * no longer part of the hashed input once a valid matrix exists. Any edit
- * that changes the matrix itself — a criterion's text, its completion-
- * evidence cell, or the row set (add/remove) — changes `matrix.rows` and
- * therefore still changes the digest (fail-closed: no genuine spec change is
- * exempted). Non-goals are unaffected by this change: they were never part of
- * the redundant-checklist problem (the matrix does not carry Non-goals), so
- * they stay sourced from the `## Non-goals` section exactly as before.
- *
- * Fail-closed fallback: when `detectAcDodMatrix` reports `found: false` (no
- * matrix at all) or `valid: false` (empty/malformed/identifier-only table —
- * i.e. it cannot be positively parsed as a real semantic mapping), this falls
- * back to the PRE-#2016 behavior of hashing the extracted checklist text
- * verbatim. A body this function cannot prove carries an equivalent matrix
- * must never silently narrow what gets digested.
+ * The AC/DoD source is the authoritative AC→DoD mapping MATRIX
+ * (`detectAcDodMatrix`, reused byte-identical from
+ * `issue-refinement-artifact.mjs`) when the body carries one that parses as
+ * valid; the list-form checklists (`extractChecklistItems`) are a redundant
+ * presentation projection of that same matrix and are read only as the
+ * fail-closed fallback for older issue bodies with no matrix at all.
+ * A checklist-only edit that projects an unchanged matrix therefore never
+ * touches `specDigest`; any edit that changes the matrix itself still does.
+ * Non-goals always come from the `## Non-goals` section — the matrix does not
+ * carry them.
  *
  * @param {string} body — the tracker issue markdown body
  * @returns {{ acceptanceCriteria: string[], definitionOfDone: string[], nonGoals: string[] }}
@@ -747,7 +717,7 @@ export function extractSpecFromBody(body) {
   }
 
   // Fallback: no positively-parseable matrix — hash the checklist projection
-  // (pre-#2016 behavior) rather than an empty/weaker AC/DoD surface.
+  // (prior behavior) rather than an empty/weaker AC/DoD surface.
   const acSection = extractSection(body, "Acceptance criteria");
   const dodSection =
     extractSection(body, "Definition of done") ?? extractSection(body, "DoD");