@opengsd/gsd-path 1.4.0 → 1.5.0

package/skills/gsd-path/scripts/worktree_paths.py

@@ -22,6 +22,27 @@ else:
         from scripts import _common
 
 
+def _worktree_list_porcelain(primary: Path) -> tuple[str, bool]:
+    try:
+        if __package__:
+            from . import pipeline_git as pg
+        else:
+            from scripts import pipeline_git as pg
+    except ImportError:
+        try:
+            import pipeline_git as pg
+        except ImportError:
+            pg = None
+    if pg is not None:
+        return pg.worktree_list_porcelain(primary)
+    try:
+        output = _git(primary, "worktree", "list", "--porcelain", "-z")
+        return output, True
+    except ValueError:
+        output = _git(primary, "worktree", "list", "--porcelain")
+        return output, False
+
+
 def _git(primary: Path, *args: str) -> str:
     result = _common.run_git(primary, *args)
     if result.returncode:
@@ -82,6 +103,33 @@ def _workspace(primary: Path, pin: bool) -> Path:
     return workspace
 
 
+def release_workspace(primary: Path) -> bool:
+    """Forget the pinned placement receipt once no linked worktrees remain.
+
+    Lets GSD_PATH_WORKTREE_ROOT (or a new default) apply again at the next
+    milestone's first allocation. Returns True when a receipt was removed;
+    any remaining linked worktree (including one only still registered) keeps
+    the pin.
+    """
+    primary = primary.resolve()
+    common = Path(_git(primary, "rev-parse", "--git-common-dir"))
+    common = (primary / common).resolve()
+    receipt = common / "gsd-path" / "workspaces" / f"{_identity(primary)}.json"
+    if not receipt.is_file():
+        return False
+    output, nul_separated = _worktree_list_porcelain(primary)
+    records = output.split("\0\0") if nul_separated else [
+        block for block in output.strip().split("\n\n") if block.strip()
+    ]
+    for record in records:
+        fields = record.split("\0") if nul_separated else record.splitlines()
+        for field in fields:
+            if field.startswith("worktree ") and Path(field[len("worktree "):]).resolve() != primary:
+                return False
+    receipt.unlink()
+    return True
+
+
 def worktree_path(primary: Path, kind: str, name: str, *, pin: bool = False) -> Path:
     primary = primary.resolve()
     if kind not in {"task", "verify", "integrate", "bound"} or not name or Path(name).name != name or name in {".", ".."}:
@@ -91,9 +139,13 @@ def worktree_path(primary: Path, kind: str, name: str, *, pin: bool = False) ->
     legacy = (primary.parent / f".{primary.name}-gsd-path-integrate-{name}"
               if kind == "integrate" else primary.parent / f"{primary.name}.gsd-path" / kind / name)
     branch = f"refs/heads/gsd-path-{kind}/{name}"
-    records = _git(primary, "worktree", "list", "--porcelain", "-z").split("\0\0")
+    output, nul_separated = _worktree_list_porcelain(primary)
+    if nul_separated:
+        records = output.split("\0\0")
+    else:
+        records = [block for block in output.strip().split("\n\n") if block.strip()]
     for record in records:
-        fields = record.split("\0")
+        fields = record.split("\0") if nul_separated else record.splitlines()
         # Compare as paths: git prints forward slashes on Windows.
         worktrees = [Path(field[len("worktree "):]) for field in fields if field.startswith("worktree ")]
         if legacy in worktrees and f"branch {branch}" in fields:

package/skills/gsd-path/templates/docs-audit.md

@@ -62,7 +62,11 @@ Worst drift: <one sentence — the most misleading claim found>
 ## Remediation queue
 
 <!-- Every non-verified claim, classified. The user rules on this queue;
-     the auditor never fixes anything. -->
+     the auditor never fixes anything.
+     Numbers are unique and strictly increasing, not necessarily contiguous.
+     A persisting row keeps its number; a new row takes a number above every
+     prior queue number and every User rulings Queue #. Never reuse a retired
+     number: a ruling stays bound to the item it was made for. -->
 
 | # | Doc | Claim | Verdict | Class | Suggested action |
 |---|-----|-------|---------|-------|------------------|

package/skills/gsd-path/templates/final-review.md

