@danmoisan/drm-copilot-mcp 1.1.3 → 1.1.5

package/resources/claude-customizations/.claude/hooks/enforce-prd-feature-before-planner.ps1

@@ -14,13 +14,31 @@
     Feature folder resolution order:
       1. Scan the prompt text for any path matching
          docs/features/active/<token>, accepting both forward-slash and
-         backslash separators. The longest match wins; when it points at a
-         file (ends with .md), use its parent directory.
-      2. If no candidate was found in the prompt, read the feature-folder field
+         backslash separators. Truncate every match to two segments past the
+         docs/features/active/ prefix -- that is, to exactly four path segments:
+         docs, features, active, and the feature-folder name. Truncation is
+         depth-insensitive, so the feature folder itself, a spec.md path, a
+         research/ artifact path, and an evidence/ artifact path all resolve to
+         the same folder. A match that truncates to fewer than four segments is
+         rejected. Candidates are deduplicated preserving first-occurrence
+         order.
+      2. Select among the distinct candidates: one candidate is used directly;
+         otherwise the candidate equal to the checkpoint's feature-folder field
+         is preferred, because the checkpoint is the orchestrator's own record of
+         which feature is in flight; otherwise the earliest-occurring candidate
+         in the prompt wins, because the orchestrator names the active feature
+         folder before citing artifacts inside it.
+      3. If no candidate was found in the prompt, read the feature-folder field
          from artifacts/orchestration/orchestrator-state.json.
-      3. If neither yields a folder, block with a reason instructing the caller
+      4. If neither yields a folder, block with a reason instructing the caller
          to reference a feature folder explicitly.
 
+    Known limitation: resolution stops at the feature-folder segment, so it does
+    not descend into a version folder (v1/, v2/). No versioned folder exists
+    under docs/features/active/ today, and issue.md sits at the feature root in
+    every case, so the limitation is inert; it is recorded here rather than coded
+    around.
+
     Once the folder is resolved, the hook reads the persisted work-mode marker
     (`- Work Mode: minor-audit|full-feature|full-bug|full`) from that folder's
     issue.md, per the mode contract in
@@ -30,11 +48,16 @@
       - full-bug     -> spec.md only is required.
       - minor-audit  -> neither is required; issue.md carries the acceptance
                         criteria for this mode.
-      - marker absent, unreadable, or unrecognized -> fail closed to the
-        strictest set (spec.md and user-story.md), and the block reason states
-        that the work mode could not be determined so the operator can tell
-        this case apart from a genuine missing prerequisite. The legacy `full`
-        marker normalizes to full-feature's requirement set.
+      - marker absent, unreadable, or unrecognized -> deny on a distinct
+        decision path that names the resolved folder and the issue.md path it
+        probed and states adding or correcting the marker as the remedy. That
+        path does not run the required-file probe and names neither prerequisite
+        document, because when the mode is unknown no prerequisite set is
+        knowable: a set containing user-story.md cannot be satisfied by full-bug
+        or minor-audit work without violating the lifecycle contract, and the
+        empty set would fail open. The delegation is still denied, so the gate
+        remains fail-closed. The legacy `full` marker normalizes to
+        full-feature's requirement set.
 
     If any required file is missing, the script emits a PreToolUse JSON
     response with hookSpecificOutput.permissionDecision='deny' and a reason
@@ -137,9 +160,14 @@ function Get-PrdFeatureRequiredFile {
         allowed.
     .DESCRIPTION
         full-feature requires spec.md and user-story.md; full-bug requires
-        spec.md only; minor-audit requires neither. A $null or unrecognized
-        mode fails closed to the strictest set (spec.md and user-story.md) so
-        an undeterminable mode never becomes permissive.
+        spec.md only; minor-audit requires neither.
+
+        The default arm returns spec.md alone. It is not reached from the
+        decision path for an undeterminable mode, which denies on its own branch
+        without probing at all; the arm exists so a direct caller passing a $null
+        or unrecognized mode never receives a permissive empty set, and it must
+        not name user-story.md, because that document is required to be ABSENT
+        for full-bug and minor-audit work.
     #>
     [CmdletBinding()]
     [OutputType([string[]])]
@@ -154,7 +182,7 @@ function Get-PrdFeatureRequiredFile {
         'full-feature' { return [string[]]@('spec.md', 'user-story.md') }
         'full-bug' { return [string[]]@('spec.md') }
         'minor-audit' { return [string[]]@() }
-        default { return [string[]]@('spec.md', 'user-story.md') }
+        default { return [string[]]@('spec.md') }
     }
 }
 
