@opengsd/gsd-path 1.4.0 → 1.6.0

package/skills/path/scripts/task_context.py

@@ -1,23 +1,27 @@
 #!/usr/bin/env python3
+# gsd-path project runtime
 """Render a read-only coder intent view from the approved task and intent."""
 
 import argparse
 import hashlib
 import re
 import sys
+sys.dont_write_bytecode = True
 from pathlib import Path
 
 try:
     from scripts import check_handoffs as contracts
+    from scripts import _common
 except ImportError:
     import check_handoffs as contracts
+    import _common
 
 
 def render(repo: Path, task: Path) -> str:
     intent_path = repo.resolve() / '.project/intent/INTENT.md'
     task = task.resolve()
-    intent = intent_path.read_bytes().decode('utf-8')
-    task_text = task.read_bytes().decode('utf-8')
+    intent = _common.read_user_text(intent_path)
+    task_text = _common.read_user_text(task)
     owned = contracts._owned_criteria(task_text, task.stem)
     criteria = contracts._success_criteria(intent)
     unknown = set(owned) - set(criteria)
@@ -40,7 +44,14 @@ def render(repo: Path, task: Path) -> str:
         if simple:
             before, after = intent[:section.start('body')], intent[section.end('body'):]
             # Corrections and task interfaces can explicitly refer to another SC.
-            required = set(owned) | set(re.findall(r'\bSC\d+\b', before + after + task_text))
+            # The spec-probe tables name every SC by design, so they select nothing.
+            scanned = re.sub(r'(?ms)^## (?:Edge coverage|Prohibitions)[ \t]*\n.*?(?=^## |\Z)', '',
+                             before + after)
+            required = set(owned) | set(re.findall(r'\bSC\d+\b', scanned + task_text))
+            # An owned criterion's edge or prohibition ruled into another SC needs that SC's text.
+            for rows in (contracts.edge_coverage(intent, criteria), contracts.prohibitions(intent, criteria)):
+                required |= {row['target'] for row in (rows or {}).values()
+                             if row['target'] and row['criterion'] in owned}
             selected = ''.join(chunk for item, chunk in zip(items, chunks) if f'SC{item[1]}' in required)
             projected = before + '\n' + (selected or '- No criteria assigned.\n\n') + after
             mode = 'owned-criteria'

package/skills/path/scripts/workflow_run.py

@@ -77,7 +77,7 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
         head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
                               cwd=repo, capture_output=True, encoding="utf-8", errors="replace", check=True).stdout.strip()
         step("check_task_briefs.py", "--repo", str(repo), "--base", head,
-             "--tasks-dir", f"{project_dir}/tasks")
+             "--tasks-dir", f"{project_dir}/tasks", "--project-dir", project_dir)
         panel = ["validate-plan", "--plan", str(repo / project_dir / "plan/PLAN.md"),
                  "--intent", str(repo / project_dir / "intent/INTENT.md")]
         charter = repo / ".project/CHARTER.md"
@@ -199,7 +199,7 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
             head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
                                   cwd=repo, capture_output=True, encoding="utf-8", errors="replace", check=True).stdout.strip()
             step("check_task_briefs.py", "--repo", str(repo), "--base", head,
-                 "--tasks-dir", f"{project_dir}/tasks")
+                 "--tasks-dir", f"{project_dir}/tasks", "--project-dir", project_dir)
             step("check_handoffs.py", "plan", *common)
         elif action == "prepare-task" and _task_member(repo, project_dir, task_id):
             # A member task works in a sidecar of its member; its Verify runs there at finish.
@@ -210,8 +210,14 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
                         "--base", expected_head, "--task-id", task_id,
                         "--round-size", str(round_size))
             if task["mode"] == "serial":
+                name = f"task-{task_id.lower()}-verify"
+                stale = isolation.sidecar_root(repo, "verify", name)
+                if os.path.lexists(stale / ".git"):
+                    # An earlier prepare-task left this sidecar. Only one that is proven untouched is replaced.
+                    steps.append({"script": "isolation.py", "result": isolation.retire_stale_verify(
+                        repo, stale, isolation.verify_branch_name(name))})
                 step("isolation.py", "isolate-verify", "--repo", str(repo),
-                     "--base", expected_head, "--name", f"task-{task_id.lower()}-verify")
+                     "--base", expected_head, "--name", name)
         elif action == "build-evidence":
             proof = step("build_state.py", "verify-landed", *common, "--head", expected_head)
             # The landing proof has one canonical home; lean final-review reuse allows only this path.