@@ -13,11 +13,20 @@ Reviewed HEAD: <full SHA>
 Overall verdict: <pass | blocked>
 
 <!-- pass only when every criterion is met; blocked when any criterion is
-     not-met or unverifiable. -->
+     not-met or unverifiable.
+     A criterion with a held-out edge (E#) or judgment prohibition (N#) in
+     INTENT.md is met only when Check, Observed, or Reference cites every such
+     id with its evidence; otherwise it is unverifiable with
+     `Finding: insufficient spec evidence: <id> ...`. -->
 
 ## Success criteria
 
-### SC1 — <criterion copied verbatim from INTENT.md>
+<!-- Each `### SCn —` title must match INTENT.md `## Success criteria` as
+     `_success_criteria` stores it: continuation lines join with a single
+     space and keep `- ` sub-bullet markers; comparison uses `_normalize_ws`
+     only. -->
+
+### SC1 — <criterion as stored by the gate>
 
 - **Verdict**: <met | not-met | unverifiable>
 - **Surface**: <exactly the surface name PLAN.md's Surface contract lists this criterion under, with no detail after it; omit the whole field for any other criterion>

package/skills/gsd-path/templates/intent.md

@@ -57,6 +57,36 @@ paragraph the user signed off on — do not edit without a new sign-off.>
 1. <criterion — a thing you can run/measure/see>
 2. ...
 
+## Edge coverage
+
+<!-- Written by define's edge probe (references/spec-probes.md). Walk every
+     success criterion; each applicable edge gets one row ruled by the user.
+     Disposition: criterion SCn (stated in that criterion) | held-out (a named
+     test pins the ruling written in Detail) | dismissed (Detail says why the
+     edge cannot occur). Every SCn appears at least once; a criterion with no
+     data shape gets category none, dismissed. Categories: boundary,
+     adjacency, empty, encoding, ordering, precision, idempotency,
+     concurrency, none. `check_handoffs.py intent` gates this table. -->
+
+| Edge | Criterion | Category | Disposition | Detail |
+|------|-----------|----------|-------------|--------|
+| E1 | SC1 | <category> | <disposition> | <ruling, examples, or dismissal reason> |
+
+## Prohibitions
+
+<!-- Written by define's prohibition probe. What each criterion must never
+     silently become: values, safety, privacy, fairness, transparency. Not
+     routine engineering, not generic security canon.
+     Disposition: criterion SCn (checkable; stated in that criterion) |
+     judgment (final reviewer judges it; Detail says what to look for) |
+     dismissed. A single row with Criterion `all`, Must not `none`, and
+     disposition dismissed, and no other row, records work that affects no
+     person directly. -->
+
+| Prohibition | Criterion | Must not | Disposition | Detail |
+|-------------|-----------|----------|-------------|--------|
+| N1 | SC1 | <what it must never become> | <disposition> | <what the reviewer looks for, or why dismissed> |
+
 ## Scope: in
 
 <The smallest version that hits the success criteria. Bullet list.>

package/skills/gsd-path/templates/patch-findings.md

@@ -11,6 +11,6 @@ State: ship/blocked
 ### P001 — <short finding title>
 
 - **Source**: `.project/review/FINAL.md`
-- **Locator**: `<SC number or gap risk row>`
-- **Evidence**: <observed result copied from the source review>
-- **Fix direction**: <concrete direction for the patch task>
+- **Locator**: <copy the full `Risk: ...` line from a gap review, or the `SC<n>` id from `FINAL.md`>
+- **Evidence**: <copy the gap review's `Found` or `FINAL.md`'s `Finding` field verbatim>
+- **Fix direction**: <copy the source's `Fix direction` field verbatim>

package/skills/gsd-path/templates/plan.md

@@ -47,8 +47,8 @@ Goal: <the end-to-end slice that runs>
 Review depth: <full | deep | verify-only>
 
 <!-- More waves: features by dependency, then polish. Rules:
-     - deps only in earlier waves, or same wave with no file overlap
-     - no two same-wave tasks share files
+     - deps only in earlier waves or the same wave
+     - same-wave tasks share files only when one transitively depends on the other
      - nothing from INTENT.md scope-out appears anywhere -->
 
 ## Surface contract
@@ -83,6 +83,21 @@ Walkthrough:
 |-----------|------|------------|
 | SC1 | T001 | AC1 |
 
+## Held-out checks
+
+<!-- Required when INTENT.md Edge coverage has a held-out edge; omit the
+     section entirely when it has none. One row per held-out edge, given to
+     the task that owns the edge's criterion. Test is a file listed in that
+     task's files (optionally `path::test_name`); the task's Verify runs it
+     and its Acceptance
+     criteria state the edge id and the ruling from INTENT.md Detail. Final
+     review cites this test's recorded result for the edge.
+     `scripts/check_handoffs.py plan` gates this table. -->
+
+| Edge | Task | Test |
+|------|------|------|
+| E1 | T001 | <test path from T001 files> |
+
 ## Dependency notes
 
 <Per non-obvious edge: the exact data or landed effect that makes X precede Y,

package/skills/gsd-path/templates/research-handoff.md

@@ -14,12 +14,23 @@ Intent: `.project/intent/INTENT.md`
 <!-- Include every standard dimension exactly once. A custom dimension may
      supplement these rows, never replace a standard row. -->
 - `domain` — dispatched → `.project/research/evidence-domain.md` — <why this dimension ran>
-- `stack` — skipped → none — <why this dimension was skipped>
+- `stack` — dispatched → `.project/research/evidence-stack.md` — <why this dimension ran>
 - `pitfalls` — skipped → none — <why this dimension was skipped>
 - `similar` — skipped → none — <why this dimension was skipped>
 
 ## Question assignments
 
 <!-- Copy every [RESEARCH] question from INTENT.md exactly once. Use `- none`
-     only when INTENT.md has no [RESEARCH] questions. -->
-- `[RESEARCH] <question copied from INTENT.md>` → `domain`
+     only when INTENT.md has no [RESEARCH] questions. The question is a
+     CommonMark code span: choose a fence length not used by a backtick run in
+     the question (a longer fence is usually easiest), with one space of
+     padding on each side. Each row may target one or more dispatched
+     dimensions, each in its own code span and separated by commas. Every
+     dispatched dimension must receive a question and answer all its assigned
+     questions in its evidence file. For example:
+     - `` [RESEARCH] Does `Widget` match `sample.json`? `` → `domain`, `stack`
+     A question that ends in a backtick also needs padding, as in:
+     - `` [RESEARCH] Does the label end with `Widget`?` `` → `domain`
+     After removing the fence and CommonMark padding, the text must equal the
+     INTENT question exactly. -->
+- `` [RESEARCH] <question copied from INTENT.md> `` → `domain`, `stack`

package/skills/gsd-path/templates/state.md

@@ -10,7 +10,7 @@ branch: null        # bound per milestone as gsd-path/M00N; after integration
                     # the router rebinds before any next-milestone file change
                     # the bound branch is never main; ship integrates it there
 archive: null       # persisted archive transaction path; never recomputed
-integration_default: direct # direct | pull-request; project setting
+integration_default: direct # direct | pull-request | external-landing; project setting
 integration: direct # current milestone; may override the default before build
 integration_source: default # default | milestone; preserves override provenance
 ---

package/skills/gsd-path/templates/wave-review.md

@@ -10,10 +10,11 @@
      with actual values, otherwise omit them:
 Reviewed HEAD: <full review commit SHA>
 Review scope: final
-     In each surface SC block also include Surface, Check, and Observed fields
-     using the final-review format. Surface holds exactly the surface name from
-     PLAN.md's Surface contract; put walkthrough detail in Check and Observed.
-     Record the actual walkthrough evidence once. -->
+     In each surface SC block keep the mandatory `- ✅` / `- ❌` evidence line
+     (the wave gate requires it). Also include Surface, Check, and Observed
+     fields using the final-review format. Surface holds exactly the surface name
+     from PLAN.md's Surface contract; put walkthrough detail in Check and Observed.
+     The `- ✅` line may summarize Observed; do not omit it. -->
 
 Wave verdict: <pass | blocked — blocked if any task fails>
 Cycle: <C>
@@ -45,12 +46,21 @@ Contract violations (blocking):
 <!-- One heading per INTENT.md success criterion owned by a task in this
      wave, ending `: pass` or `: fail`. `scripts/check_handoffs.py wave
      --review <this file>` gates the SC id set and verdicts. Omit this
-     section when no task in the wave owns an SC. -->
+     section when no task in the wave owns an SC.
+     Copy the criterion text from INTENT.md `## Success criteria` exactly as
+     `_success_criteria` stores it: indented continuation lines join with a
+     single space and keep their leading `- ` markers; the gate compares
+     heading text with `_normalize_ws` only (no paraphrase or stripped
+     sub-bullets). -->
 
-### SC1 — <criterion>: <pass | fail>
+### SC1 — <criterion as stored by the gate>: <pass | fail>
 - ✅ <evidence: verify output / file:line checked>
 - ❌ <criterion> — found: <what exists instead, file:line>
   fix: <concrete direction a coder can execute without re-investigating>
+<!-- Quick-lane final scope (Review scope: final): add after the evidence line:
+- **Surface**: <surface name from PLAN.md>
+- **Check**: `<walkthrough command>`
+- **Observed**: <what was seen> -->
 
 ## Fixed since last cycle
 

package/skills/gsd-path-build/references/build-native.md

@@ -24,6 +24,14 @@ python3 <absolute dispatch_driver.py> round --repo <absolute primary> --wave <N>
   [--child-timeout <owner seconds>]
 ```
 
+Use the absolute `dispatch_driver.py` from the active installed
+`gsd-path-build` skill when orchestrating a consuming project's build; that
+copy resolves role briefs and templates from its own skill bundle. The
+repository or npm package also supports the top-level `scripts/dispatch_driver.py`:
+when a default is not beside that script, it resolves from the shipped
+`skills/gsd-path` bundle. Explicit `--role-brief`, `--task-template`, and
+`--template` paths override those defaults and must name existing files.
+
 `round` owns the entry transition described in Preconditions and branch
 binding, checkpointed as `build: start milestone`, and sets `build/blocked`
 on a dependency deadlock or a blocked
@@ -136,6 +144,13 @@ dispatch contract and perform steps 1–5 by hand.
    even while unrelated tasks still run, so rerun `ready` after each landing.
    A `NEEDS-ORCHESTRATOR` block stays unselectable until its `Orchestrator
    answer` is recorded in the task Log and the task is back to `pending`.
+   An all-done wave whose latest canonical review cycle has any blocked lens
+   gates later waves: `ready` selects unfinished later tasks with a `## Review
+   findings` section that depend on it, sets `current_wave` to the earliest
+   repair wave, and adds `repair_for_wave` with the source wave. When no such
+   repair remains, `ready` returns no tasks and adds `blocked_review` (`wave`,
+   `cycle`, `waiting_waves`); a later passing canonical review cycle releases
+   the waiting waves.
    Its typed errors are the recovery rule:
    - `task-recovery-required`: for each listed failed or blocked task run
      `python3 <absolute build_state.py> reconcile --repo <absolute primary>
@@ -196,7 +211,7 @@ dispatch contract and perform steps 1–5 by hand.
    a later round unlocked by fresh landings records the later HEAD — and
    lint every ready task's brief with the bundled
    `scripts/check_task_briefs.py --repo <absolute repo root> --base <recorded
-   base>` and re-check Intent coverage with
+   base> --project-dir <routed project dir>` and re-check Intent coverage with
    `python3 <absolute check_handoffs.py> plan --repo <absolute repo root>`
    before creating any worktree; a lint or coverage failure is a documented plan
    defect — repair it against INTENT.md and SYNTHESIS.md, then re-establish

package/skills/gsd-path-build/references/dispatch.md

@@ -44,6 +44,19 @@ use exactly one matching branch:
   create another worktree. Encode task dependencies explicitly; launch
   independent children concurrently up to the host's advertised
   concurrent-subagent capacity.
+- A `muse.subagent_spawn` tool (with `muse.subagent_wait`,
+  `muse.subagent_read_result`, and `muse.subagent_send_message` siblings) is
+  Muse Code. Omit `subagent_type` (general-purpose, full capability), pass the
+  logical task name as `task_name` and `role`, and the complete brief as
+  `objective`. Never set `worktree_isolation`. Keep the returned
+  `subagent_id`; send a correction to a still-live child with
+  `muse.subagent_send_message` mode `followup` and the complete new prompt,
+  otherwise start a fresh child. Collect with `muse.subagent_wait`
+  (`wait_for: task_terminal`) then `muse.subagent_read_result`; on
+  `root_capacity_exhausted`, wait for a child to finish and retry. Spawn has no
+  model or effort argument, so record no such capability. If only
+  `muse.workflow` is exposed (untrusted workspace), do not script or inline
+  the work; stop and report that the workspace must be trusted.
 
 For every branch:
 

package/skills/gsd-path-build/references/reviewer-final.md

@@ -1,8 +1,13 @@
 ## Final integration mode
 
 Use only final-review.md. Treat INTENT.md success criteria as the rubric.
-Exercise the running system and record `met`, `not-met`, or `unverifiable`
-with checked command output or a precise file reference. When PLAN.md carries
+Each `### SCn —` heading must match the criterion text as
+`check_handoffs._success_criteria` stores it from INTENT.md `## Success
+criteria`: indented continuation lines join with a single space and keep
+their `- ` list markers; the gate compares titles with `_normalize_ws`
+only. Exercise the running system and record `met`, `not-met`, or
+`unverifiable` with checked command output or a precise file reference.
+When PLAN.md carries
 a `## Surface contract`, every criterion it lists under a surface is checked
 by performing that surface's Walkthrough from its Entry in the supplied
 sidecar: `Surface` names that surface, Check names what was performed,
@@ -14,6 +19,19 @@ re-run PLAN.md's project Verify; cite the orchestrator's recorded
 project-verify sidecar output. `pass`
 requires every criterion to be `met`.
 
+When INTENT.md `## Edge coverage` or `## Prohibitions` tags a criterion with a
+`held-out` edge or a `judgment` prohibition, grade that criterion on cited
+evidence for every tag (see the [spec-reach probes](spec-probes.md)). Name
+each id in Check, Observed, or Reference with its evidence: the held-out
+test's recorded passing output from the PLAN.md `## Held-out checks` test, or
+the observed behavior judged against the prohibition's Detail. When a tag's
+evidence is missing, did not run, or cannot be judged, record `unverifiable`
+with `Finding: insufficient spec evidence: <id> <what is missing>` and a Fix
+direction naming the check to add or run. Never mark such a criterion `met`
+on inference or on code that merely looks right; the ship gate refuses a
+`met` verdict that does not cite every tag. Grade untagged criteria as usual:
+the trigger is the INTENT.md tag, never your own doubt.
+
 ## Final gap mode
 
 Use only gap-review.md. Check the one cross-wave risk in the brief against the

package/skills/gsd-path-build/references/reviewer-wave.md

@@ -23,10 +23,18 @@ tasks in this wave as the rubric. For each task:
    concrete fix direction for each failure.
 
 Then check each INTENT.md success criterion owned by a task in this wave
-against that same isolated product. Copy the criterion verbatim from
-INTENT.md. Mark `pass` or `fail` with evidence; a failed owned SC blocks
+against that same isolated product. In each `### SCn —` heading, copy the
+criterion text exactly as `check_handoffs._success_criteria` stores it from
+INTENT.md `## Success criteria`: indented continuation lines are joined
+with a single space and keep their `- ` list markers in the compared text;
+only whitespace is normalized at the gate. Do not paraphrase or drop
+sub-bullets. Mark `pass` or `fail` with evidence; a failed owned SC blocks
 the wave. Omit the Intent coverage section when no task in the wave owns
-an SC.
+an SC. When INTENT.md `## Edge coverage` or `## Prohibitions` has rows for
+an owned SC, judge it against those rulings too: cite each `held-out` edge
+id with its held-out test's recorded output and each `judgment` prohibition
+id with what you observed. A missing held-out result or a violated ruling
+fails the SC.
 
 Allow changed paths only in the task's `files` plus its assigned task file.
 Within the task file, allow orchestrator-owned `base`, `worktree`,
@@ -65,7 +73,10 @@ criterion's Intent coverage block includes `- **Surface**:`, `- **Check**:`, and
 `- **Observed**:` with the walked states and actual result. `Surface` holds
 exactly the surface name from PLAN's Surface contract; walkthrough detail belongs
 in Check and Observed. Reuse recorded task
-output if it proves that exact walkthrough; run only a missing check. Final-scope
+output if it proves that exact walkthrough; run only a missing check. Cite
+every `held-out` edge and `judgment` prohibition id of each criterion in its
+evidence; shipping derives FINAL.md from these records, and an uncited id
+sends the milestone to a dispatched final review instead. Final-scope
 coverage shares this wave artifact; do not write a second report. Shipping's
 runtime checks freshness and derives the final view from these records.
 

package/skills/gsd-path-build/references/reviewer.md

@@ -46,7 +46,9 @@ Resolve sibling links against this role file's directory.
   from the same model family is one evidence path; independence comes
   from re-run evidence, different sources, or a different model family.
 - Pass any reasonable satisfied reading of an ambiguous wave criterion and
-  warn that it needs tightening.
+  warn that it needs tightening, unless INTENT.md `## Edge coverage` or
+  `## Prohibitions` rules on that reading: a ruling there binds, and a
+  reading that contradicts it fails.
 - Do not edit code, tasks, plans, or implementation state.
 
 Return verdicts and the review output path without extra prose.

package/skills/gsd-path-build/references/spec-probes.md

@@ -0,0 +1,150 @@
+# Spec-reach probes
+
+Define runs two probes over the success criteria before approval: the edge
+probe (what each criterion must do at its edges) and the prohibition probe
+(what each criterion must never silently become). Both leave a table in
+INTENT.md. Plan, build review, and final review read those tables; the
+`check_handoffs.py intent`, `plan`, and `final` gates enforce them.
+
+## Why define owns this
+
+A reviewer can only check what the intent states. An edge nobody wrote down
+is never checked: final review covers exactly the INTENT success criteria,
+and a reviewer passes any reasonable reading of an ambiguous one. Model
+reviewers are also confidently wrong on exactly these gaps. On three tasks
+whose correct behavior the spec left unstated, LLM verifier verdicts caught
+the defect 0 times in 12 while a held-out test caught all three; in a larger
+replication, stating the surfaced edge in the spec raised the verifier's
+catch rate to 98% ([Verifier Reach Is Spec Reach](https://github.com/davesienkowski/verifier-reach-is-spec-reach)).
+A smarter reviewer does not close that gap; a wider intent does. The user is
+present at define, so define is where the edge gets its ruling.
+
+## Edge probe
+
+Walk every success criterion:
+
+1. Name the data shapes the criterion handles, then raise only the
+   categories those shapes reach:
+
+   | Shape | Categories |
+   |-------|------------|
+   | numeric range, dates, money, counts | boundary, precision |
+   | list, set, rows, intervals | adjacency, empty, ordering |
+   | text, names, identifiers | empty, encoding |
+   | state that persists or repeats | idempotency, concurrency |
+   | files, network, processes | concurrency |
+
+2. For each raised category, write one concrete candidate edge and the
+   ruling you recommend:
+
+   | Category | Probe question |
+   |----------|----------------|
+   | boundary | What happens exactly at each minimum, maximum, or threshold, and one step either side? |
+   | adjacency | When two items are equal or just touch, do they merge, collide, or stay separate? |
+   | empty | What is the result for empty, single-item, or missing input? |
+   | encoding | Whose length or equality applies: bytes, code points, grapheme clusters, normalized form, case? |
+   | ordering | When items compare equal, is output order specified and stable? |
+   | precision | Where can rounding, overflow, or truncation happen, and which rule applies? |
+   | idempotency | What happens when this runs twice on the same input? |
+   | concurrency | If interrupted or run in parallel, what is guaranteed? |
+
+3. Ask the user in one small round, all criteria together, recommended
+   ruling first. Never rule on an edge's behavior yourself: the correct
+   answer is exactly what the criteria did not say, so a guess here is the
+   defect this probe exists to prevent. Under pre-approval, an edge whose
+   behavior the user has not stated is still a required answer: stop and
+   ask instead of ruling.
+
+4. Record each ruling as one row:
+   - `criterion SCn` when the answer is observable where the user sees the
+     work. Add or amend that success criterion (define owns criteria), then
+     point the row at it. An existing criterion that already states the
+     edge may be named directly.
+   - `held-out` when the answer is a precise rule or a set of examples that
+     belongs in a test rather than a user-facing criterion (a normalization
+     form, a rounding rule, an inclusive bound on an internal API). Write the
+     ruling or the user's examples verbatim in Detail. The plan must schedule
+     a named test that pins it.
+   - `dismissed` when the edge cannot occur for this criterion. Detail says
+     why ("input is a closed enum"). "Not important" is not a reason.
+
+Every criterion gets at least one row. A criterion with no data shape gets
+one row with category `none`, dismissed with its reason.
+
+## Prohibition probe
+
+Walk every success criterion with one adversarial question: what could this
+silently become that the user would not want, although nothing in INTENT.md
+forbids it? Generate candidates privately, then keep only values, safety,
+privacy, fairness, and transparency items: "must not email unsubscribed
+users", "must not store raw card numbers in logs", "must not use guilt
+wording". Drop routine engineering items (mutating input, throwing on empty
+input, leaking handles); those are edges or ordinary review. Do not mint
+generic security or compliance canon (injection, path traversal, data
+retention law); record a real compliance need under Constraints instead.
+Expect two or three kept items for work people touch, and often none for
+internals.
+
+Present the kept items with a recommended ruling and record each as a row:
+
+- `criterion SCn` when a test or command can check it. State it as a
+  success criterion and point the row at it.
+- `judgment` when it is real but not mechanically checkable. Detail says
+  what the final reviewer looks for.
+- `dismissed` when the user rules it out. Detail records the reason.
+
+Work that affects no person directly records a single row instead, and no
+other: `| N1 | all | none | dismissed | <why no person is affected> |`.
+
+## INTENT.md tables
+
+```markdown
+## Edge coverage
+
+| Edge | Criterion | Category | Disposition | Detail |
+|------|-----------|----------|-------------|--------|
+| E1 | SC1 | boundary | criterion SC4 | |
+| E2 | SC1 | empty | dismissed | the command always receives at least one file |
+| E3 | SC2 | encoding | held-out | names compare by NFC code points, case-sensitive |
+
+## Prohibitions
+
+| Prohibition | Criterion | Must not | Disposition | Detail |
+|-------------|-----------|----------|-------------|--------|
+| N1 | SC2 | send a reminder to an unsubscribed user | criterion SC5 | |
+| N2 | SC2 | use guilt or shame wording | judgment | reminder copy is neutral and states only the due item |
+```
+
+Ids are contiguous from `E1` and `N1`. Detail is required for every row that
+is not `criterion SCn`. The headings are exact: `## Edge coverage` and
+`## Prohibitions`. An INTENT.md without them predates the probes and is not
+rechecked; a near-miss heading fails the gate rather than switching it off.
+
+## Downstream
+
+- **Plan.** Every `held-out` edge gets one PLAN.md `## Held-out checks` row
+  naming the task that owns the edge's criterion and the test file (a
+  `path::test_name` node id is fine). That file is listed in the task's
+  `files`, the task's Verify runs it, and the task's Acceptance criteria
+  state the edge id and its ruling. A `criterion SCn` row needs nothing extra: SCn is
+  already covered like any criterion. A `judgment` prohibition belongs in
+  the owning task's Approach so the coder knows the line.
+- **Review.** A row pins the reading of its criterion. A reviewer does not
+  pass a reading that contradicts a ruling in either table, and cites each
+  held-out edge and judgment prohibition id with its evidence.
+- **Final review.** A criterion that carries a held-out edge or a judgment
+  prohibition is `met` only when its Check, Observed, or Reference cites
+  every such id with the evidence: the held-out test's recorded passing
+  output, or the observed behavior judged against Detail. When that
+  evidence is missing, did not run, or cannot be judged, record
+  `unverifiable` with `Finding: insufficient spec evidence: <id> ...`;
+  never `met` on inference. The trigger is the tag, not reviewer doubt:
+  criteria without a tag are graded as usual and never abstained.
+
+## What the gates can and cannot prove
+
+`check_handoffs.py intent` (before approval and again when define records
+approval), `plan`, and `final` prove the tables are complete, every held-out
+edge has a scheduled test, and every tagged `met` cites its tags. They cannot
+prove who made a ruling or that a cited result says what the verdict claims.
+Those stay with the define conversation and the reviewer's recorded evidence.