@opengsd/gsd-core 1.5.0-rc.3 → 1.5.0-rc.4

package/gsd-core/bin/lib/worktree-safety.cjs

@@ -701,6 +701,7 @@ function reapOrphanWorktrees(repoRoot, deps = {}) {
     const readFileSafe = deps.readFileSafe || defaultReadFileSafe;
     const mtimeSafe = deps.mtimeSafe || defaultMtimeSafe;
     const reapMtimeGuardMs = deps.reapMtimeGuardMs !== undefined ? deps.reapMtimeGuardMs : REAP_MTIME_GUARD_MS;
+    const nowMs = deps.nowMs ?? Date.now();
     const results = [];
     // 1. Discover the .git/worktrees/ admin directory.
     const gitDir = execGit(['rev-parse', '--git-dir'], { cwd: repoRoot });
@@ -803,7 +804,7 @@ function reapOrphanWorktrees(repoRoot, deps = {}) {
         }
         // 4a. Stale-lock guard: skip if lock is too fresh (PID recycling / race).
         const lockMtime = mtimeSafe(lockedFile);
-        if (!lockMtime || Date.now() - lockMtime.getTime() < reapMtimeGuardMs) {
+        if (!lockMtime || nowMs - lockMtime.getTime() < reapMtimeGuardMs) {
             results.push({ path: worktreePath, status: 'skipped', reason: 'lock_too_fresh' });
             continue;
         }

package/gsd-core/references/edge-probe.md

@@ -77,6 +77,17 @@ Two rules keep the probe honest and prevent an "everything is N/A" failure mode:
 2. **Dismissal requires a reason string.** "N/A — input is a bounded enum, no boundary
    exists" is valid; silence is not. The reason string is the audit trail.
 
+**Zero-classification surfaces an `unclassified` candidate (#1110).** The relevance filter is
+a heuristic over prose cues, so a requirement whose wording *is* edge-relevant but matches no
+shape cue would otherwise classify to zero shapes → zero edges and vanish from coverage with
+no signal — the same silent blind spot the probe exists to catch. Instead, a requirement with
+non-empty prose, no authored `shapes`, and zero matched shapes surfaces exactly one soft
+`unclassified — review manually` candidate (`category: "unclassified"`, `status: "unresolved"`).
+It is a dismissible nudge — resolve it, or dismiss it with a reason (e.g. a genuinely edge-free
+static-asset requirement) — never a hard block. `unclassified` is a review signal, **not** a
+ninth taxonomy category: the closed eight above are unchanged, and an explicit `shapes: []`
+opt-out stays silent (the author's deliberate "no edge surface").
+
 Each raised edge carries two orthogonal axes — a resolution **lifecycle** and, when
 resolved, a **verification** tier (ADR-550 Decision 7, the shared probe-core model):
 

package/gsd-core/references/prohibition-probe-fixtures/01-streak-reminder/expected.json

@@ -0,0 +1,14 @@
+{
+  "items": [
+    {
+      "requirement_id": "R1",
+      "category": "values",
+      "status": "resolved",
+      "verification": "judgment",
+      "resolution": null,
+      "reason": null,
+      "statement": "MUST NOT use shaming, guilt, or loss-aversion streak framing (e.g. \"Don't lose your streak!\") — the reminder must encourage without penalty framing"
+    }
+  ],
+  "coverage": { "applicable": 1, "resolved": 1, "unresolved": 0, "byVerification": { "test": 0, "judgment": 1 } }
+}

package/gsd-core/references/prohibition-probe-fixtures/02-clean-utility/expected.json

@@ -0,0 +1,4 @@
+{
+  "items": [],
+  "coverage": { "applicable": 0, "resolved": 0, "unresolved": 0, "byVerification": { "test": 0, "judgment": 0 } }
+}

package/gsd-core/references/prohibition-probe-fixtures/03-multi-prohibition/expected.json

@@ -0,0 +1,32 @@
+{
+  "items": [
+    {
+      "requirement_id": "R1",
+      "category": "fairness",
+      "status": "resolved",
+      "verification": "judgment",
+      "resolution": null,
+      "reason": null,
+      "statement": "MUST NOT use protected attributes (race, gender, age, national origin) or their proxies (zip code, name) in the loan decision or rate"
+    },
+    {
+      "requirement_id": "R1",
+      "category": "privacy",
+      "status": "resolved",
+      "verification": "test",
+      "resolution": null,
+      "reason": null,
+      "statement": "MUST NOT store raw PII / financial secrets (SSN, full account or card numbers) in plaintext in the audit log"
+    },
+    {
+      "requirement_id": "R1",
+      "category": "transparency",
+      "status": "resolved",
+      "verification": "judgment",
+      "resolution": null,
+      "reason": null,
+      "statement": "MUST NOT mislead or omit the true rate/APR/terms in the explanation; an adverse decision must state the real principal reason (adverse-action)"
+    }
+  ],
+  "coverage": { "applicable": 3, "resolved": 3, "unresolved": 0, "byVerification": { "test": 1, "judgment": 2 } }
+}

package/gsd-core/references/prohibition-probe.md

@@ -0,0 +1,248 @@
+# Prohibition-Probe — Spec-Completeness Must-NOT Reference
+
+Shared reference for the spec/requirements phase. Companion to
+`@~/.claude/gsd-core/references/edge-probe.md`: `edge-probe` reaches the
+**data/behavior-shape axis** (boundaries, adjacency, encoding, ordering) — the things a
+feature must *do*. This reference reaches the orthogonal **must-NOT axis** (product, values,
+safety, ethics) — the things a feature must *never silently become*. The edge-probe caught
+0/8 of these in controlled testing because it is the wrong instrument: a shape taxonomy
+cannot surface "the reminder must not shame the user." Walk each requirement through the
+two-stage recall→precision protocol below and resolve each surfaced prohibition to exactly
+one state.
+
+This doc is written in generic `requirements → checks → verifier` terms with no
+tool-specific vocabulary, so it is portable: copy it into any spec/requirements process.
+A short mapping table at the end binds it to common host structures.
+
+## Why front-of-pipeline
+
+A goal-backward verifier only checks assertions that exist; an assertion only exists for a
+requirement that was written down. The class of constraint this probe targets — the
+*"must-NOT"* the author assumed but never wrote — is invisible to the verifier in exactly
+the same way an omitted edge is, but with a sharper failure mode: a `✅ done` that means
+"the code matches the words in the spec" can still ship a feature that does what the author
+explicitly would *not* want. The manipulative-streak reminder, the loan model that proxies
+on zip code, the audit log that stores raw SSN — each one passes a literal spec while
+violating the intent. The fix is not a better verifier; it is **spec completeness**: surface
+the omitted prohibition into an explicit, checkable acceptance criterion *before* any code
+exists, after which the verifier reliably enforces it.
+
+The technique is adversarial elicitation, not deterministic computation. Unlike the edge
+taxonomy (a closed eight categories a classifier can apply), the recall stage is inherently
+model-driven: it asks an open question and reads prose. There is **no compiled
+`prohibition-probe.cjs` engine** — the recall stage is an LLM prose pass, and only the
+schema/projection layer is real code (ADR-550 Decision 7b). Building a deterministic
+recall adapter would be the scope-creep the maintainer flags.
+
+## Inputs
+
+A list of requirements, each a `{ id, text }` record where `text` is a testable statement.
+There is no shape override and no taxonomy classifier — the recall stage reads the prose
+directly and the precision stage filters its raw output. The probe runs **after** the
+edge-probe in the spec phase, over the same requirement list.
+
+## Two-stage protocol (recall → precision)
+
+The probe is a two-pass pipeline per requirement. Stage 1 maximizes recall (cast wide);
+Stage 2 restores precision (drop the noise). Running them in this order — wide then narrow —
+is what keeps the surfaced list both complete and short.
+
+**Stage 1 — Recall (adversarial probe).** Ask the single adversarial question of each
+requirement:
+
+> *What could this feature silently become that the author would NOT want, but the spec
+> does not forbid?*
+
+This question is model-robust (17/17 holistic surfacing including smaller models in the N18
+experiment). It deliberately over-produces: ~10 raw candidates per requirement, including
+routine engineering items. That over-production is intentional — recall first.
+
+**Stage 2 — Precision (one-pass classifier).** Filter the raw Stage-1 list in a single pass.
+The rule is a drop/keep split:
+
+- **DROP routine-engineering items** — anything that is a normal correctness or hygiene
+  concern rather than an intent constraint: "must not mutate its input", "must not throw on
+  empty list", "must return a primitive not an object", "must not leak a file handle". These
+  belong to the edge-probe or to ordinary code review, not here.
+- **KEEP values / safety / ethics items** — anything that, if violated, makes the feature do
+  something the author would object to on product, fairness, privacy, transparency, or
+  safety grounds: "must not use shaming framing", "must not proxy on protected attributes",
+  "must not store raw PII in plaintext".
+
+This collapses the raw ~10 to ~2–3 genuine prohibitions (GT 5/5, 0 false positives on the
+N18 eight-spec battery). A requirement that yields zero kept prohibitions emits an empty
+list — that is the correct precision outcome for a pure utility, not a failure.
+
+## Canon-referral (do not mint canon items)
+
+Some kept candidates are not bespoke at all — they are **canon** security/compliance
+constraints that a dedicated tool already owns. Do NOT mint a prohibition for them. Instead
+emit a one-line breadcrumb and stop:
+
+- OWASP / prototype-pollution / path-traversal / injection → breadcrumb to `/gsd:secure-phase`
+  and `eslint` (security plugins), not a minted prohibition.
+- GDPR / data-retention / consent → breadcrumb to `/gsd:secure-phase`.
+- Generic fairness/bias canon → breadcrumb to `/gsd:secure-phase`.
+
+The breadcrumb reads like: *"prototype-pollution is canon — covered by /gsd:secure-phase +
+eslint; not minted here."* This keeps the surfaced list to the ~2–3 **bespoke** items that
+no other tool would catch — the manipulative-framing prohibition, the product-specific
+fairness constraint — which is the whole value of the probe. Minting canon items both
+duplicates other tooling and drowns the bespoke signal (ADR-550 Decision 6).
+
+## Resolution states
+
+Each surfaced prohibition carries two orthogonal axes — a resolution **lifecycle** and, when
+resolved, a **verification** tier (ADR-550 Decision 7, the shared probe-core model; the
+lifecycle is identical to the edge-probe, the verification tiers differ):
+
+- **status** — `resolved | dismissed | unresolved` (IDENTICAL to the edge-probe):
+  - **resolved** — the prohibition is addressed; *how* it is addressed is the verification tier.
+  - **dismissed** — not a genuine prohibition for this feature, accompanied by a required,
+    non-empty reason string. "N/A — this utility has no user-facing surface, no values
+    constraint applies" is valid; silence is not. The reason string is the audit trail.
+  - **unresolved** — carried forward and flagged; the author chose not to resolve it yet.
+- **verification** (only when `status` is `resolved`; `null` otherwise) — `test | judgment`
+  (this REPLACES the edge-probe's `explicit | backstop`):
+  - **test** — the prohibition can be mechanically checked (a negative test, a lint rule, an
+    assertion that the audit log contains no raw SSN). A checkable assertion exists.
+  - **judgment** — the prohibition is real but cannot be reduced to a mechanical test (a
+    human/LLM judgment that the framing is not manipulative). It records intent and routes
+    to a judgment-based review rather than a green/red test.
+
+Splitting these axes keeps the lifecycle enum free of a verification fact and lets the
+prohibition adapter declare `test | judgment` without forking the shared lifecycle enum that
+the edge-probe's `explicit | backstop` also uses.
+
+## Output schema
+
+The probe emits, per kept prohibition, an item of the form:
+
+```
+{ requirement_id, category, status, verification, resolution, reason, statement }
+```
+
+where `statement` is the must-NOT sentence and `category` is the values/safety/ethics class
+(`values`, `fairness`, `privacy`, `transparency`, `safety`, …), plus a coverage summary:
+
+```
+coverage: { applicable, resolved, unresolved, byVerification: { test, judgment } }
+```
+
+`applicable` is the number of kept prohibitions, `resolved` = closed (`resolved` +
+`dismissed`) status items, `unresolved` is the remainder, and `byVerification` breaks the
+`resolved`-status items down by tier (`{ test, judgment }`). This JSON is the stable contract
+both the reference implementation and any third-party port emit.
+
+## Generic mapping (requirements → checks → verifier)
+
+| Host structure | "requirement" | a `resolved`/`test` prohibition becomes | a `resolved`/`judgment` prohibition becomes |
+|----------------|---------------|------------------------------------------|----------------------------------------------|
+| GSD SPEC | a SPEC Requirement | a SPEC acceptance criterion (marked prohibition) that `plan-phase` lifts into `must_haves.prohibitions` | a `must_haves.prohibitions` item routed to judgment review |
+| Gherkin feature | a Scenario | a negative `Then` assertion / tagged negative scenario | a tagged scenario routed to manual review |
+| OpenAPI operation | an operation | a contract test asserting the forbidden behavior never occurs | a documented constraint flagged for review |
+| Docstring contract | a documented behavior | a negative assertion in the contract test | a documented must-NOT for reviewers |
+
+The portable invariant: a `resolved`/`test` prohibition produces **a checkable negative the
+verifier iterates over** (GSD: a `must_haves.prohibitions` item with a test); a
+`resolved`/`judgment` prohibition produces a recorded intent routed to judgment review. An
+`unresolved` prohibition is an explicit assumption the downstream planner must surface, not
+silently drop.
+
+## Worked example (streak-reminder)
+
+A single requirement to send a daily habit reminder. The edge-probe sees a `stateful`
+requirement and asks about idempotency; the prohibition-probe asks the adversarial question
+and surfaces what the reminder must never *become*. Stage 1 over-produces ("must not spam",
+"must not throw on a deleted habit", "must not use shaming framing"); Stage 2 drops the
+routine-engineering items and keeps the one genuine values prohibition:
+
+```json prohibition-probe:01-streak-reminder/expected.json
+{
+  "items": [
+    {
+      "requirement_id": "R1",
+      "category": "values",
+      "status": "resolved",
+      "verification": "judgment",
+      "resolution": null,
+      "reason": null,
+      "statement": "MUST NOT use shaming, guilt, or loss-aversion streak framing (e.g. \"Don't lose your streak!\") — the reminder must encourage without penalty framing"
+    }
+  ],
+  "coverage": { "applicable": 1, "resolved": 1, "unresolved": 0, "byVerification": { "test": 0, "judgment": 1 } }
+}
+```
+
+The kept prohibition is `judgment`-tier: "manipulative framing" cannot be reduced to a
+mechanical test, so it records intent and routes to judgment review — but it is now an
+explicit acceptance criterion the spec must clear, not an unwritten assumption.
+
+## Worked example (clean-utility)
+
+A pure utility requirement — "deduplicate a list of integers" — has no user-facing surface,
+no values/safety/ethics dimension. Stage 1 still over-produces ("must not mutate the input",
+"must not change order"), but every candidate is routine engineering that Stage 2 drops (and
+the edge-probe already owns). The correct precision outcome is an empty prohibition list — a
+zero, not a false positive:
+
+```json prohibition-probe:02-clean-utility/expected.json
+{
+  "items": [],
+  "coverage": { "applicable": 0, "resolved": 0, "unresolved": 0, "byVerification": { "test": 0, "judgment": 0 } }
+}
+```
+
+This is the precision discipline that keeps the probe from crying wolf: a utility with no
+intent surface produces zero prohibitions, so a non-empty list always carries signal.
+
+## Worked example (multi-prohibition)
+
+A loan-decision requirement is the high-stakes case: it surfaces several distinct
+prohibitions across categories. Stage 1 produces a long list including canon items
+(prototype-pollution, generic GDPR retention) that canon-referral breadcrumbs out; Stage 2
+keeps the three bespoke values/safety items — a `fairness` constraint, a `privacy` constraint
+(`test`-tier, mechanically checkable against the audit log), and a `transparency` constraint:
+
+```json prohibition-probe:03-multi-prohibition/expected.json
+{
+  "items": [
+    {
+      "requirement_id": "R1",
+      "category": "fairness",
+      "status": "resolved",
+      "verification": "judgment",
+      "resolution": null,
+      "reason": null,
+      "statement": "MUST NOT use protected attributes (race, gender, age, national origin) or their proxies (zip code, name) in the loan decision or rate"
+    },
+    {
+      "requirement_id": "R1",
+      "category": "privacy",
+      "status": "resolved",
+      "verification": "test",
+      "resolution": null,
+      "reason": null,
+      "statement": "MUST NOT store raw PII / financial secrets (SSN, full account or card numbers) in plaintext in the audit log"
+    },
+    {
+      "requirement_id": "R1",
+      "category": "transparency",
+      "status": "resolved",
+      "verification": "judgment",
+      "resolution": null,
+      "reason": null,
+      "statement": "MUST NOT mislead or omit the true rate/APR/terms in the explanation; an adverse decision must state the real principal reason (adverse-action)"
+    }
+  ],
+  "coverage": { "applicable": 3, "resolved": 3, "unresolved": 0, "byVerification": { "test": 1, "judgment": 2 } }
+}
+```
+
+The `privacy` row is `test`-tier — "no raw SSN in the audit log" is a mechanical assertion —
+while `fairness` and `transparency` are `judgment`-tier. The byVerification rollup
+`{ test: 1, judgment: 2 }` is the count-preserved breakdown of the three `resolved`-status
+items. Each worked-example block above is kept byte-for-byte (parsed-JSON) identical to its
+fixture under `gsd-core/references/prohibition-probe-fixtures/` by
+`tests/prohibition-probe.docs-fixtures.test.cjs`, so the doc and the reference data cannot
+silently drift.

package/gsd-core/templates/spec.md

@@ -80,6 +80,20 @@ No "should feel good", "looks reasonable", or "generally works" — those are no
 Acceptance Criteria above; `backstop` rows must be carried into plan-phase `must_haves`.
 `⚠ UNRESOLVED` rows are flagged: planner must treat as assumption.]
 
+## Prohibitions (must-NOT)
+
+**Coverage:** [resolved]/[applicable] applicable prohibitions resolved · [unresolved] unresolved
+
+| Prohibition (must-NOT statement) | Requirement | Status | Verification / Reason |
+|----------------------------------|-------------|--------|------------------------|
+| [MUST NOT … must-NOT statement] | [Rn] | [resolved / dismissed / ⚠ UNRESOLVED] | [verification: test \| judgment, or dismissal reason] |
+
+[Generated by the prohibition probe (Step 5.6). `resolved` prohibitions become NEGATIVE
+acceptance criteria; a `resolved`/`test` row is a checkable negative the verifier iterates
+over, a `resolved`/`judgment` row routes to judgment review. Resolved prohibitions are lifted
+into `must_haves.prohibitions` by plan-phase. `dismissed` rows carry a required non-empty
+reason. `⚠ UNRESOLVED` rows are flagged: planner must treat as assumption.]
+
 ## Ambiguity Report
 
 | Dimension          | Score | Min  | Status | Notes                              |

package/gsd-core/workflows/complete-milestone.md

@@ -612,11 +612,7 @@ Extract `branching_strategy`, `phase_branch_template`, `milestone_branch_templat
 
 Detect base branch:
 ```bash
-BASE_BRANCH=$(gsd_run query config-get git.base_branch 2>/dev/null || echo "")
-if [ -z "$BASE_BRANCH" ] || [ "$BASE_BRANCH" = "null" ]; then
-  BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||')
-  BASE_BRANCH="${BASE_BRANCH:-main}"
-fi
+BASE_BRANCH=$(gsd_run query git.base-branch)
 ```
 
 **If "none":** Skip to git_tag.

package/gsd-core/workflows/execute-phase.md

@@ -189,7 +189,7 @@ CURRENT_PLAN_ID="{phase_number}-{plan_padded}"
 SUMMARY_PATH="{phase_dir}/{plan_padded}-SUMMARY.md"
 PLAN_COMMITS=$(git log --oneline --grep="${CURRENT_PLAN_ID}" -30)
 ```
-If production commits exist and `SUMMARY.md is missing`, stop before spawning a
+If production commits exist and `SUMMARY.md is missing` (no `.planning/async-jobs/*.json` manifest matches it: a match is a legal `external_job_waiting` deferral - reconcile per `docs/reference/planning-artifacts.md`, never re-dispatch), stop before spawning a
 new executor; continuing risks duplicate work and stale `STATE.md`/ROADMAP progress.
 Offer these recovery options:
 - `close out manually` — inspect commits, write SUMMARY.md, then update STATE/ROADMAP.
@@ -296,8 +296,9 @@ Check `branching_strategy` from init:
 Fork the new phase branch off `origin/HEAD` (the project's default branch), not the current HEAD — otherwise consecutive phases compound and stay unpushed (#2916). If `$BRANCH_NAME` already exists locally, reuse it as-is.
 
 ```bash
-DEFAULT_BRANCH=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
-DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
+DEFAULT_BRANCH=$(gsd_run query git.base-branch 2>/dev/null \
+  || git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||' \
+  || echo main)
 
 if git show-ref --verify --quiet "refs/heads/$BRANCH_NAME"; then
   git switch "$BRANCH_NAME" || { echo "ERROR: Could not switch to existing branch '$BRANCH_NAME'." >&2; exit 1; }

package/gsd-core/workflows/execute-plan.md

@@ -13,10 +13,23 @@ Read config.json for planning behavior settings.
 For each executed plan, the only complete close-out order is:
 `production-code commit(s) -> SUMMARY commit -> STATE/ROADMAP update`.
 
-The only legal half-state is mid-production-commits while the executor is still
-actively working. Once production commits for a plan exist, returning without a
-committed SUMMARY.md is an illegal partial-plan state. The next execute-phase
-resume must detect that condition before dispatching another executor.
+For a synchronous executor, the only legal half-state is mid-production-commits
+while the executor is still actively working. Once production commits for a plan
+exist, returning without a committed SUMMARY.md is an illegal partial-plan state.
+The next execute-phase resume must detect that condition before dispatching
+another executor.
+
+**Async exception — `external_job_waiting`.** When an executor dispatches an
+async external job (long-running compute) it commits an async-job manifest at
+`.planning/async-jobs/<job>.json` and returns *without* SUMMARY.md. With a
+manifest recording a non-terminal job for this plan, the SUMMARY-absent state is
+a **legal deferred state** (`external_job_waiting`), not an illegal partial.
+SUMMARY.md is deferred until the external job reaches a terminal state and its
+output is verified. Resume reconciles against the manifest and must NOT
+re-dispatch a fresh executor for a plan with a non-terminal manifest (that would
+duplicate the external job). The manifest schema is the stability contract in
+`docs/reference/planning-artifacts.md`; the scheduler adapter that *writes* it is
+a capability (#1164), not core.
 </atomic_close_out_invariant>
 
 <available_agent_types>
@@ -47,7 +60,9 @@ If `.planning/` missing: error.
 (ls .planning/phases/XX-name/*-SUMMARY.md 2>/dev/null || true) | sort
 ```
 
-Find first PLAN without matching SUMMARY. Decimal phases supported (`01.1-hotfix/`):
+Find first PLAN without matching SUMMARY. Decimal phases supported (`01.1-hotfix/`).
+
+**Exclude `external_job_waiting` plans from selection.** When choosing the first PLAN that lacks a matching SUMMARY, skip any plan whose `plan_id` matches an async-job manifest in `.planning/async-jobs/` (any status) — that plan is `external_job_waiting` or awaiting reconciliation, never work to (re-)dispatch (re-dispatching would duplicate the external job). Reconcile via the manifest / safe_resume_gate instead.
 
 ```bash
 PHASE=$(echo "$PLAN_PATH" | grep -oE '[0-9]+(\.[0-9]+)?-[0-9]+')
@@ -504,7 +519,7 @@ If `USER_SETUP_CREATED=true`: display `⚠️ USER SETUP REQUIRED` with path + e
 
 | Condition | Route | Action |
 |-----------|-------|--------|
-| summaries < plans | **A: More plans** | Find next PLAN without SUMMARY. Yolo: auto-continue. Interactive: show next plan, suggest `/gsd:execute-phase {phase}` + `/gsd:verify-work`. STOP here. |
+| summaries < plans | **A: More plans** | Find next PLAN without SUMMARY — skip any plan whose `plan_id` matches a non-terminal async-job manifest (`external_job_waiting`; see `identify_plan`). Yolo: auto-continue. Interactive: show next plan, suggest `/gsd:execute-phase {phase}` + `/gsd:verify-work`. STOP here. |
 | summaries = plans, current < highest phase | **B: Phase done** | Show completion, suggest `/gsd:plan-phase {Z+1}` + `/gsd:verify-work {Z}` + `/gsd:discuss-phase {Z+1}` |
 | summaries = plans, current = highest phase | **C: Milestone done** | Show banner, suggest `/gsd:complete-milestone` + `/gsd:verify-work` + `/gsd-add-phase` |
 

package/gsd-core/workflows/help/modes/full.md

@@ -256,11 +256,15 @@ Check project status and intelligently route to next action.
 Modes:
 - **default** — progress report + intelligent routing
 - **`--next`** — auto-advance to the next logical step (use `--next --force` to bypass safety gates)
+- **`--next --auto`** — like `--next`, but chains steps automatically until milestone completion or a blocking decision
+- **`--next --converge`** — when the next action is planning, route it through `/gsd:plan-review-convergence` instead of `/gsd:plan-phase`; requires `workflow.plan_review_convergence=true`. `--cross-ai` is an alias. Reviewer flags (`--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`) and `--max-cycles N` forward to the convergence loop.
 - **`--forensic`** — append a 6-check integrity audit after the progress report
 - **`--do "<text>"`** — smart router: dispatch freeform intent to the matching `/gsd-*` command (see *Smart Router* above)
 
 Usage: `/gsd:progress`
 Usage: `/gsd:progress --next`
+Usage: `/gsd:progress --next --auto`
+Usage: `/gsd:progress --next --auto --converge`
 Usage: `/gsd:progress --forensic`
 
 ### Session Management

package/gsd-core/workflows/next.md

@@ -230,7 +230,7 @@ If the current phase directory exists but has neither CONTEXT.md nor RESEARCH.md
 
 **Route 3: Phase has context but no plans → plan**
 If the current phase has CONTEXT.md (or RESEARCH.md) but no PLAN.md files:
-→ Next action: `/gsd:plan-phase <current-phase>`
+→ Next action: `/gsd:plan-phase <current-phase>` (or `/gsd:plan-review-convergence <current-phase>` when `PLAN_STRATEGY=converge`)
 
 **Route 4: Phase has plans but incomplete summaries → execute**
 If plans exist but not all have matching summaries:
@@ -254,6 +254,47 @@ If STATE.md shows paused_at:
 </step>
 
 <step name="show_and_execute">
+Parse the arguments passed to this workflow to detect the plan strategy and build convergence pass-through args:
+
+```bash
+PLAN_STRATEGY="local"
+if echo "$ARGUMENTS" | grep -qE '(^|[[:space:]])\-\-(converge|cross-ai)([[:space:]]|$)'; then
+  PLAN_STRATEGY="converge"
+fi
+
+CONVERGENCE_ARGS=""
+for REVIEW_FLAG in --codex --gemini --claude --opencode --ollama --lm-studio --llama-cpp --all --text; do
+  if echo "$ARGUMENTS" | grep -qE "(^|[[:space:]])${REVIEW_FLAG}([[:space:]]|$)"; then
+    CONVERGENCE_ARGS="${CONVERGENCE_ARGS} ${REVIEW_FLAG}"
+  fi
+done
+
+MAX_CYCLES_ARG=""
+if echo "$ARGUMENTS" | grep -qE '\-\-max-cycles\s+[0-9]+'; then
+  MAX_CYCLES_ARG=$(echo "$ARGUMENTS" | grep -oE '\-\-max-cycles\s+[0-9]+' | awk '{print $2}')
+  CONVERGENCE_ARGS="${CONVERGENCE_ARGS} --max-cycles ${MAX_CYCLES_ARG}"
+fi
+```
+
+If `PLAN_STRATEGY` is `converge`, fail fast unless the convergence feature gate is enabled:
+
+```bash
+if [ "$PLAN_STRATEGY" = "converge" ]; then
+  CONVERGENCE_ENABLED=$(gsd_run query config-get workflow.plan_review_convergence 2>/dev/null || echo "false")
+  if [ "$CONVERGENCE_ENABLED" != "true" ]; then
+    printf '%s\n' \
+      '/gsd:progress --next --converge is disabled (workflow.plan_review_convergence=false).' \
+      '' \
+      'Enable plan convergence with:' \
+      '' \
+      '  gsd config-set workflow.plan_review_convergence true' \
+      '' \
+      'Then re-run with --converge.'
+    exit 1
+  fi
+fi
+```
+
 Display the determination:
 
 ```
@@ -269,7 +310,9 @@ Display the determination:
 Then immediately invoke the determined command via SlashCommand.
 Do not ask for confirmation — the whole point of `/gsd:progress --next` is zero-friction advancement.
 
-**If `--auto` was passed:** after the determined command completes, automatically re-invoke `/gsd:progress --next --auto` to continue chaining to the next step. Repeat until one of:
+**Route 3 convergence override:** When the routing decision is Route 3 (plan) and `PLAN_STRATEGY=converge`, invoke `/gsd:plan-review-convergence <current-phase> ${CONVERGENCE_ARGS}` instead of `/gsd:plan-phase <current-phase>`.
+
+**If `--auto` was passed:** after the determined command completes, automatically re-invoke `/gsd:progress --next --auto` (forwarding `--converge`/`--cross-ai` and any reviewer flags if they were originally passed) to continue chaining to the next step. Repeat until one of:
 - A milestone completes (`/gsd:complete-milestone` is reached)
 - A blocking decision is required (safety gate triggers, prior-phase completeness prompt, user input needed)
 - An error or paused state is detected
@@ -296,4 +339,9 @@ Resume with: `/gsd:progress --next --auto` once resolved.
 - [ ] Next action correctly determined from routing rules
 - [ ] Command invoked immediately without user confirmation
 - [ ] Clear status shown before invoking
+- [ ] `--converge` routes Route 3 planning through `gsd-plan-review-convergence`
+- [ ] `--cross-ai` is accepted as an alias for `--converge`
+- [ ] `--converge` fails fast with enable instructions when `workflow.plan_review_convergence=false`
+- [ ] `--converge` forwards reviewer selector flags and `--max-cycles N`
+- [ ] Default planning remains `gsd-plan-phase` when convergence is not requested
 </success_criteria>

package/gsd-core/workflows/pause-work.md

@@ -48,7 +48,8 @@ If phase is detected, proceed with phase handoff path. Otherwise use the first m
 6. **Human actions pending**: Things that need manual intervention (MCP setup, API keys, approvals, manual testing)
 7. **Background processes**: Any running servers/watchers that were part of the workflow
 8. **Files modified**: What's changed but not committed
-9. **Blocking constraints**: Anti-patterns or methodological failures encountered during this session that a resuming agent MUST be aware of before proceeding. Only include items discovered through actual failure — not warnings or predictions. Assign each constraint a `severity`:
+9. **Outstanding async external jobs**: any `.planning/async-jobs/*.json` manifests for non-terminal jobs — record job id, backend, status, expected artifacts, verification + resume commands, and any watcher/daemon state. Do NOT cancel the external job; it keeps running across the pause.
+10. **Blocking constraints**: Anti-patterns or methodological failures encountered during this session that a resuming agent MUST be aware of before proceeding. Only include items discovered through actual failure — not warnings or predictions. Assign each constraint a `severity`:
    - `blocking` — The resuming agent MUST demonstrate understanding before proceeding. The discuss-phase and execute-phase workflows will enforce a mandatory understanding check.
    - `advisory` — Important context but does not gate resumption.
 
@@ -93,6 +94,9 @@ timestamp=$(gsd_run query current-timestamp full --raw)
   "blockers": [
     {"description": "{blocker}", "type": "technical|human_action|external", "workaround": "{if any}"}
   ],
+  "async_jobs": [
+    {"manifest": ".planning/async-jobs/{job}.json", "job_id": "{id}", "backend": "{backend}", "status": "running", "submit_command": "{cmd}", "submitted_at": "{iso8601}", "expected_artifacts": ["..."], "verification_command": "{cmd}", "resume_command": "{cmd}"}
+  ],
   "human_actions_pending": [
     {"action": "{what needs to be done}", "context": "{why}", "blocking": true}
   ],
@@ -104,6 +108,8 @@ timestamp=$(gsd_run query current-timestamp full --raw)
   "context_notes": "{mental state, approach, what you were thinking}"
 }
 ```
+
+Any recorded `async_jobs` entries are the primary resume context on the next session — check them first before treating a PLAN-without-SUMMARY as incomplete work.
 </step>
 
 <step name="write">

package/gsd-core/workflows/plan-phase.md

@@ -892,6 +892,7 @@ Output consumed by /gsd:execute-phase. Plans need:
 - Verification criteria
 - must_haves for goal-backward verification
 - If the SPEC has an `## Edge Coverage` section, lift every `covered` edge's acceptance criterion into `must_haves.truths`, and every `backstop` edge into `must_haves.truths` as a non-inferable check (note it needs a held-out/property-based test). `unresolved` edges are explicit assumptions — surface them in the plan, do not silently drop them.
+- If the SPEC has a `## Prohibitions` section, lift every resolved prohibition into the `must_haves.prohibitions:` sibling block (NOT `truths` — ADR-550 D3) carrying `statement` + `status` + `verification`; unresolved prohibitions are explicit assumptions — surface them in the plan, do not silently drop them. A prohibition is a must-NOT (negative) check that belongs in its own `must_haves.prohibitions` block. Never place a must-NOT under `must_haves.truths` — that block keeps positive-observable semantics only.
 - **"Artifacts this phase produces" section (MANDATORY)** — list every symbol this phase creates: decorators, classes, functions, CLI flags, struct/dataclass fields, new file paths. The plan-review-convergence source-grounding pass reads this section to exclude newly-created symbols from drift verification; omitting it causes new symbols to be flagged for acknowledgement.
 </downstream_consumer>
 
@@ -938,6 +939,7 @@ Every task MUST include these fields — they are NOT optional:
 - [ ] must_haves derived from phase goal
 - [ ] Every PLAN.md includes an "Artifacts this phase produces" section listing symbols created by this phase (decorators, classes, functions, CLI flags, struct/dataclass fields, new file paths)
 - [ ] Every SPEC ## Edge Coverage covered/backstop edge is represented in a plan's must_haves (no silent drops)
+- [ ] Every SPEC ## Prohibitions resolved item is represented in a plan's must_haves.prohibitions (no silent drops)
 </quality_gate>
 ```
 

package/gsd-core/workflows/plan-review-convergence.md

@@ -185,13 +185,23 @@ Run this pass unless `plan_review.source_grounding` is `false`. It verifies ever
 
 1. **Enumerate cited symbols.** List every referenced symbol by kind, quoting the plan line for each (coverage must be auditable): decorators (`@name`), classes/methods (`Class.method`), functions (`module.function`), CLI flags (`--name`), file paths, dataclass/struct fields.
 2. **Exclude new artifacts.** Do NOT verify symbols the plan declares under its "Artifacts this phase produces" section — those are created by this phase, not references to existing code.
-3. **Resolve each remaining symbol** using the adapter named by `plan_review.source_grounding_authority` (default `grep`):
+3. **Resolve each remaining symbol** using the effective authority adapter (resolved deterministically — see step 4a):
    - `grep` — ripgrep / Read the source; confirm the name appears as a real declaration.
    - `intel` — consult `.planning/intel/API-SURFACE.md` / `api-map.json` (only when `intel.enabled`).
    Record one verdict per symbol: **VERIFIED** (quote `file:line`), **MISSING** (adapter can check this language/kind and the symbol is absent), **AMBIGUOUS** (multiple candidates), or **UNCHECKABLE** (adapter cannot analyze this language/kind — e.g. non-JS under `intel`, or any signature under `grep`). Never treat UNCHECKABLE as verified or missing.
-4. **Severity & gating:**
-   - **MISSING** at authority `grep`/`intel` → `needs-acknowledgement`: the plan proceeds only if the author confirms the symbol is genuinely new or dynamically resolved, and that acknowledgement is recorded. A hard block is reserved for higher-authority adapters (LSP/SCIP) that can prove absence.
-   - **AMBIGUOUS** → MEDIUM. **UNCHECKABLE** → INFO.
+4a. **Resolve effective authority** (deterministic — replaces manual `intel.enabled` reasoning):
+   ```bash
+   EFFECTIVE_AUTHORITY=$(gsd_run drift-guard authority --raw)
+   ```
+4. **Severity & gating** — classify each symbol's verdict using the seam (do not apply the table manually):
+   ```bash
+   # For each symbol, e.g.:
+   RESULT=$(gsd_run drift-guard severity --status <verdict> --authority "$EFFECTIVE_AUTHORITY")
+   # $RESULT is JSON: {"severity":"…","hardBlock":true|false}
+   ```
+   - `hardBlock: true` (HIGH at authority `lsp`/`scip`) — stops the review cycle immediately; do not proceed until the plan author resolves the missing symbol.
+   - `hardBlock: false`, severity `needs-acknowledgement` — plan proceeds only if the author confirms the symbol is genuinely new or dynamically resolved, and that acknowledgement is recorded.
+   - `AMBIGUOUS` → MEDIUM. `UNCHECKABLE` → INFO.
    - Signature mismatches cannot be asserted under `grep`/`intel`; report the signature as UNCHECKABLE.
 5. **Coverage block.** Append a "Verification coverage" section to `REVIEWS.md` listing every UNCHECKABLE/skipped symbol and why — a clean review must never silently mean "nothing was checked."