@@ -191,9 +219,22 @@ function Get-PrdFeatureCheckpointFolder {
 function Find-PrdFeatureFolderFromPrompt {
     <#
     .SYNOPSIS
-        Scans a prompt string for docs/features/active/<...> path tokens and
-        returns the longest unique match resolved to a folder path. Returns
-        $null when no match is found.
+        Scans a prompt string for docs/features/active/<...> path tokens,
+        truncates each to exactly four path segments, and returns the selected
+        feature folder. Returns $null when no token truncates to four segments.
+    .DESCRIPTION
+        Truncation to four segments -- docs, features, active, and the
+        feature-folder name -- is two segments past the docs/features/active/
+        prefix, so the depth at which an artifact is cited cannot change which
+        folder is resolved. Candidates are deduplicated preserving
+        first-occurrence order; selection among two or more distinct candidates
+        prefers the checkpoint's feature-folder field and otherwise takes the
+        earliest occurrence in the prompt.
+
+        The return value is a repo-relative path normalized to forward slashes,
+        or $null. The function reads no file except through the existing
+        checkpoint seam, and it is deterministic for a given prompt and
+        checkpoint value.
     #>
     [CmdletBinding()]
     [OutputType([string])]
@@ -214,22 +255,56 @@ function Find-PrdFeatureFolderFromPrompt {
         return $null
     }
 
-    $unique = @{}
+    # Deduplicate preserving FIRST-OCCURRENCE order. A [hashtable] must not be
+    # used here: PowerShell hashtable key enumeration order is unspecified, so a
+    # first-occurrence selection rule fed by a hashtable is not deterministic.
+    [System.Collections.Generic.List[string]] $candidates = [System.Collections.Generic.List[string]]::new()
     foreach ($m in $matchList) {
         $normalized = ($m.Value -replace '\\', '/').TrimEnd('/')
-        $unique[$normalized] = $true
+
+        # Truncate to exactly two segments past the docs/features/active/ prefix,
+        # that is, to the four segments docs, features, active, and the feature
+        # folder name. Truncation is depth-insensitive, so a folder path, a
+        # spec.md path, a research/ artifact path, and an evidence/ artifact path
+        # all reduce to the same value. A '.' component is a path no-op and is
+        # discarded first, so a degenerate token such as docs/features/active/.
+        # yields three segments and is rejected rather than resolved.
+        $segments = @($normalized -split '/' | Where-Object { $_ -ne '' -and $_ -ne '.' })
+        if ($segments.Count -lt 4) {
+            continue
+        }
+
+        $truncated = ($segments[0..3] -join '/')
+        if (-not $candidates.Contains($truncated)) {
+            $candidates.Add($truncated)
+        }
     }
 
-    $candidates = @(@($unique.Keys) | Sort-Object -Property Length -Descending)
-    $best = $candidates[0]
+    if ($candidates.Count -eq 0) {
+        return $null
+    }
 
-    # If the longest match ends in .md, treat it as a file and use its parent.
-    if ($best -match '\.md$') {
-        $parent = $best -replace '/[^/]+\.md$', ''
-        return $parent
+    # One distinct candidate is used directly, so the common case never consults
+    # the checkpoint.
+    if ($candidates.Count -eq 1) {
+        return $candidates[0]
+    }
+
+    # More than one distinct feature folder was cited. Prefer the folder the
+    # orchestrator itself records as in flight: the checkpoint is the
+    # authoritative disambiguator, and it reuses a seam this hook already owns.
+    $checkpointFolder = Get-PrdFeatureCheckpointFolder
+    if ($checkpointFolder) {
+        $checkpointNormalized = ($checkpointFolder -replace '\\', '/').TrimEnd('/')
+        if ($candidates.Contains($checkpointNormalized)) {
+            return $checkpointNormalized
+        }
     }
 
-    return $best
+    # Tiebreak of last resort: the orchestrator supplies the active feature folder
+    # among its delegation inputs and names it before citing artifacts inside it,
+    # so a cross-reference to another feature appears later in the prompt.
+    return $candidates[0]
 }
 
 function Get-PrdFeatureMissingFile {
@@ -308,10 +383,32 @@ function Invoke-PrdFeatureBeforePlannerDecision {
 
     # Derive the prerequisite set from the persisted work-mode marker rather
     # than a fixed spec.md/user-story.md pair. A marker that cannot be read or
-    # recognized must fail closed to the strictest set, not fail open.
+    # recognized must fail closed, not fail open: it denies on its own branch
+    # below, naming no prerequisite set and probing for no required file.
     $issueContent = Get-PrdFeatureIssueContent -FeatureFolder $folderNormalized
     $workMode = Resolve-PrdFeatureWorkMode -IssueContent $issueContent
-    $modeDetermined = [bool]$workMode
+
+    # An indeterminate mode is its own decision path, and it deliberately does NOT
+    # run the required-file probe. When the mode is unknown no prerequisite set is
+    # knowable, so any set the gate named would be wrong for at least one mode:
+    # a set containing user-story.md is unsatisfiable for full-bug and minor-audit
+    # without violating the lifecycle contract, and the empty set fails open. The
+    # only remedy true in all three modes is repairing the marker, so that is what
+    # the reason states. This still DENIES, so the gate remains fail-closed.
+    if (-not $workMode) {
+        return [ordered]@{
+            hookSpecificOutput = [ordered]@{
+                hookEventName            = 'PreToolUse'
+                permissionDecision       = 'deny'
+                permissionDecisionReason = "PRD_FEATURE_BLOCKED: resolved feature folder '$folderNormalized', " +
+                "but its work mode could not be determined from '$folderNormalized/issue.md' " +
+                '(the ''- Work Mode:'' marker is absent, unreadable, or unrecognized). ' +
+                'Confirm that is the intended feature folder, then add or correct the ' +
+                '''- Work Mode:'' marker in that file so the prerequisite set can be derived.'
+            }
+        }
+    }
+
     # Force array wrapping: PowerShell unravels a zero-element array return down
     # the pipeline to $null, which would otherwise fail the Mandatory
     # -RequiredFile parameter on Get-PrdFeatureMissingFile for minor-audit mode.
@@ -322,13 +419,13 @@ function Invoke-PrdFeatureBeforePlannerDecision {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
+    # Lead with the resolved folder, not with the remedy: a reader who sees a
+    # folder they did not intend diagnoses a path problem immediately instead of
+    # re-running a step that has already completed correctly.
     $list = ($missing -join ', ')
-    if ($modeDetermined) {
-        $reason = "PRD_FEATURE_BLOCKED: cannot delegate to atomic-planner before prd-feature outputs are present in '$folderNormalized'. Missing: $list (work mode: $workMode). Invoke the prd-feature subagent first."
-    }
-    else {
-        $reason = "PRD_FEATURE_BLOCKED: cannot delegate to atomic-planner before prd-feature outputs are present in '$folderNormalized'. Missing: $list. Work mode could not be determined from '$folderNormalized/issue.md' (marker absent, unreadable, or unrecognized); failing closed to the strictest prerequisite set (spec.md, user-story.md). Invoke the prd-feature subagent first."
-    }
+    $reason = "PRD_FEATURE_BLOCKED: resolved feature folder '$folderNormalized' is missing: " +
+    "$list (work mode: $workMode). Confirm that is the intended feature folder, then " +
+    'invoke the prd-feature subagent to produce the missing output(s).'
 
     return [ordered]@{
         hookSpecificOutput = [ordered]@{

package/resources/claude-customizations/.claude/rules/benchmark-baselines.md

@@ -1,3 +1,10 @@
+---
+paths:
+  - "scripts/benchmarks/**"
+  - "**/baseline*.json"
+description: Runner-environment parity and provenance rules for committed benchmark baselines.
+---
+
 # Benchmark Baseline Provenance
 
 This rule governs performance baselines used by benchmark regression gates. It exists because a baseline captured on a developer workstation was compared against a `windows-latest` runner, producing deterministic latency regressions that the benchmark gate could not survive (issue #26, PR #30).

package/resources/claude-customizations/.claude/rules/ci-workflows.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - ".github/workflows/**"
+description: Exit-code rules for GitHub Actions workflow steps that run pwsh.
+---
+
 # CI Workflow Authoring
 
 This rule governs GitHub Actions workflow steps that run PowerShell (`pwsh`). It exists because a `pwsh` step that intentionally invoked a failing nested command left `$LASTEXITCODE == 1` after its verification logic had already succeeded, leaking a failure to GitHub Actions even though the step's intent was satisfied (issue #26, PR #30).

package/resources/claude-customizations/.claude/rules/orchestrator-state.md

@@ -1,3 +1,27 @@
+---
+paths:
+  - "artifacts/orchestration/*orchestrator-state.json"
+  - "artifacts/orchestration/*planner-state.json"
+  - "scripts/dev_tools/*orchestrator_state*"
+  - "extensions/drm-copilot/src/lib/validate/orchestrator-state-*"
+  - "scripts/dev_tools/compute_complexity_floor.py"
+  - "scripts/dev_tools/resolve_delegation_model.py"
+  - ".claude/hooks/validate-orchestrator-output.ps1"
+  - ".claude/hooks/enforce-model-routing-receipt.ps1"
+  - "config/orchestration-routing.json"
+  - ".claude/agents/orchestrator.md"
+  - ".claude/agents/epic-orchestrator.md"
+  - ".claude/agents/parallel-orchestrator.md"
+  - ".claude/agents/epic-planner.md"
+  - ".claude/agents/parallel-planner.md"
+  - ".claude/skills/orchestrate/SKILL.md"
+  - ".claude/skills/epic-orchestrate/SKILL.md"
+  - ".claude/skills/parallel-orchestrate/SKILL.md"
+  - ".claude/skills/epic-plan/SKILL.md"
+  - ".claude/skills/parallel-plan/SKILL.md"
+description: Checkpoint invariants for the orchestration state artifact and the surfaces that write or validate it.
+---
+
 # Orchestrator-State Remediation-Cycle and Human-Interaction Invariants
 
 This rule governs remediation-cycle records and the optional `human_interaction` block in the orchestrator-state checkpoint at `artifacts/orchestration/orchestrator-state.json`. It documents three invariants that must hold for each remediation cycle, plus three invariants for the `human_interaction` block, so that resume and review workflows do not depend on a structurally invalid checkpoint.

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

@@ -1,3 +1,24 @@
+---
+paths:
+  - "artifacts/orchestration/parallel-*"
+  - "docs/features/parallel/**"
+  - "scripts/dev_tools/*parallel*"
+  - "extensions/drm-copilot/src/lib/validate/parallel-*"
+  - "scripts/dev_tools/*blast_radius*"
+  - "config/blast-radius.json"
+  - "**/config/blast-radius.json"
+  - "extensions/drm-copilot/src/lib/push-down/claude-blast-radius-derive-core.ts"
+  - ".claude/lib/blast-radius/**"
+  - ".claude/lib/bash/parallel-yaml-scan.sh"
+  - "scripts/dev_tools/validate_orchestration_artifacts.py"
+  - "extensions/drm-copilot/src/lib/validate/orchestration-artifacts.ts"
+  - ".claude/hooks/enforce-epic-merge-gate.ps1"
+  - ".claude/agents/parallel-orchestrator.md"
+  - ".claude/agents/parallel-planner.md"
+  - ".claude/skills/parallel-*/SKILL.md"
+description: Artifact invariants and blast-radius contention doctrine for the parallel orchestration surface.
+---
+
 # Parallel Orchestration Artifact Invariants
 
 This rule governs the three artifacts of the `parallel` orchestration surface: the parallel-run manifest at `docs/features/parallel/<slug>/parallel.md`, the parallel-orchestrator checkpoint at `artifacts/orchestration/parallel-orchestrator-state.json`, and the parallel-planner checkpoint at `artifacts/orchestration/parallel-planner-state.json`. It records the invariants those artifacts must satisfy as numbered prose so that downstream features consume a fixed schema and add behavior only.

package/resources/claude-customizations/.claude/rules/plan-acceptance-gates.md

@@ -1,3 +1,15 @@
+---
+paths:
+  - "scripts/dev_tools/plan_gate_*"
+  - "scripts/dev_tools/validate_orchestration_artifacts.py"
+  - "extensions/drm-copilot/src/lib/validate/plan-gate-*"
+  - "extensions/drm-copilot/src/lib/validate/orchestration-artifacts.ts"
+  - "docs/features/**/plan.*.md"
+  - "docs/features/**/remediation-plan.*.md"
+  - ".claude/skills/atomic-plan-contract/SKILL.md"
+description: Acceptance-gate rules G1 through G6 applied to the shell commands an atomic plan states as acceptance conditions.
+---
+
 # Atomic-Plan Acceptance Gates (G1 through G6)
 
 This rule governs the acceptance-gate rules the plan validator applies to the shell commands an atomic plan states as acceptance conditions. It exists because a plan can state an acceptance condition that cannot fail: a coverage argument that collects no data, or a search for a literal that returns zero matches whatever the executor does. Such a condition reads as a verification step and gates nothing (issue #486).
@@ -24,10 +36,18 @@ Every finding string begins with the square-bracketed `P#-T#` identifier of the
 | **G4** | A `--cov` value supplied space-separated (`--cov <value>`) rather than with `=`. The ambiguous form can bind the following positional argument. Independent of resolvability, so it is reported for every value. | **Warning** |
 | **G5** | A checkable search literal that is absent from the tracked tree **and** not quoted in the plan document outside the command span it was read from. | **Warning** (see below) |
 | **G6** | A checkable search literal absent from every single line of a tracked file but present in that file's sliding-window join of adjacent lines. A line-oriented search returns zero matches. | **Warning** |
+| **G7** | A write-mode command — one matching a write-mode register entry, that is a tool that rewrites tracked source and exits 0 after rewriting — whose attributed task text carries none of that entry's observation markers. The exit code alone cannot distinguish a clean run from a repairing one, so the acceptance condition holds either way. | **Warning** |
+| **G8** | A `git diff` invocation carrying no non-flag ref operand and neither `--cached` nor `--staged`. It compares the worktree against the index, which is ambient state: the comparison passes vacuously once the change is committed. Exonerated when the attributed task text carries a second `git diff` or a `git status` span. | **Warning** |
+| **G8b** | A `git diff` invocation carrying a non-flag ref operand together with `--name-only` or `--name-status`, whose attributed task text carries neither a `git add` span nor a `git status --porcelain` span. A name-listing diff enumerates tracked changes only, so a path the plan creates is invisible to it. | **Warning** |
+| **G9** | A command carrying a `--cov` token, carrying no token beginning `--cov-report=term` and no token beginning `--cov-fail-under`, whose project `addopts` value also carries no `--cov-report=term`. No coverage table is printed, so a coverage number the acceptance condition demands can never be read. | **Warning** |
+
+G1 through G9 are the complete shipped set. G1 through G6 were added by issue #486 and G7 through G9 by issue #519; the parenthetical in this file's title names the original set only.
 
 G1 through G4 form a cascade over each `--cov` value: the value is decided once, so a value G1 rejects is never additionally reported by G2 or G3. G4 is evaluated independently of the cascade because the ambiguous form is a defect whatever the value resolves to. G6 is evaluated before G5, because cross-line presence falsifies G5's tree-absence claim.
 
-G1 and G4 are context-free and run on every invocation. G2, G3, G5, and G6 require a repository seam; with no context supplied they do not run, and the Blocking list is byte-identical to the pre-change output for the same text.
+G8b is a distinct rule from G8 and not a sub-case of it: G8 reports a diff with no ref operand, G8b reports one that has a ref operand but cannot observe an untracked path. A single invocation can satisfy only one of the two, because the presence of a ref operand decides between them.
+
+G1 and G4 are context-free and run on every invocation. G2, G3, G5, and G6 require a repository seam; with no context supplied they do not run, and the Blocking list is byte-identical to the pre-change output for the same text. G7, G8, and G8b are likewise context-free and run on every invocation. G9 requires the repository seam, because it reads the project `addopts` value through it, so with no context supplied G9 does not run. All four of the rules added by issue #519 ship in the Warning channel, so none of them can alter the Blocking list at all.
 
 ### Attribution window
 
@@ -43,7 +63,7 @@ A repository seam that raises, or that reports a non-zero exit, causes G2, G3, G
 
 The shipped G5 severity was not chosen by argument. It was fixed by a pre-declared rule applied to a measurement over the committed plan corpus: Blocking if and only if the total G5 finding count is greater than zero **and** the recorded false-positive count is zero; otherwise Warning.
 
-The measurement is recorded in `docs/features/active/2026-08-17-reject-unfalsifiable-acceptance-gates-in-atomic-plans-486/evidence/qa-gates/g5-corpus-measurement.2026-08-20T12-02.md`. It scanned 166 plan files, evaluated 100 candidate literals, and produced a total G5 finding count of 0. A zero false-positive count over zero findings measures nothing, so the first conjunct failed and **G5 ships as a Warning**.
+The measurement is recorded in `docs/features/completed/2026-08-17-reject-unfalsifiable-acceptance-gates-in-atomic-plans-486/evidence/qa-gates/g5-corpus-measurement.2026-08-20T12-02.md`. That feature has since been completed and its folder moved out of the active tree, so the citation names the completed tree; the path this file previously carried, under `docs/features/active/`, no longer resolves. It scanned 166 plan files, evaluated 100 candidate literals, and produced a total G5 finding count of 0. A zero false-positive count over zero findings measures nothing, so the first conjunct failed and **G5 ships as a Warning**.
 
 The zero count is a property of the corpus, not a defect in the measurement. Every committed plan is a tracked file, so a fixed-string search for a literal quoted inside a committed plan always finds at least that plan itself, and the tree-absence condition holds for no committed candidate. The measurement artifact records the four checks that established this (non-vacuous enumeration, a working repository seam, a self-hit on every sampled lookup, and predicate-order equivalence with the shipped rule).
 
@@ -63,6 +83,127 @@ Rejecting such a plan would block a correct plan on evidence about a state the p
 
 The window size is fixed at four adjacent non-blank lines. Blank lines are removed before windowing, and one window is emitted per start position, so the boundary is exact: two lines further apart than the window size never appear in the same join. The size is recorded here rather than left implicit so that a later feature can revise it against measured wrap-depth data instead of re-deriving it.
 
+### The shared measurement behind G7, G8, G8b, and G9
+
+The four severities below were fixed by one corpus measurement recorded in `docs/features/active/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`. The pre-declared decision rule was written and committed **before** the driver existed and before any count was taken, so the ordering is verifiable from git history rather than only asserted in prose. Its form matches the G5 precedent: the shipped severity is Blocking if and only if the total finding count for that rule is greater than zero **and** the recorded false-positive count for that rule is zero; otherwise Warning.
+
+The false-positive definition the rule consumes is likewise pre-declared: a finding is a false positive when the acceptance condition it reports is in fact falsifiable — when the plan states an observation sufficient to distinguish a passing run from a failing one, by a mechanism the rule's predicate does not recognise. A finding is a true positive when the acceptance condition it reports genuinely cannot fail, or can only be satisfied vacuously.
+
+The measurement scanned 194 plan files under `docs/features`, covering the `active`, `completed`, and `archive` trees. Unlike the G5 measurement, every rule here found findings, so each false-positive count is a count over an examined population rather than over an empty one. The vacuity declaration therefore applies to no rule of this set.
+
+| Rule | Corpus files | Candidates | Findings | True positives | False positives | Decision | Shipped |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| G7 | 194 | 519 | 466 | 444 | 22 | second conjunct fails | **Warning** |
+| G8 | 194 | 237 | 82 | 75 | 7 | second conjunct fails | **Warning** |
+| G8b | 194 | 47 | 19 | 19 | 0 | pre-declared unconditional clause | **Warning** |
+| G9 | 194 | 273 | 8 | 4 | 4 | second conjunct fails | **Warning** |
+
+### G7 — ships as a Warning because the measurement recorded 22 false positives
+
+G7's finding count of 466 satisfies the first conjunct, so the rule was not decided by a vacuous measurement. It fails the second conjunct: 22 of the 466 findings are false positives, in two classes named in full in the measurement artifact.
+
+**Class 1, two findings — read-only argv shape.** The `prettier-write` register entry matches the argv shape `npm run format` and declares no exclusion for a check flag, so a check-mode invocation written as `npm run format -- --check` is matched as if it wrote. That command does not write and exits non-zero on drift, so its acceptance condition is falsifiable by the exit code alone.
+
+**Class 2, twenty findings — the task observes the tree rather than the tool's stdout.** The attributed task text carries a `git status --porcelain` or `git status` span, so the plan distinguishes a clean run from a repairing one by comparing the tree before and after. G7's marker set recognises tool-output observation only, so it does not see this mechanism. Class 2 is the larger of the two and is the reason the rule cannot ship Blocking on this measurement: a plan that observes the tree has stated a real acceptance condition, and rejecting it would block a correct plan.
+
+Both classes are addressable by a later feature — Class 1 by adding a check-flag exclusion to the `prettier-write` entry, Class 2 by admitting a tree-observation span as an alternative to a marker — but neither was changed here, because narrowing a predicate after reading its measurement would invalidate the measurement that decided its severity. A later feature that narrows either class must re-take the measurement the same way.
+
+Counts, and every one of the 22 false positives named by plan path, task identifier, and offending span: `docs/features/active/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`.
+
+### G8 — ships as a Warning because the measurement recorded 7 false positives
+
+G8's finding count of 82 satisfies the first conjunct. It fails the second: 7 findings are false positives, in two classes.
+
+**Class 1, six findings — `--no-index`.** `git diff --no-index` compares two named paths on disk. It does not compare the worktree against the index, so G8's stated claim that the comparison passes vacuously once the change is committed is false for this form.
+
+**Class 2, one finding — the unmerged-path filter.** `--diff-filter=U` selects conflicted paths during a merge or rebase. In that state the worktree-against-index comparison is the correct one and does not become vacuous on commit, because the conflict is precisely what is not yet committed.
+
+Counts, and every one of the 7 false positives named by plan path, task identifier, and offending span: `docs/features/active/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`.
+
+### G8b — ships as a Warning unconditionally, by the pre-declared rule
+
+G8b is exempt from the two-conjunct rule and **cannot reach the Blocking channel by any measured outcome**. That exemption was declared before the counts were taken, and it holds even though G8b is the only rule of the four whose measured false-positive count is zero.
+
+The reason is that G8b carries the highest false-positive surface of the set, and a false-positive count taken over one corpus does not bound the false-positive surface of a predicate. Promoting a rule on the strength of a clean run over one corpus would convert an accident of that corpus into a gate. The 19 findings were nonetheless examined individually and all 19 were retained as true positives, across three sub-classes: a placeholder ref operand, which resolves to a real ref at run time and still cannot make the diff see an untracked path; an artifact-field label inside the span, which is cosmetic and leaves the underlying acceptance condition as the finding describes it; and a pathspec written without the `--` separator, where the predicate reads the pathspec as a ref operand. That last sub-class is a true positive for G8b and is simultaneously recorded in the measurement as a **G8 false negative**: the same span should also have been reported by G8, and was not.
+
+Counts, the zero false-positive record, and the three sub-classes with their plan paths and offending spans: `docs/features/active/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`.
+
+### G9 — ships as a Warning because the measurement recorded 4 false positives
+
+G9's finding count of 8 satisfies the first conjunct. It fails the second: 4 of the 8 findings are false positives, and all four share one cause — the offending span is not a command the plan states as an acceptance condition. Two are prose quotations of a flag or flag pair used to describe something the task declares out of scope; one is a test-data literal inside a sentence asserting a helper's return values; and one is a truncated restatement of a command whose full form on the task line does supply a terminal reporter. In every one of the four, the acceptance condition the task actually states is decided by a pass count, an exit code, or an artifact field, not by a coverage number.
+
+The remaining 4 findings are true positives, and each is the exact defect the rule was written for: the acceptance condition demands a numeric coverage percentage, the command supplies no terminal reporter, the project `addopts` supplies only an LCOV reporter, and the number the acceptance demands is therefore never printed.
+
+Counts, and every one of the 4 false positives named by plan path, task identifier, offending span, and the reason its acceptance condition is falsifiable: `docs/features/active/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`.
+
+## The Write-Mode Register
+
+G7 reads a fixed register of six entries. Each entry is an argv predicate plus a set of observation markers matched case-sensitively as substrings of the owning task's attributed text. The register is data, not code, so the same six entries are transcribed into the TypeScript twin without porting behaviour.
+
+### Membership criterion
+
+**A tool belongs in the write-mode register when it rewrites tracked source and still exits 0 after rewriting.** That conjunction is the whole criterion. The exit code of such a tool is the same on a clean run and on a repairing run, so a plan that states the invocation as an acceptance condition and records nothing but the exit code has asserted nothing the tool can fail. The register's markers name the literals the tool's success-case output prints, which is the observation that separates the two runs.
+
+The six entries are `black-write`, `ruff-fix`, `prettier-write`, `poshqc-format`, `run_poshqc_analyze_autofix`, and `poshqc-suite`. The fifth is named for the MCP tool `run_poshqc_analyze_autofix`, whose argv predicate is an argv word ending with that name.
+
+### Executable-position constraint
+
+A word satisfies an entry's argv shape only when its index lies within the leading four-word scan window and the word immediately preceding it does not begin with a hyphen. A tool name supplied as the operand of a search flag is therefore never read as an invocation, which mirrors the extractor's existing rule that a grep-family name appearing as an operand is not the executable. Without this constraint a task that searches a policy file for a register member's name would report a finding against its own search command — including a task that searches this file.
+
+### Exclusions, with the reason for each
+
+Two tools that do write are deliberately **not** register members.
+
+- **`git add` is excluded.** A plan stages in order to make a later diff complete, so its acceptance concerns the diff, not the staging. The staging itself carries no acceptance condition to make unfalsifiable, and G8b already reads a `git add` span as an exonerating companion rather than as an offence.
+- **`npm ci` is excluded.** Its only write target is git-ignored, so it rewrites no tracked source and fails the membership criterion's first half. A plan can still state a real observation of it — an installed-package count, or the existence of a resolved binary — but it is not a case G7 needs to report.
+
+### Two writers that are not register members and are not exclusions
+
+Two further tools write files without being register members, and they are recorded here so a later maintainer does not read their absence as an oversight.
+
+- **The Python test runner** writes coverage output under the artifacts tree, for example the LCOV file the project `addopts` value names. It rewrites no tracked source, and its exit code already distinguishes a passing run from a failing one, so it fails the membership criterion on both halves.
+- **The PoshQC test tool** likewise writes result and coverage files under the artifacts tree without rewriting tracked source, and likewise reports pass and fail through its own result. The three PoshQC entries that *are* members — format, analyze-autofix, and the suite — are members because they rewrite tracked PowerShell source in place.
+
+A tool that writes only under the artifacts tree is therefore outside the register by construction. The register is about tracked source, not about writing in general.
+
+### Known false-negative class — the single-token tool-name span
+
+The command extractor drops any command span shorter than two shell words. That two-word minimum-argv floor predates these rules, is pinned by an existing test, and was deliberately left unchanged: relaxing it would newly admit a single-word coverage-argument span into the G1 and G4 scan, which would change existing output, and changing existing output is exactly what this addition forbids itself.
+
+The consequence is a false-negative class. **A tool invoked as a bare single-token name is never extracted, so G7 can never report it, however unobservable its acceptance condition is.** This is the form plans commonly use for MCP tools, including the PoshQC formatter, the PoshQC analyzer autofix tool, and the PoshQC composite suite tool — three of the six register entries. Those three entries are reachable only by a span whose first word is the tool name and whose second word is an operand, for example the tool name followed by a path.
+
+This is a stated limitation, not a promise deferred, and it is recorded here for the same reason the placeholder guard's false-negative class is recorded above: it is the cost side of a trade, and a later feature must weigh it rather than rediscover it. The limitation is pinned by a test asserting that a single-token tool-name span produces zero findings from every one of the four rules, so the boundary cannot move silently.
+
+A later feature may revisit the floor, but only together with a plan for the coverage-rule output change that relaxing it would cause. The two cannot be separated: the floor is one value read by one extractor feeding every rule, so any relaxation reaches G1 and G4 as well as G7.
+
+## Deliberately Uncovered Sub-Classes
+
+Issue #519 measured five classes of unfalsifiable acceptance condition on a single plan. G7 and G9 cover two decidable slices of the first, G8 and G8b cover the third. The remainder is recorded here so a reviewer knows what these rules do **not** reach and that human attention is still required for it.
+
+### The general unobservable-success-output class, beyond what G7 and G9 reach
+
+The class is: an acceptance condition that asserts over output the command does not emit on a successful run. G9 covers the slice where a coverage command prints no table at all, and G7 covers the slice where a write-mode tool's exit code is identical on a clean and a repairing run. Neither reaches the general case.
+
+Three measured instances outside their reach illustrate why. A gate requiring a formatter's `reformatted` line to be recorded verbatim is unsatisfiable on a clean run, because that line is printed only when a file was rewritten. A gate demanding a zero-diagnostic count from an analyzer that returns only an ok flag and a one-sentence summary names a value that has no source. A gate demanding separate line and branch percentages from a coverage run that prints one combined `Cover` column reads two numbers that are never printed.
+
+**Deciding these requires knowing each tool's success-case output, which is not derivable from the plan text, the rules, or the tool documentation.** That is what makes the class invisible to review: four careful review cycles on the measured plan missed it entirely, and it surfaced only when the reviewer ran the tools and observed what they actually printed. A rule would need a per-tool output model, which is a different mechanism from a register of argv predicates. The class is therefore addressed by an authoring requirement in `.claude/skills/atomic-plan-contract/SKILL.md` — that a plan author observe a command's success-case output before asserting over that output — and not by a rule.
+
+### The task-ordering class
+
+The class is: an acceptance condition that is unsatisfiable because of where its task sits in the plan rather than because of what the command does. A gate that runs a test path containing deliberately-failing cases added by an earlier task, before the later task that makes them pass, cannot exit 0. A baseline captured *after* a write-mode formatter has already repaired pre-existing drift becomes either a blanket waiver or makes the later gate unsatisfiable.
+
+**No rule covers this class.** Detecting it requires intra-plan dependency reasoning across phases: the validator would have to model which task changes which file, and which later assertion depends on that change. That is a different analysis from the per-command predicates these rules apply. It is recorded here so a reviewer knows the class still needs human attention.
+
+### The executor-choice heuristic — rejected, and closed rather than deferred
+
+The proposal was a rule that flags selection vocabulary in acceptance text — "any", "a suitable", "the known", "choose" — on the reasoning that an executor free to pick the evidence it is judged against cannot fail. The underlying concern is real and was measured: two conditions on the examined plan asked the executor to identify "the known-genuine pair" and to choose a survivor list.
+
+**The rule is rejected.** The vocabulary it would scan for is ordinary plan prose used in roles that carry no selection semantics, and the research recorded a corpus instance in which the word "any" appears inside a *prohibition* rather than a selection — a case the scan would report and the author would be right to ignore. A keyword scan over prose is not statically decidable for the property the rule would claim to detect. This file's own guidance is to weigh a new rule on its authoring-time false-positive rate rather than on how many committed plans it would have flagged, and on that test the proposal fails.
+
+The concern is addressed as authoring guidance in `.claude/skills/atomic-plan-contract/SKILL.md` instead, where a false positive costs an author a moment's judgment rather than a blocked plan.
+
+**This is closed, not deferred.** Reviving it requires new evidence about its false-positive rate on plan prose, not a restatement of the original proposal.
+
 ## Checkable-Literal Definition and the Placeholder Guard
 
 G5 and G6 apply only to a *checkable* literal. The specification defines a checkable literal by two conditions: the command carries the fixed-string flag `-F`, or the pattern contains none of the regular-expression metacharacters `. * [ ] ^ $ \ ( ) { } | + ?`. That condition is conservative in POSIX BRE, POSIX ERE, PCRE, and the Rust regex dialect simultaneously, so no dialect-selection logic is required.

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

@@ -159,6 +159,8 @@ Before a plan can be treated as approved:
 
 The same validator call also applies the acceptance-gate rules G1 through G6 defined in `.claude/rules/plan-acceptance-gates.md`. Those rules report acceptance conditions that cannot fail — a coverage argument that collects no data, or a search for a literal that returns zero matches whatever the executor does. They run automatically on the existing `plan` route with no additional flag. Blocking findings appear in the validator's error output and fail the gate; Warnings are surfaced without failing it, prefixed with `PLAN GATE WARNING: ` on the CLI and carried on the optional `warnings` field of the MCP result. Read that rule file before authoring acceptance conditions.
 
+The same call additionally applies the rules G7, G8, G8b, and G9, which report a write-mode command observed only by its exit code, an unanchored `git diff`, a name-listing diff with no companion span, and a coverage command that prints no table. All four ship in the Warning channel, so they surface without failing the gate. The complete shipped set is therefore G1 through G9.
+
 ## Wrap-Tolerant Assertion Authoring (Mandatory)
 
 An acceptance condition must be able to fail. A condition whose command returns the same result whatever the executor does verifies nothing, however precise it reads. Author every acceptance condition in a wrap-tolerant form: one that survives line wrapping and shell quoting in the file it asserts against.
@@ -171,6 +173,13 @@ Rules:
 - **Dotted coverage-argument form.** Coverage assertions must name an importable dotted module, for example `--cov=scripts.dev_tools.plan_gate_discrimination`. The filesystem-path spellings `--cov=scripts/dev_tools/module.py` and `--cov=scripts/dev_tools/module` collect no data, so a coverage threshold asserted against them cannot fail. Rules G1 through G3 report those spellings.
 - **Use the `=` form, not the space-separated form.** `--cov <value>` can bind the following positional argument. Rule G4 reports it.
 - **Quote what the task will create.** When an asserted literal does not yet exist in the tree, quote the exact literal in the plan prose outside the command span. The gate reads that quotation as the executor's instruction and exonerates the assertion; a paraphrase does not.
+- **Record an observation beyond the exit code for a write-mode command.** A formatter or a fixing linter rewrites tracked source and still exits 0 after rewriting, so its exit code is identical on a clean run and on a repairing one. State, in the task text, the literal its success-case output prints — for example the summary line a formatter prints when it changed nothing — or state a before-and-after tree observation. Rule G7 in `.claude/rules/plan-acceptance-gates.md` reports a write-mode command whose task text carries neither.
+- **Anchor every `git diff` to a ref.** A `git diff` with no ref operand and no `--cached` compares the worktree against the index, which is ambient state: it passes vacuously once the change is committed, so the assertion cannot fail for the executor who commits before running it. Supply an explicit ref operand, usually the base branch. Rule G8 reports the unanchored form.
+- **Pair a name-listing diff with a staging or porcelain-status companion.** An anchored `git diff --name-only` or `--name-status` enumerates tracked changes only, so it can never report a file the task creates, and an assertion that it lists newly created files always sees an empty list. Add a `git add` span or a `git status --porcelain` span in the same task. Rule G8b reports a name-listing diff with neither companion. The two mechanisms are complementary and each alone is wrong in one state: the anchored diff is blind to untracked files, and porcelain status goes empty once the change is committed.
+- **Pass a terminal reporter to every coverage command.** The project `addopts` value supplies an LCOV reporter only, so a coverage command that does not pass `--cov-report=term-missing` prints no coverage table at all, and a numeric percentage the acceptance condition demands can never be read from it. Rule G9 reports a coverage command that supplies no terminal reporter and no `--cov-fail-under` threshold.
+- **Observe a command's success-case output before asserting over that output (mandatory).** Run the command, or read a recorded run of it, and confirm the value you intend to assert is actually printed on a *successful* run. Do not infer it from the tool's documentation, from the plan, or from what the tool prints on failure. This requirement exists because the class of defect it prevents is not detectable by reading: an assertion on a line the tool prints only when it changed something is unsatisfiable on a clean run; a demand for a zero-diagnostic count from a tool that returns only an ok flag names a value with no source; a demand for separate line and branch percentages from a coverage run that prints one combined column reads two numbers that are never printed. G7 and G9 cover two decidable slices of this class. The remainder is covered by this requirement and by nothing else, so a reviewer cannot rely on the gate to catch it.
+- **Fix the evidence in the plan; never leave the executor to select it.** An executor free to choose the evidence it is judged against cannot fail. Do not write an acceptance condition that asks the executor to identify "the known-genuine pair", to choose a survivor list, or to pick any suitable instance. Name the instances, or state the mechanical derivation that produces them, so a third party re-running it obtains the same set. This is authoring guidance and not a rule: a validator rule that scanned acceptance text for selection vocabulary was proposed and rejected, because that vocabulary is ordinary plan prose used in roles carrying no selection semantics and a keyword scan over prose is not statically decidable for the property it would claim to detect. The judgment is the author's, and it is not automated. `.claude/rules/plan-acceptance-gates.md` records the rejection and the reason for it.
+- **Check that the task-ordering does not make the condition unsatisfiable.** No rule covers this. A gate that runs a test path containing deliberately-failing cases added by an earlier task, before the later task that makes them pass, cannot exit 0. A baseline captured after a write-mode formatter has already repaired pre-existing drift becomes either a blanket waiver or makes a later gate unsatisfiable. Read each acceptance condition against the state the plan will actually be in when its task runs.
 
 ## Plan-Path Continuity Contract (Mandatory)
 

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

@@ -19,14 +19,6 @@ checkpoint handling, wave computation, integration-branch lifecycle, wave barrie
 merge-conflict handling, worktree cleanup, and documentation-maintenance procedures so the
 procedure is not re-derived ad hoc on each epic run.
 
-## Prerequisites
-
-Before proceeding, `epic-orchestrator` must:
-
-1. Read `CLAUDE.md` for repository tone policy and architectural context.
-2. Read applicable `.claude/rules/` files for the languages in scope.
-3. Read the policy files listed in the compliance reading order section of `CLAUDE.md`.
-
 ## Epic Dependency Manifest
 
 The epic manifest is the YAML frontmatter of the single epic home
@@ -123,7 +115,7 @@ function of the DAG.
 When `epic-orchestrator` delegates a child feature to `Agent(orchestrator)`, the prompt includes
 the literal epic-mode kickoff line:
 
-> `Epic mode: true. epic_feature_folder: <epic-slug>. integration_branch: epic/<epic-slug>-integration. epic_checkpoint_path: artifacts/orchestration/epic-orchestrator-state.json. PR base branch MUST be <integration_branch>, not main; pass --base <integration_branch> to gh pr create.`
+> `Epic mode: true. epic_feature_folder: <epic-slug>. integration_branch: epic/<epic-slug>-integration. epic_checkpoint_path: artifacts/orchestration/epic-orchestrator-state.json. PR base branch MUST be <integration_branch>, not main; pass --base <integration_branch> to gh pr create. Your final report MUST be exactly the bounded return shape (issue_num, feature_folder, merge_status, pr_number, merge_commit_sha, blocked_reason, branch_name, worktree_path) and nothing else; any additional narrative is discarded because the parent re-derives authoritative state regardless.`
 
 The child's own `orchestrator`, on reading this line, records `epic_mode: true` and
 `epic_context: { epic_feature_folder, integration_branch, epic_checkpoint_path }` at its first
@@ -131,6 +123,31 @@ checkpoint write, and on CI-green (S9 step 6) merges its own PR into the integra
 recording `epic_merge: { merge_commit_sha, target_branch, merged_at }`. Standalone (non-epic)
 orchestration is unchanged: `epic_mode` absent or `false` makes S9 step 6 a no-op.
 
+## Bounded Child Return Contract
+
+A child `orchestrator`'s final report is consumed as a fixed eight-field shape and nothing else:
+
+- `issue_num` — the child's GitHub issue number.
+- `feature_folder` — the child's feature-folder path.
+- `merge_status` — the child's terminal merge-status enum value.
+- `pr_number` — the child's pull-request number, or null when none was opened.
+- `merge_commit_sha` — the merge commit, or null when the child did not merge.
+- `blocked_reason` — a short reason string when the child is blocked, otherwise null.
+- `branch_name` — the child's feature branch.
+- `worktree_path` — the child's isolated worktree path.
+
+Content beyond these eight fields is **discarded**. A child that returns a longer narrative is not
+in error; the excess is simply not read into the parent's context, which is what keeps the parent's
+footprint flat as the child count grows.
+
+Discarding is safe because the parent re-derives authoritative state regardless, from
+`git worktree list --porcelain`, `git branch`, and
+`gh pr view --json state,mergedAt,headRefOid`. `branch_name` and `worktree_path` are carried in the
+shape only to spare the parent a re-parse of porcelain output per child before
+`git worktree remove`; they are not authoritative and are re-derived like every other field. The
+governing argument is the cache doctrine already recorded in
+`.claude/rules/parallel-orchestration.md`, which is cited here rather than restated.
+
 ## Model Selection
 
 When `epic-orchestrator` delegates a child feature to `Agent(orchestrator)`, the prompt appends the
@@ -265,7 +282,7 @@ checkpoint JSON remains the durable, machine-authoritative source.
 `docs/features/epics/<epic-slug>/epic.md`), `epic_status_doc_path`, `integration_branch`,
 `completed_steps`, `next_step`, `last_updated`, `current_wave`, `waves[]`, `features[]`,
 `epic_merge_pr`, and the three receipt arrays (`delegation_receipts[]`, `skill_receipts[]`,
-`mcp_call_receipts[]`) — the full schema is defined in `spec.md` §6 of this feature. The
+`mcp_call_receipts[]`). The
 `merge_status` enum is: `not_started`, `worktree_created`, `pr_open`, `ci_green`,
 `merge_conflict`, `blocked_conflict_loop_limit`, `merged`, `worktree_removed`. The optional
 `intent` object (projection of the `epic.md` intent block) is validated presence-gated.

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

@@ -96,6 +96,16 @@ A delegation prompt carrying the literal marker `Preparation mode: true` (issued
 - **Terminal checkpoint.** Stop with `completed_steps` containing `S3_promotion` and `S4_atomic_planning`, `next_step: "S5_atomic_execution"`, out-of-scope step statuses set to `not-applicable`, and `blocked_reason: "none"`. Do NOT assert completion (`next_step: "complete"`, `S12_complete`, or a `completed` step8/9/10 status): the run has no PR or CI evidence, and the route's `requires_ci_gate: false` exempts it from `ci_gate` at the completion validator instead.
 - **Commit.** Commit the prepared feature folder and plan to the current branch (the worktree branch created off the epic integration branch) before stopping, and report the `plan-path` and preflight status in the final output.
 
+## Epic Mode Bounded Return
+
+Under `Epic mode: true`, your final report must be exactly this eight-field shape and nothing else:
+`issue_num`, `feature_folder`, `merge_status`, `pr_number`, `merge_commit_sha`, `blocked_reason`,
+`branch_name`, `worktree_path`.
+
+Content beyond those fields is discarded unread, so spend no effort on it. The parent
+`epic-orchestrator` re-derives authoritative state from git and `gh` regardless, per
+`## Bounded Child Return Contract` in `.claude/skills/epic-orchestrate/SKILL.md`.
+
 ## Model Selection
 
 Model selection is a second axis, strictly separate from `route`. `route` (`small | large | remediation | preparation | epic`) is deterministic — file-count driven for `small`/`large`, marker-driven for `preparation` (the `Preparation mode: true` kickoff line) and `epic`; it governs `required_agents`, `required_skills`, and `required_mcp_tools` only. `route` is NOT an input to model selection anywhere. The sole feature-level input to the delegation model tier is a judgment-based `complexity_band` (`C1 | C2 | C3 | C4`). The authoritative values live in the `model_policy` block of `config/orchestration-routing.json`.