@danmoisan/drm-copilot-mcp 1.1.5 → 1.1.6

package/out/mcp-server.js

@@ -31365,10 +31365,16 @@ function parseSection3(markdown, heading) {
 function formatDiffPath2(pathText) {
   return pathText !== null ? formatDiffPath(pathText) : "";
 }
-function appendGenerationTimestamp(clock = () => /* @__PURE__ */ new Date()) {
+var GENERATED_CONTEXT_SECTION_TITLE = "Context generated";
+var HEAD_SHA_LABEL = "Head SHA:";
+var UNKNOWN_HEAD_SHA_PLACEHOLDER = "(unknown)";
+function appendGenerationTimestamp(clock = () => /* @__PURE__ */ new Date(), headSha = null) {
   const now = clock();
   const timestamp = formatUtcTimestamp(now);
-  return section("Context generated") + "\n" + timestamp + "\n";
+  const shaText = headSha !== null && headSha !== "" ? headSha : UNKNOWN_HEAD_SHA_PLACEHOLDER;
+  return section(GENERATED_CONTEXT_SECTION_TITLE) + "\n" + timestamp + `
+${HEAD_SHA_LABEL} ${shaText}
+`;
 }
 function formatUtcTimestamp(date3) {
   const year = date3.getUTCFullYear().toString().padStart(4, "0");
@@ -31716,7 +31722,7 @@ function renderVerificationEvidenceSection(fs10, resolvedRoot, featureDocs) {
   }
   return lines.join("\n");
 }
-function buildSummaryText(collected, fs10, appendixPath) {
+function buildSummaryText(collected, fs10, appendixPath, generatedSection) {
   const ctx = collected.contextResult;
   const ghStatusText = resolveGhStatusText(collected);
   const intentBlock = [
@@ -31727,6 +31733,7 @@ function buildSummaryText(collected, fs10, appendixPath) {
     "Author-asserted autoclose issues:"
   ].join("\n");
   const summarySections = [
+    generatedSection,
     section("GitHub CLI status"),
     ghStatusText,
     intentBlock,
@@ -31804,7 +31811,7 @@ function buildSummaryText(collected, fs10, appendixPath) {
   }
   return summaryText;
 }
-function buildAppendixText(collected, clock) {
+function buildAppendixText(collected, generatedSection) {
   const featureBlock = collected.featureDocs.map((doc) => doc.excerpt).join("\n");
   const issueSections = collected.issueDetails.map(
     (detail) => issueAppendix(detail)
@@ -31813,7 +31820,7 @@ function buildAppendixText(collected, clock) {
     (detail) => prAppendix(detail)
   );
   const appendixParts = [
-    appendGenerationTimestamp(clock),
+    generatedSection,
     collected.contextResult.text,
     "",
     section("Issue details"),
@@ -31846,17 +31853,23 @@ function writeOutput(fs10, text, outPath, append2) {
 function collectAndWrite(options) {
   const clock = options.clock ?? (() => /* @__PURE__ */ new Date());
   const collected = collectPrContext(options);
+  const generatedSection = appendGenerationTimestamp(
+    clock,
+    collected.contextResult.headSha
+  );
   const summaryText = buildSummaryText(
     collected,
     options.fs,
-    options.appendixOut
+    options.appendixOut,
+    generatedSection
   );
-  const appendixText = buildAppendixText(collected, clock);
+  const appendixText = buildAppendixText(collected, generatedSection);
   writeOutput(options.fs, summaryText, options.out, options.append);
   writeOutput(options.fs, appendixText, options.appendixOut, options.append);
   const log = options.log ?? (() => void 0);
   log(`Wrote context summary to: ${options.out}`);
   log(`Wrote context appendix to: ${options.appendixOut}`);
+  return { summaryText, appendixText };
 }
 function resolveGhStatusText(collected) {
   let ghStatusText = collected.ghStatusOverride || collected.ghStatusMessage || "GitHub CLI authenticated.";
@@ -31928,26 +31941,48 @@ function parentDir(path11) {
 // ../../extensions/drm-copilot/src/lib/pr-context/pr-context-service-call.ts
 var SUMMARY_OUT = "artifacts/pr_context.summary.txt";
 var APPENDIX_OUT = "artifacts/pr_context.appendix.txt";
+function verifyWrittenArtifact(fileSystem, artifactPath, expected) {
+  let actual;
+  try {
+    actual = fileSystem.readTextFile(artifactPath);
+  } catch (error2) {
+    const detail = error2 instanceof Error ? error2.message : String(error2);
+    throw new Error(
+      `Failed to verify PR context artifact '${artifactPath}': the file could not be read back after writing (${detail}).`,
+      { cause: error2 }
+    );
+  }
+  if (actual !== expected) {
+    throw new Error(
+      `Failed to verify PR context artifact '${artifactPath}': the content read back is not the content this invocation rendered (expected ${String(expected.length)} characters, read back ${String(actual.length)}).`
+    );
+  }
+}
 function collectPrContextServiceCall(input) {
-  collectAndWrite({
+  const summaryOut = normalizeGeneratedPath(
+    (0, import_node_path.join)(input.workspaceRoot, SUMMARY_OUT)
+  );
+  const appendixOut = normalizeGeneratedPath(
+    (0, import_node_path.join)(input.workspaceRoot, APPENDIX_OUT)
+  );
+  const rendered = collectAndWrite({
     base: input.base,
     repoRoot: input.workspaceRoot,
-    out: SUMMARY_OUT,
-    appendixOut: APPENDIX_OUT,
+    out: summaryOut,
+    appendixOut,
     append: false,
     includeUntracked: true,
     fs: input.fileSystem,
     runner: input.runner,
     ...input.log === void 0 ? {} : { log: input.log }
   });
+  verifyWrittenArtifact(input.fileSystem, summaryOut, rendered.summaryText);
+  verifyWrittenArtifact(input.fileSystem, appendixOut, rendered.appendixText);
   return {
     tool: "collect_pr_context",
     workspaceRoot: input.workspaceRoot,
     summary: `Collected PR context against base '${input.base}'.`,
-    artifacts: [
-      normalizeGeneratedPath((0, import_node_path.join)(input.workspaceRoot, SUMMARY_OUT)),
-      normalizeGeneratedPath((0, import_node_path.join)(input.workspaceRoot, APPENDIX_OUT))
-    ]
+    artifacts: [summaryOut, appendixOut]
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Stdio MCP server exposing drm-copilot repo-automation tools.",
   "license": "MIT",
   "type": "commonjs",

package/resources/claude-customizations/.claude/hooks/enforce-epic-worktree-removal-gate.ps1

@@ -4,14 +4,51 @@
 
 .DESCRIPTION
     Invoked by the Claude Code PreToolUse hook on the "Bash" matcher before any Bash
-    command runs. Regex-matches git worktree remove against the envelope's tool_input.command,
-    extracts the target worktree path argument, reads
-    artifacts/orchestration/epic-orchestrator-state.json, and finds the features[] record
-    whose worktree_path matches. Allows removal only when that record's merge_status is
-    merged or worktree_removed. Denies with reason EPIC_WORKTREE_REMOVAL_BLOCKED when the
-    checkpoint is unreadable, no matching record exists, or merge_status is anything else -
-    fail-closed, following the enforce-orchestration-preimplementation-gate.ps1 precedent of
-    treating an unreadable/no-match checkpoint as deny.
+    command runs. Regex-matches git worktree remove against the envelope's
+    tool_input.command, extracts the target worktree path argument, and allows the
+    removal only when one of two checkpoint-only conditions holds. The branches are
+    evaluated in this order and are ORed, not ANDed: the first that authorizes wins and
+    the second is not consulted.
+
+      1. Epic path: artifacts/orchestration/epic-orchestrator-state.json carries a
+         features[] record whose worktree_path matches the removal target and whose
+         merge_status is merged or worktree_removed.
+      2. Parallel path: artifacts/orchestration/parallel-orchestrator-state.json has
+         route_id == "parallel" and carries an items[] entry whose worktree_path matches
+         the removal target and whose merge_status is merged or worktree_removed.
+
+    Otherwise the command is denied with reason EPIC_WORKTREE_REMOVAL_BLOCKED. The gate
+    is fail-closed in every failure mode: neither checkpoint present, either checkpoint
+    unparseable, route_id absent or not "parallel", no matching worktree_path, a matched
+    record whose merge_status is not in the allowed set, or a matched record carrying no
+    merge_status key. The cascade is a disjunction of two positive predicates; no
+    negative path returns an allow. An envelope-level anomaly is checked first and denies
+    before either checkpoint is read.
+
+    Both branches key on the worktree PATH because the command names a path, and both
+    normalize separators and trim a trailing slash on each side of the comparison, so
+    Windows- and POSIX-style paths compare equal. Path is also why the two branches are
+    mutually exclusive in practice: an epic run and a parallel run allocate worktrees
+    under distinct per-run, per-item paths, so a path recorded in one checkpoint is not a
+    path recorded in the other, and adding branch 2 cannot widen what branch 1 authorizes.
+    The authorization is a property of the path rather than of the caller, and the safety
+    property this gate protects - do not destroy unmerged work - is likewise a property of
+    the path's recorded merge state.
+
+    Accepted residual: artifacts/ is gitignored, so the parallel checkpoint persists after
+    a run ends and a stale document remains readable here. For a stale document to
+    authorize a removal it should not, a worktree would have to exist at a path
+    byte-identical, after normalization, to one it records with merge_status merged or
+    worktree_removed. Worktree paths carry a session or timestamp component, so a
+    collision is implausible, and where the recorded status is worktree_removed the path
+    was already deleted. This is a documented accepted trade, not an unexamined gap; the
+    route_id check does not reduce it, because a stale parallel checkpoint legitimately
+    declares that route.
+
+    The sibling gate enforce-parallel-worktree-removal-gate.ps1 fires on the same command
+    and owns its own reason prefix. PreToolUse denials are conjunctive, so both gates must
+    allow for a removal to proceed; this gate keeps the EPIC_WORKTREE_REMOVAL_BLOCKED
+    prefix for both of its branches so transcript attribution stays unambiguous.
 
 .NOTES
     Compatible with PowerShell 7+. No external module dependencies. Filesystem reads go
@@ -24,6 +61,7 @@ param()
 
 Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 $script:EpicCheckpointPath = 'artifacts/orchestration/epic-orchestrator-state.json'
+$script:ParallelCheckpointPath = 'artifacts/orchestration/parallel-orchestrator-state.json'
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
 
 function Get-EpicWorktreeGateCheckpointContent {
@@ -44,6 +82,52 @@ function Get-EpicWorktreeGateCheckpointContent {
     return (Get-Content -LiteralPath $script:EpicCheckpointPath -Raw)
 }
 
+function Get-EpicWorktreeGateParallelCheckpointContent {
+    <#
+    .SYNOPSIS
+        Read the raw JSON text of the parallel-orchestrator checkpoint. Tests mock
+        this function (read seam).
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    if (-not (Test-Path -LiteralPath $script:ParallelCheckpointPath -PathType Leaf)) {
+        return $null
+    }
+    return (Get-Content -LiteralPath $script:ParallelCheckpointPath -Raw)
+}
+
+function ConvertFrom-EpicWorktreeGateJson {
+    <#
+    .SYNOPSIS
+        Parse checkpoint JSON text, returning $null on unreadable/invalid content.
+    .DESCRIPTION
+        Shared by both authorization branches so the two checkpoints are parsed by
+        one implementation rather than by duplicated inline logic.
+    .PARAMETER Raw
+        Raw checkpoint text, or $null when the file does not exist.
+    .OUTPUTS
+        System.Object or $null
+    #>
+    [CmdletBinding()]
+    param(
+        [AllowNull()]
+        [string] $Raw
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Raw)) {
+        return $null
+    }
+    try {
+        return ($Raw | ConvertFrom-Json -ErrorAction Stop)
+    } catch {
+        return $null
+    }
+}
+
 function Get-EpicWorktreeRemovalCommandPath {
     <#
     .SYNOPSIS
@@ -138,6 +222,70 @@ function Test-EpicWorktreeRemovalAllowed {
     return $script:AllowedMergeStatuses -contains ([string]$FeatureRecord.merge_status)
 }
 
+function Test-ParallelCheckpointAllowsWorktreeRemoval {
+    <#
+    .SYNOPSIS
+        Decision logic for the parallel-orchestrator checkpoint path (branch 2).
+    .DESCRIPTION
+        Allows only when the checkpoint declares the parallel route identity and
+        carries an items[] entry whose worktree_path matches the removal target and
+        whose merge_status is in the allowed set. Every other shape returns $false,
+        so the branch is a positive predicate with no negative path to an allow.
+    .PARAMETER Checkpoint
+        Parsed parallel-orchestrator checkpoint, or $null when absent/unreadable.
+    .PARAMETER WorktreePath
+        The target worktree path extracted from the command text.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()]
+        $Checkpoint,
+
+        [AllowNull()]
+        [string] $WorktreePath
+    )
+
+    if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($WorktreePath)) {
+        return $false
+    }
+    $props = @($Checkpoint.PSObject.Properties.Name)
+    # Route identity is orchestrator invariant 2, so a document at the parallel path
+    # that does not declare it is malformed by the rule's own definition and inert here.
+    if ($props -notcontains 'route_id' -or ([string]$Checkpoint.route_id) -ne 'parallel') {
+        return $false
+    }
+    if ($props -notcontains 'items' -or $null -eq $Checkpoint.items) {
+        return $false
+    }
+
+    $normalizedTarget = ($WorktreePath -replace '\\', '/').TrimEnd('/')
+
+    # Scan every recorded item for a worktree_path that matches the removal target;
+    # path separators are normalized exactly as the epic branch normalizes them.
+    foreach ($item in @($Checkpoint.items)) {
+        if ($null -eq $item) {
+            continue
+        }
+        $itemProps = @($item.PSObject.Properties.Name)
+        if ($itemProps -notcontains 'worktree_path') {
+            continue
+        }
+        $normalizedItemPath = (([string]$item.worktree_path) -replace '\\', '/').TrimEnd('/')
+        if ($normalizedItemPath -ne $normalizedTarget) {
+            continue
+        }
+        if ($itemProps -notcontains 'merge_status') {
+            return $false
+        }
+        return $script:AllowedMergeStatuses -contains ([string]$item.merge_status)
+    }
+
+    return $false
+}
+
 function Get-EpicWorktreeGateAllowDecision {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -202,22 +350,19 @@ function Invoke-EpicWorktreeRemovalGateDecision {
 
     $worktreePath = Get-EpicWorktreeRemovalCommandPath -CommandText $commandText
 
-    $checkpointRaw = Get-EpicWorktreeGateCheckpointContent
-    $checkpoint = $null
-    if (-not [string]::IsNullOrWhiteSpace($checkpointRaw)) {
-        try {
-            $checkpoint = $checkpointRaw | ConvertFrom-Json -ErrorAction Stop
-        } catch {
-            $checkpoint = $null
-        }
-    }
+    $checkpoint = ConvertFrom-EpicWorktreeGateJson -Raw (Get-EpicWorktreeGateCheckpointContent)
 
     $featureRecord = Find-EpicWorktreeFeatureRecord -Checkpoint $checkpoint -WorktreePath $worktreePath
     if (Test-EpicWorktreeRemovalAllowed -FeatureRecord $featureRecord) {
         return Get-EpicWorktreeGateAllowDecision
     }
 
-    return Get-EpicWorktreeGateBlockDecision -Reason "EPIC_WORKTREE_REMOVAL_BLOCKED: git worktree remove for '$worktreePath' requires a matching epic checkpoint features[] record with merge_status in {merged, worktree_removed}. The checkpoint was unreadable, no matching record was found, or merge_status was not yet safe for removal."
+    $parallelCheckpoint = ConvertFrom-EpicWorktreeGateJson -Raw (Get-EpicWorktreeGateParallelCheckpointContent)
+    if (Test-ParallelCheckpointAllowsWorktreeRemoval -Checkpoint $parallelCheckpoint -WorktreePath $worktreePath) {
+        return Get-EpicWorktreeGateAllowDecision
+    }
+
+    return Get-EpicWorktreeGateBlockDecision -Reason "EPIC_WORKTREE_REMOVAL_BLOCKED: git worktree remove for '$worktreePath' requires either an epic checkpoint features[] record with merge_status in {merged, worktree_removed}, or a parallel-orchestrator checkpoint with route_id == ""parallel"" whose matching items[] record (matched by worktree_path) has merge_status in {merged, worktree_removed}. No checkpoint authorized this removal."
 }
 
 function Invoke-EpicWorktreeRemovalGateEntryPoint {

package/resources/claude-customizations/.claude/lib/blast-radius/BlastRadius.psm1

@@ -428,6 +428,17 @@ function Test-BlastRadiusConflict {
     .OUTPUTS
         System.Collections.Hashtable. Keys conflict (a boolean) and reasons (an
         array of hashtables with keys kind and detail).
+
+        Read the verdict from the conflict key of the returned hashtable.
+        Do not test the returned object itself: the hashtable is
+        unconditionally truthy under PowerShell boolean coercion, so
+        'if ($result)' treats every pair as contending.
+        System.Collections.Hashtable implements IDictionary and ICollection but
+        not IList, and the count-based truthiness rule applies only to IList
+        implementations, so a hashtable falls under the rule for any other
+        non-collection type and is always $true. The Python port agrees with its
+        own verdict; this mirror provably cannot, because PowerShell exposes no
+        hook by which a type can decline or change the conversion.
     #>
     [CmdletBinding()]
     [OutputType([hashtable])]

package/resources/claude-customizations/.claude/rules/parallel-orchestration.md

@@ -409,3 +409,4 @@ an unclassified key or a key present in only one copy fails loudly and names its
 - Enforcement is therefore Python validator logic, plus the TypeScript parity port, plus this prose file. It is NEVER an imported JSON Schema. No schema file is read at validation time.
 - The `parallel` route entry lives in `config/orchestration-routing.json` with `requires_pr_gate: false` (there is no run-level pull request to gate; each child's own route checkpoint enforces its per-item pull-request gate) and is mirrored byte-for-byte in `extensions/drm-copilot/resources/config/orchestration-routing.json`.
 - The `PreToolUse` merge gate `.claude/hooks/enforce-epic-merge-gate.ps1` carries a parallel allow-branch that authorizes a per-item `gh pr merge --merge` from the parallel-orchestrator checkpoint when `route_id == "parallel"`, the target item's `merge_status == "ci_green"`, and the command's PR number matches that item's `pr_number`; any other case fails closed with `EPIC_MERGE_GATE_BLOCKED`.
+- The `PreToolUse` worktree-removal gate `.claude/hooks/enforce-epic-worktree-removal-gate.ps1` likewise carries a parallel allow-branch that authorizes a per-item worktree removal from the parallel-orchestrator checkpoint when `route_id == "parallel"` and the `items[]` entry whose `worktree_path` matches the normalized removal target has `merge_status` in `{merged, worktree_removed}`; any other case — neither checkpoint present, either checkpoint unparseable, `route_id` absent or not `"parallel"`, no matching `worktree_path`, or a matched entry whose `merge_status` is outside that set or absent — fails closed with `EPIC_WORKTREE_REMOVAL_BLOCKED`. Removal is keyed on the worktree path rather than on `pr_number`, because the command names a path. This gate and the sibling gate `.claude/hooks/enforce-parallel-worktree-removal-gate.ps1`, which owns `PARALLEL_WORKTREE_REMOVAL_BLOCKED`, both fire on the same command, and `PreToolUse` denials are conjunctive, so both must allow for a removal to proceed.

package/resources/claude-customizations/.claude/skills/atomic-plan-contract/SKILL.md

@@ -139,6 +139,20 @@ For command-bearing tasks in approved plans (especially Phase 2 final-QC tasks):
 
 Any regression test task expected to fail must be tagged with `[expect-fail]` and include an auditable evidence artifact per `evidence-and-timestamp-conventions`.
 
+## Planner Adversarial Self-Review (Mandatory)
+
+Before any plan handoff, `atomic-planner` MUST complete one explicit adversarial self-review pass over every fact, assumption, and line or file citation the plan relies on. The pass is required on initial authoring and on every revision-delta round. A revision round is not exempt because it changed only part of the plan: the citations the revision touched describe the tree as it stands after the revision, and no earlier pass observed that state.
+
+Rules:
+
+- **Re-derive every citation in this pass.** Any line, file, test, or assertion that the planner's own edit touched, added, or removed in the current authoring or revision pass MUST be re-derived directly against current repository state in that same pass. The prohibited source is a citation carried forward from an earlier round, including one the planner itself verified in a prior round: that earlier verification observed the tree before the intervening edits, so it is evidence about a superseded state rather than about the state the plan now asserts.
+- **Re-check the sibling region.** The self-review MUST re-check the sibling lines, tests, and assertions that sit in the same file or region as any edited citation. The failure mechanism is sibling invalidation: a fix to one line can invalidate an assumption baked into a sibling line or test that a prior round's citation did not cover, so a pass that verifies only the edited line leaves the invalidated sibling unreported and it surfaces as a defect on a later round.
+
+Declaration requirement. Every plan handoff MUST carry exactly one of these two signal lines, written in the directive-line form already used elsewhere in this contract:
+
+- `SELF-REVIEW: RE-DERIVED THIS PASS` — the adversarial self-review pass completed in this pass. This signal MUST be followed by an enumeration of the citations re-derived in that pass, one entry per citation, each naming the file and the line, test, or identifier that was re-derived. A signal carrying no enumeration is not a completed declaration.
+- `SELF-REVIEW: BLOCKED` — the pass could not be completed. This signal halts the handoff. It does not permit a self-approved plan: the planner reports the blocking reason and waits for the caller rather than proceeding to hand off an unverified plan.
+
 ## Preflight Validation (Planner ↔ Executor)
 
 When validating or handing off plans for execution:
@@ -149,6 +163,20 @@ When validating or handing off plans for execution:
 - If revisions are required, provide a precise plan delta and repeat validation until all clear.
 - If the required planner ↔ executor handoff cannot be started or completed, stop and report blocked state; do not self-approve the plan.
 
+Review depth and reporting rules:
+
+- **Review the entire plan in one pass.** Under `DIRECTIVE: PREFLIGHT VALIDATION ONLY`, `atomic-executor` MUST continue checking every remaining phase, task, and prose region after finding an initial defect. Stopping at the first defect is prohibited: the unchecked remainder holds defects that the same pass could have reported, and each one that is left unreported becomes an additional round.
+- **Enumerate every defect found.** `PREFLIGHT: REVISIONS REQUIRED` output MUST list every defect found in that pass, not only the first. The failure mechanism is round inflation: a single-defect report causes the next round to rediscover a defect the same pass could have reported, so the round count rises without the review having covered more of the plan.
+- **Check the delta against its own rule.** Before returning either signal, `atomic-executor` MUST check its proposed fix or delta text against every rule the plan enforces, including that delta's own prose against the same violation class it is remediating. Worked example: the delta prose of a tonality-compliance fix must not itself contain the hyperbole or humor that `.claude/rules/tonality.md` prohibits, because a delta that violates the rule it is written to enforce reintroduces the finding it closes.
+- **Two-round target.** The quality bar is a target of at most two preflight rounds per plan. Exhaustive first-pass review is the mechanism that holds the round count to that target: a pass that reports every defect it can find leaves at most a revision round and a confirming round, whereas a pass that reports one defect at a time cannot reach the target however correct each individual report is.
+
+Convergence signal. Every preflight return, whether it carries `PREFLIGHT: ALL CLEAR` or `PREFLIGHT: REVISIONS REQUIRED`, MUST additionally carry exactly one of these two forward-looking lines:
+
+- `CONVERGENCE: NO FURTHER ROUNDS EXPECTED` — the reviewer expects the plan to clear without a further round.
+- `CONVERGENCE: FURTHER ROUNDS LIKELY` — the reviewer expects at least one further round, and states why.
+
+The convergence line is a required signal rather than free prose. It is a second required line accompanying the preflight signal, not a third value of the signal set that the `Require one of the exact signals:` bullet above enumerates: that bullet's two-value set is unchanged, and every return carries one value from it together with one convergence line.
+
 ## Validator Gate (Mandatory)
 
 Before a plan can be treated as approved:

package/resources/claude-customizations/.claude/skills/cleanup-merged-worktrees/SKILL.md

@@ -3,11 +3,23 @@ name: cleanup-merged-worktrees
 description: 'Detect, consolidate, and delete git worktrees/branches that are fully merged into main; use after an epic or feature''s PRs have merged and stale drm-copilot-wt-* branches/worktrees remain, driving the detect -> report -> consolidate -> pr-author handoff -> post-merge deletion workflow.'
 allowed-tools:
   - Read
+  - Grep
+  - Glob
+  - Agent
   - "Bash(bash scripts/bash/cleanup-worktrees.sh *)"
   - "Bash(git fetch *)"
   - "Bash(git merge-base *)"
   - "Bash(git push *)"
   - "Bash(git rev-parse *)"
+  - "Bash(git status *)"
+  - "Bash(git log *)"
+  - "Bash(git show *)"
+  - "Bash(git diff *)"
+  - "Bash(git branch -r*)"
+  - "Bash(git worktree list*)"
+  - "Bash(gh issue view *)"
+  - mcp__drm-copilot__new_potential_bug_entry
+  - mcp__drm-copilot__potential_to_issue
 ---
 
 # Cleanup Merged Worktrees
@@ -35,8 +47,12 @@ and is out of the script's scope.
   which carry unmerged or unique work (`NOT_MERGED`, `HAS_UNIQUE_RESIDUALS`).
 - When stranded documentation/agent-memory commits were appended to a worktree branch
   after its feature content already merged and must be preserved before deletion.
+- When a worktree is reported `BLOCKED-DIRTY`, or its branch is classified `NOT_MERGED`
+  or `HAS_UNIQUE_RESIDUALS`, and the uncommitted or unmerged content it holds must be
+  triaged into disposable versus must-preserve before the worktree can ever be deleted.
 - Do not use this skill to manage remote branches; its scope is local branches and
-  local worktree registrations only.
+  local worktree registrations only, except for the explicitly confirmed origin-branch
+  offer in the Dirty Worktree Triage Procedure's final step.
 
 ## Report Line Contract
 
@@ -99,7 +115,9 @@ The script emits pipe-delimited, `LC_ALL=C`-ordered records, one per line:
    (without force; a dirty worktree is reported via `DIRTY|` lines and skipped), then
    deletes branches with `git branch -D`. The now-merged `documentationandmemories`
    branch and its worktree become `MERGED_CLEAN` instances and are cleaned up by the same
-   mechanics.
+   mechanics. Any worktree left standing afterward — reported `BLOCKED-DIRTY`, or whose
+   branch classified `NOT_MERGED` or `HAS_UNIQUE_RESIDUALS` — is not abandoned; it moves
+   to the Dirty Worktree Triage Procedure below.
 
 ## Nothing to Consolidate (Short Path)
 
@@ -108,6 +126,108 @@ with an empty cherry-pick-candidate list, skip steps 3-5 entirely: proceed direc
 the report to `bash scripts/bash/cleanup-worktrees.sh --apply`. Cleanup completes in a
 single session with no PR.
 
+## Dirty Worktree Triage Procedure
+
+**Trigger.** A worktree reported `ACTION|worktree-remove|<path>|BLOCKED-DIRTY` (with
+accompanying `DIRTY|<path>|<status-porcelain-line>` records), or a branch classified
+`NOT_MERGED` or `HAS_UNIQUE_RESIDUALS`, carries uncommitted or unmerged content the
+script correctly refuses to discard. That refusal is correct and this procedure never
+overrides it — a dirty worktree is never force-removed. This procedure is the systematic
+follow-up: deciding, per worktree, whether that content is disposable or must be
+preserved before the worktree can ever be deleted.
+
+Steps 1-7 are read-only investigation. Run them per worktree, or fan out one
+`Agent(general-purpose)` investigation per worktree (or small batch) concurrently per
+step 8, each returning a `SAFE_TO_DELETE` / `PRESERVE` verdict with justification citing
+specific files or commit SHAs, before step 9 acts on any finding.
+
+1. **Re-verify current state before analyzing.** Worktrees can be actively in use by
+   another concurrent session. Re-run `git status --porcelain` in the worktree and
+   re-check the branch's merge status fresh — do not reuse the original scan's
+   snapshot. If the worktree's `.git`/index/HEAD mtimes show activity in the last few
+   minutes, treat it as possibly live and pause rather than analyze it as abandoned.
+
+2. **Check committed-but-unmerged commits, not only the working tree.** Run
+   `git log main..<branch> --oneline`. Some worktrees carry real commits that never
+   merged, separate from uncommitted working-tree changes. Both need the classification
+   in step 5.
+
+3. **Check for equivalent content already on `main`, by topic, not only by path.** For
+   every dirty, untracked, or unmerged file, check `git show main:<path>` at the same
+   path, and also grep broadly across the relevant shared namespace (for example
+   `.claude/agent-memory/**` for lesson files, `docs/features/**` for feature docs)
+   since the same fact is often re-recorded under a different filename on `main`.
+
+4. **For feature-folder doc snapshots** (`issue.md`, `plan.md`, `spec.md`,
+   `research/*`), check whether the feature is fully closed on `main` — acceptance
+   criteria all checked, code-review/feature-audit/policy-audit artifacts present, an
+   evidence trail present. An earlier draft of an already-closed feature is almost
+   always fully superseded; diff it against the closed feature's final artifacts to
+   confirm rather than assume.
+
+5. **Classify any content that is not obviously superseded** into exactly one of:
+   - `DEAD_ONE_OFF` — real, but tied to an already-executed, closed plan with no reuse
+     elsewhere (check whether the same pattern appears in shared `.claude/skills/**`
+     templates or in other feature plans). Low value; safe to discard even though it is
+     not technically duplicated.
+   - `ALREADY_SOLVED_ELSEWHERE` — the underlying problem it documents is fixed a
+     different way on `main` (check `main`'s current code/config/script, not only its
+     memory files — a memory file can describe a bug that no longer exists).
+   - `STALE_OR_CONTRADICTED` — `main`'s current version of the same lesson has since
+     been corrected to state something different or opposite. This is not merely
+     redundant; it is actively wrong, and discarding is the right call.
+   - `GENUINELY_NEW` / `STILL_RELEVANT` — not found anywhere else, or it corrects
+     something `main` currently gets wrong, or it documents unresolved scope on a
+     still-open issue (verify open/closed with `gh issue view <n>`; never assume). Must
+     be preserved before the worktree is deleted.
+
+6. **Handle non-memory dirty content on its own terms.** Some worktrees carry stale
+   build artifacts (a modified `.csproj`/`packages.config`/`app.config` from a build run
+   in that worktree) rather than documentation. Diff a representative sample against
+   `main` (`git diff main -- <path>`) to characterize the change before deciding it is
+   disposable.
+
+7. **Recognize orphaned non-worktree directories.** A path can still exist on disk
+   under a worktree-tracking folder after `git worktree remove` partially ran or
+   failed, with no `.git` file inside and no entry in `git worktree list`. These are no
+   longer worktrees — flag them for plain filesystem removal, not `git worktree
+   remove`, which will misfire or no-op on them. Filesystem removal of an orphaned
+   directory is a destructive action outside this skill's pre-approved tool surface; it
+   requires explicit user confirmation each time, the same as any other irreversible
+   delete.
+
+8. **Parallelize the triage.** Steps 1-7 are pure read-only investigation. Fan out one
+   `Agent(general-purpose)` investigation per worktree (or a small batch) concurrently,
+   each following steps 1-7 and returning a structured `SAFE_TO_DELETE` / `PRESERVE`
+   verdict with justification. This scales far better than triaging serially.
+
+9. **Route `PRESERVE` findings through the existing consolidation flow** (the
+   `documentationandmemories` branch/PR mechanism in steps 3-4 of the End-to-End
+   Workflow above) before that worktree's dirty content is discarded. If a finding
+   describes unresolved product scope rather than a process lesson, promote it to a
+   real follow-up issue instead of folding it into the docs/memory PR: file it with
+   `mcp__drm-copilot__new_potential_bug_entry` and promote with
+   `mcp__drm-copilot__potential_to_issue` per
+   `.claude/skills/feature-promotion-lifecycle/SKILL.md`. For a `SAFE_TO_DELETE`
+   verdict, discard the content as a distinct, individually confirmed manual action —
+   clear the dirty working tree, or delete a disposable `NOT_MERGED`/
+   `HAS_UNIQUE_RESIDUALS` branch directly. This is never automated: the script's
+   classification ladder and apply-mode allowlist are never changed to accept these
+   states, so a `--apply` run never deletes them on its own, before or after triage. If
+   discarding the working-tree content changes the branch's classification (for example
+   to content-neutral against `main`), a follow-up report/apply pass then picks it up
+   through the normal deterministic path.
+
+10. **After local branch deletion, check origin too.** This skill is local-only by
+    design (see "When to Use This Skill"), which leaves stale branches on the remote for
+    anything already merged. After `--apply` finishes, diff the deleted-local-branch
+    list against `git branch -r` (post-prune) to find remote branches whose local
+    counterpart is gone, and offer to delete the remainder on origin. Because this
+    mutates shared, visible remote state, each deletion requires explicit user
+    confirmation — never delete an origin branch as an automatic consequence of local
+    cleanup, and never rely on this skill's general `Bash(git push *)` allowance to
+    perform it silently.
+
 ## Prohibited Shortcuts
 
 - Never invoke `gh pr create` or `gh pr edit --body*` from this skill or the scripts. PR
@@ -116,10 +236,19 @@ single session with no PR.
 - Never pass a force flag to `git worktree remove`. A dirty worktree blocks deletion and
   is reported for manual handling; it is never force-removed.
 - Never execute `git worktree prune`. Prunable registrations are report-only.
-- Never act on `NOT_MERGED`, `HAS_UNIQUE_RESIDUALS`, or `PROTECTED_CURRENT` candidates;
-  the caller's worktree and branch, and the main worktree, are never mutated.
+- Never act on `NOT_MERGED`, `HAS_UNIQUE_RESIDUALS`, or `PROTECTED_CURRENT` candidates
+  through the script or its apply-mode allowlist; `--apply` never mutates them, and the
+  caller's worktree and branch, and the main worktree, are never mutated under any
+  disposition. The Dirty Worktree Triage Procedure's `SAFE_TO_DELETE` verdict authorizes
+  only a distinct, individually confirmed manual action outside that automated path for
+  `NOT_MERGED`/`HAS_UNIQUE_RESIDUALS` — never a change to the classification ladder
+  itself, and never for `PROTECTED_CURRENT`.
 - Never use commit-message text matching as a classification input, and never
   auto-resolve cherry-pick conflicts.
+- Never delete an origin branch, or run plain filesystem removal on an orphaned
+  worktree-tracking directory, without explicit per-item user confirmation — both are
+  outside this skill's pre-approved tool surface regardless of how the triage verdict
+  came out.
 
 ## Cross-References
 
@@ -130,3 +259,6 @@ single session with no PR.
 - `.claude/rules/shell.md` — the bash toolchain (shfmt/shellcheck/bats/kcov), the
   500-line cap, the no-temp-files test policy, and the `CLEANUP_WT_GIT_BIN` seam
   convention.
+- `.claude/skills/feature-promotion-lifecycle/SKILL.md` — the potential-entry-to-issue
+  promotion path used by the Dirty Worktree Triage Procedure's step 9 for `PRESERVE`
+  findings that describe unresolved product scope.

package/resources/claude-customizations/.claude/skills/parallel-add/SKILL.md

@@ -64,7 +64,9 @@ re-derivation is mandatory and is not an optimization to skip when the checkpoin
    required parsed `config/blast-radius.json` mapping, which push-down publishes into the
    destination workspace. `conflicts(a, b, config)` in `scripts/dev_tools/compute_blast_radius.py`
    (defined in `scripts/dev_tools/_blast_radius_conflicts.py`) remains the repository authority and
-   the parity reference. Map each conflicting pair onto an `(int, int)` conflict edge
+   the parity reference. Read the verdict from the conflict key of the returned hashtable.
+   The hashtable itself is always truthy, so a bare boolean test on the result treats every pair as
+   conflicting. Map each conflicting pair onto an `(int, int)` conflict edge
    of `items[].issue_num` values, normalized so `a < b`. Do not reimplement the relation and do not
    compute edges over the unstarted subset only: an in-flight conflict is precisely what the
    admission decision turns on.

package/resources/claude-customizations/.claude/skills/parallel-orchestrate/SKILL.md

@@ -387,15 +387,21 @@ checkout, never from inside a child worktree — issues `git worktree remove <wo
 success it records `merge_status: worktree_removed` and `worktree_removed_at`, then regenerates
 `docs/features/parallel/<slug>/parallel-status.md`.
 
-Mechanical gating of this command for parallel worktrees is F7 scope.
-`.claude/hooks/enforce-epic-worktree-removal-gate.ps1` is a project-wide `PreToolUse` Bash-matcher
-hook that denies any `git worktree remove` unless the epic checkpoint carries a matching
-`features[]` record whose `merge_status` is `merged` or `worktree_removed`; an unreadable checkpoint
-or an absent record also denies. Its block reason is `EPIC_WORKTREE_REMOVAL_BLOCKED`. A parallel run
-has no epic checkpoint record for its worktrees, so removal is denied until F7 both delivers
-`enforce-parallel-worktree-removal-gate.ps1` and coordinates the epic gate's allow conditions:
-`PreToolUse` denials are conjunctive, so a new allow-hook alone cannot override the existing deny.
-This feature ships no hook file and makes no `.claude/settings.json` change.
+Mechanical gating of this command for parallel worktrees is delivered. Both halves have landed.
+`.claude/hooks/enforce-parallel-worktree-removal-gate.ps1` exists and is registered in
+`.claude/settings.json` on the `Bash` matcher; it authorizes a removal from the
+parallel-orchestrator checkpoint and owns the block reason
+`PARALLEL_WORKTREE_REMOVAL_BLOCKED`. `.claude/hooks/enforce-epic-worktree-removal-gate.ps1` is a
+project-wide `PreToolUse` Bash-matcher hook registered alongside it whose block reason is
+`EPIC_WORKTREE_REMOVAL_BLOCKED`; it now carries a second, parallel allow-branch, so it authorizes a
+removal either from a matching epic checkpoint `features[]` record or from a parallel-orchestrator
+checkpoint whose `route_id` is `parallel` and whose matching `items[].worktree_path` record has
+`merge_status` in `{merged, worktree_removed}`. An unreadable checkpoint, an absent record, or a
+non-authorizing `merge_status` still denies on both branches. The coordination matters because
+`PreToolUse` denials are conjunctive: a new allow-hook alone could not have overridden the epic
+gate's independent deny, which is why the epic gate itself had to gain the parallel branch.
+The parallel-orchestrator-surface feature (F7) shipped no hook file and made no
+`.claude/settings.json` change of its own.
 
 ## Documentation Maintenance Boundaries
 
@@ -736,6 +742,9 @@ against `items[].worktree_path`. Removal is allowed only when that item's `merge
 or `worktree_removed`; anything else — including an unreadable checkpoint or no matching record —
 denies with a reason prefixed `PARALLEL_WORKTREE_REMOVAL_BLOCKED`. Commands that are not
 `git worktree remove` always allow. This is the mechanical counterpart to `## Worktree Cleanup`.
+`.claude/hooks/enforce-epic-worktree-removal-gate.ps1` fires on the same command and now carries a
+matching parallel allow-branch keyed on the same checkpoint, so both gates must allow for a removal
+to proceed.
 
 **Invocation-origin extension.** `.claude/hooks/enforce-epic-invocation-origin.ps1` was extended
 additively so `$script:GatedSubagentTypes` lists `epic-planner`, `epic-orchestrator`,

package/resources/claude-customizations/.claude/skills/parallel-plan/SKILL.md

@@ -214,7 +214,9 @@ as-is and never reimplemented here:
   `compute_blast_radius.py`. The signature takes three arguments; the third is the parsed
   `config/blast-radius.json`. Reasons come from the fixed vocabulary
   `{path_overlap, module_overlap, shared_surface_overlap, contract_dependency}`, and the relation
-  fails closed.
+  fails closed. Read the verdict from the conflict field of the returned ConflictResult.
+  The result's boolean projection now agrees with that field, so `if conflicts(a, b, config):`
+  yields the verdict rather than the unconditional truth a bare object test gave before issue #576.
 
 **The F1a corrections (issue #452, merged PR #453) are load-bearing.** Derivation now reaches
 separator-free repository-root shared surfaces from plan and spec text, admitting such a token only
@@ -303,6 +305,11 @@ The library returns the partition; the planner supplies the record fields.
    item is `prepared` and radius-validated. Derive the conflict edge set by applying
    `Test-BlastRadiusConflict` to every unordered pair of `declared` radii, then pass the pairs as
    `--edges "<a>:<b> ..."` and the item keys as `--keys "<k1> <k2> ..."`.
+   Read the verdict from the conflict key of the returned hashtable.
+   The hashtable itself is always truthy, so a bare boolean test on the result treats every pair as
+   conflicting and serializes the whole run. This is the sibling hazard to the `@(...)` warning
+   above for `Test-BlastRadius`: that function writes an `IList`-shaped pipeline result whose
+   emptiness is falsy, while this one returns a hashtable whose emptiness is not expressible at all.
 2. Immediately after the conflict-edge set is derived and before anything consumes it, run the
    lane-assertion diagnostic:
    `poetry run python -m scripts.dev_tools.parallel_lane_assertion --manifest docs/features/parallel/<slug>/parallel.md --edges "<a>:<b> ..."`

package/resources/claude-customizations/.claude/skills/pr-context-artifacts/SKILL.md

@@ -28,3 +28,25 @@ If the artifacts are missing or stale relative to the current branch state, re-g
 - Do not infer the refresh base from the repository default branch unless merge-base resolution fails for all candidates.
 - Treat an already-fresh artifact pair as authoritative; do not refresh solely because no explicit `PRBaseBranch` input was provided.
 
+### Freshness Cross-Check
+
+Both artifacts open with a `Context generated` section carrying the generation timestamp and a
+`Head SHA:` line. Decide freshness from those two values in two steps, and from nothing else.
+
+1. **Pair identity.** The generated-context timestamp must be byte-identical in the summary and in
+   the appendix. A mismatch proves the two files came from different invocations — a summary
+   refreshed while a stale appendix persists, or the reverse — so the pair does not describe one
+   run and must be regenerated.
+2. **Head binding.** The head SHA recorded in both files must equal the current head of the branch
+   under review. A mismatch proves the pair predates the current head, so it describes a different
+   diff than the one being reviewed and must be regenerated.
+
+File existence and file modification time are not freshness signals. A file left at the expected
+path by a previous invocation satisfies an existence check, and a stale file that was copied or
+touched satisfies a modification-time check. Both operands of the cross-check above are read from
+the artifacts themselves and from git, so the check is deterministic and does not depend on a wall
+clock.
+
+When the head SHA renders the `(unknown)` token, the collected context carried no head SHA. Head
+binding cannot be established in that case, so treat the pair as unverified and regenerate it.
+

package/resources/claude-customizations/.claude/skills/remediation-handoff-atomic-planner/SKILL.md

@@ -81,6 +81,10 @@ Timestamp rule:
 
 A cycle with fewer than five artifacts is malformed. A cycle that uses the same timestamp value for both its `remediation/<ts>/` and `audit/<ts>/` folders is malformed unless entry and exit genuinely ran within the same minute — the two folders remain distinct either way, since one is named `remediation/` and the other `audit/`.
 
+### Cycle-Document Sweep Scope
+
+A comprehensive or final sweep in a remediation cycle covers that cycle's own plan and audit documents — `remediation-plan.md`, `code-review.md`, `feature-audit.md`, and `policy-audit.md` — in addition to production and test code. The failure mechanism a code-only sweep leaves open is self-referential rule violation: a policy-compliance fix whose own descriptive text violates the policy it enforces is written into one of those four documents rather than into code, so a sweep scoped to code only reports no finding and the violation ships with the cycle.
+
 ## Plan Shape
 
 `remediation/<entry-ts>/remediation-plan.md` MUST conform to `.claude/skills/atomic-plan-contract/SKILL.md`. In particular:
@@ -102,6 +106,12 @@ After the plan is authored, `atomic-executor` runs preflight under the directive
 
 The orchestrator records the preflight outcome in `remediation_loop.cycles[current_cycle].preflight` with `iterations` (counter) and `final_status` (`clear|changes_requested|pending`).
 
+The exhaustive-pass, defect-enumeration, and delta-self-check rules that govern how `atomic-executor` conducts preflight are defined in the `## Preflight Validation (Planner ↔ Executor)` section of `.claude/skills/atomic-plan-contract/SKILL.md` and are not restated here.
+
+Alongside `iterations` and `final_status`, the orchestrator also records in `remediation_loop.cycles[current_cycle].preflight` the convergence line `atomic-executor` returned on that round, which is one of `CONVERGENCE: NO FURTHER ROUNDS EXPECTED` or `CONVERGENCE: FURTHER ROUNDS LIKELY`. This convergence field extends the field set already recorded at `remediation_loop.cycles[current_cycle].preflight` rather than replacing it: `iterations` and `final_status` continue to be recorded exactly as stated above, and the convergence field is written in addition to them.
+
+Iteration ceiling. When a cycle's `iterations` would exceed 2, the orchestrator records `final_status: "blocked_preflight_iteration_limit"`, halts the preflight sub-loop, and escalates to the caller, rather than continuing the sub-loop indefinitely. `blocked_preflight_iteration_limit` is a fourth `final_status` value extending the `clear|changes_requested|pending` enumeration stated above. This ceiling bounds the repeat-until-clear behavior stated above it: the sub-loop still repeats until `PREFLIGHT: ALL CLEAR` is returned, and the ceiling supplies the terminating condition for the case where that signal is not reached within two iterations.
+
 ## Execution and Reaudit
 
 When preflight is clear, `atomic-executor` executes the plan task-by-task. The executor invokes workers (`python-typed-engineer`, `typescript-engineer`, `csharp-typed-engineer`, `powershell-typed-engineer`) internally as needed. The orchestrator does not call workers.

package/resources/codex-and-agents-customizations/.agents/skills/pr-context-artifacts/SKILL.md

@@ -27,3 +27,25 @@ If the artifacts are missing or stale relative to the current branch state, re-g
 - When `PRBaseBranch` is missing or ambiguous, resolve it first with `pr-base-branch-merge-base` before running the collector.
 - Do not infer the refresh base from the repository default branch unless merge-base resolution fails for all candidates.
 - Treat an already-fresh artifact pair as authoritative; do not refresh solely because no explicit `PRBaseBranch` input was provided.
+
+### Freshness Cross-Check
+
+Both artifacts open with a `Context generated` section carrying the generation timestamp and a
+`Head SHA:` line. Decide freshness from those two values in two steps, and from nothing else.
+
+1. **Pair identity.** The generated-context timestamp must be byte-identical in the summary and in
+   the appendix. A mismatch proves the two files came from different invocations — a summary
+   refreshed while a stale appendix persists, or the reverse — so the pair does not describe one
+   run and must be regenerated.
+2. **Head binding.** The head SHA recorded in both files must equal the current head of the branch
+   under review. A mismatch proves the pair predates the current head, so it describes a different
+   diff than the one being reviewed and must be regenerated.
+
+File existence and file modification time are not freshness signals. A file left at the expected
+path by a previous invocation satisfies an existence check, and a stale file that was copied or
+touched satisfies a modification-time check. Both operands of the cross-check above are read from
+the artifacts themselves and from git, so the check is deterministic and does not depend on a wall
+clock.
+
+When the head SHA renders the `(unknown)` token, the collected context carried no head SHA. Head
+binding cannot be established in that case, so treat the pair as unverified and regenerate it.

package/resources/codex-and-agents-customizations/.codex/config.toml

@@ -2,7 +2,7 @@ default_permissions = ":danger-full-access"
 
 [mcp_servers.drm-copilot]
 command = "npx"
-args = ["-y", "@danmoisan/drm-copilot-mcp@1.1.5"]
+args = ["-y", "@danmoisan/drm-copilot-mcp@1.1.6"]
 required = true
 enabled_tools = [
     "collect_commit_context",

package/resources/customizations/.github/skills/pr-context-artifacts/SKILL.md

@@ -27,3 +27,25 @@ If the artifacts are missing or stale relative to the current branch state, re-g
 - When `PRBaseBranch` is missing or ambiguous, resolve it first with `pr-base-branch-merge-base` before running the collector.
 - Do not infer the refresh base from the repository default branch unless merge-base resolution fails for all candidates.
 - Treat an already-fresh artifact pair as authoritative; do not refresh solely because no explicit `PRBaseBranch` input was provided.
+
+### Freshness Cross-Check
+
+Both artifacts open with a `Context generated` section carrying the generation timestamp and a
+`Head SHA:` line. Decide freshness from those two values in two steps, and from nothing else.
+
+1. **Pair identity.** The generated-context timestamp must be byte-identical in the summary and in
+   the appendix. A mismatch proves the two files came from different invocations — a summary
+   refreshed while a stale appendix persists, or the reverse — so the pair does not describe one
+   run and must be regenerated.
+2. **Head binding.** The head SHA recorded in both files must equal the current head of the branch
+   under review. A mismatch proves the pair predates the current head, so it describes a different
+   diff than the one being reviewed and must be regenerated.
+
+File existence and file modification time are not freshness signals. A file left at the expected
+path by a previous invocation satisfies an existence check, and a stale file that was copied or
+touched satisfies a modification-time check. Both operands of the cross-check above are read from
+the artifacts themselves and from git, so the check is deterministic and does not depend on a wall
+clock.
+
+When the head SHA renders the `(unknown)` token, the collected context carried no head SHA. Head
+binding cannot be established in that case, so treat the pair as unverified and regenerate it.