@@ -257,6 +263,9 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
                         ruled.add(row[0])
                 if any(len(row) == 6 and row[4] == "NEEDS-USER" and row[0] not in ruled for row in queue):
                     raise StepFailed("DOCS-AUDIT.md has NEEDS-USER rows without a user ruling")
+            if kind == "intent":
+                # Malformed or incomplete spec-probe tables are not a pre-approvable draft.
+                step("check_handoffs.py", "intent", *common)
             if kind == "plan":
                 if gate_plan()["mode"] != "off":
                     raise StepFailed("pre-approval requires review_panel off")
@@ -275,7 +284,8 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
             if action == "approve-plan":
                 step("pipeline_state.py", "approve", *common, "--kind", "plan",
                      "--expected-head", expected_head)
-    except (StepFailed, OSError, subprocess.CalledProcessError, ValueError, KeyError, TypeError) as error:
+    except (StepFailed, isolation.IsolationError, OSError, subprocess.CalledProcessError,
+            ValueError, KeyError, TypeError) as error:
         return {"status": "blocked", "reason": str(error), "steps": steps,
                 "next": next_step}
     return {"status": "complete", "steps": steps, **outputs}

package/skills/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/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/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 has every word of the criterion in INTENT.md
+     `## Success criteria`: join continuation lines and sub-bullets with a
+     single space (the `- ` markers of sub-bullets are optional). The gate
+     compares every other word. -->
+
+### SC1 — <criterion from INTENT.md>
 
 - **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/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/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/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/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/path/templates/state.md

@@ -10,9 +10,10 @@ 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
+default_branch: main # origin default branch; initialization records it once, nothing changes it
 ---
 
 # Project State

package/skills/path/templates/task.md

@@ -11,6 +11,7 @@ task_branch: null   # orchestrator-owned: gsd-path-task/<id> while parallel; nul
 # Optional explicit dispatch overrides: model: <advertised slug|inherit>
 # effort: <advertised effort|inherit>
 # repo: <member>    # multi-repo only: the MEMBERS.md member this task changes; omit for the coordinator
+# supersedes: [<task id>]  # only when INTENT requires it: earlier-wave tasks whose behavior this task replaces; retires their Verify
 files:              # every file this task may touch — dispatch checks overlap
   - <path>
 ---

package/skills/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>
@@ -25,9 +26,17 @@ Tasks reviewed: <count>
 
 ## T001 — <title>: <pass | fail>
 
-<!-- Per task criterion: copy the full acceptance/interface criterion verbatim
-     before the em dash; join wrapped lines with spaces. An AC id or summary
-     alone cannot be matched by review_findings.py. -->
+<!-- Task sections go in task id order (T001 before T002), not in the order
+     of the PLAN.md wave table. The heading title is the exact `title:` of
+     the task file. An evidence line starts with `- ✅ ` (pass) or `- ❌ `
+     (fail). A section needs one or more lines with the marker of its own
+     verdict, so a failed task needs a `- ❌ ` criterion line.
+     Per task criterion: copy every word of the acceptance/interface
+     criterion before the em dash; join wrapped lines and sub-bullets with
+     spaces (the `- ` markers of sub-bullets are optional). An AC id or
+     summary alone cannot be matched by review_findings.py.
+     Write literal markup and code in backticks inside a sentence: text
+     such as <b> outside backticks reads as an unfilled placeholder. -->
 - ✅ <criterion> — <evidence: verify output / file:line checked>
 - ❌ <criterion> — found: <what exists instead, file:line>
   fix: <concrete direction a coder can execute without re-investigating>
@@ -45,12 +54,22 @@ 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 every word of the criterion from INTENT.md `## Success criteria`:
+     join indented continuation lines and sub-bullets with a single space
+     (the `- ` markers of sub-bullets are optional). The gate compares every
+     other word: no paraphrase, no dropped sub-bullet.
+     Each SC block needs an evidence line with the marker of its own
+     verdict: `- ✅ ` (pass) or `- ❌ ` (fail). -->
 
-### SC1 — <criterion>: <pass | fail>
+### SC1 — <criterion from INTENT.md>: <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