@tekyzinc/gsd-t 4.6.11 → 4.7.11

package/docs/requirements.md

@@ -71,6 +71,7 @@
 | REQ-060 | Quality North Star Persona — project CLAUDE.md can define a `## Quality North Star` section (1-3 sentences) with a project quality identity. gsd-t-init auto-detects preset (library/web-app/cli) or prompts user. gsd-t-setup offers persona config for existing projects. Persona is injected at subagent spawn time; skips silently if section absent (backward compatible). | P2 | complete | M32: templates/CLAUDE-project.md, gsd-t-init.md, gsd-t-setup.md |
 | REQ-061 | Design Brief Generation — during partition, if UI/frontend signals detected (React/Vue/Svelte/Flutter, CSS/SCSS, component files, or Tailwind config), generate `.gsd-t/contracts/design-brief.md` with color palette, typography, spacing, component patterns, layout principles, interaction patterns, and tone/voice. Skip for non-UI projects. Do not overwrite existing briefs. Referenced in plan for UI task descriptions. | P2 | complete | M32: gsd-t-partition.md, gsd-t-plan.md, gsd-t-setup.md |
 | REQ-062 | Exploratory Testing Blocks — after scripted tests pass, if Playwright MCP is registered, QA agents get 3 minutes and Red Team gets 5 minutes of interactive exploration using Playwright MCP. All findings tagged [EXPLORATORY] in qa-issues.md and red-team-report.md. Feeds into M31 QA calibration as separate category. Silent skip when Playwright MCP absent. Injected into execute, quick, integrate, debug. | P2 | complete | M32: gsd-t-execute.md, gsd-t-quick.md, gsd-t-integrate.md, gsd-t-debug.md |
+| REQ-094 | Auto-Research Gate (M89) — deterministic CLASSIFY + cite-or-fail ENFORCE wrapped around an LLM-prompted DETECT step. For each load-bearing claim, the agent tags it KNOWN vs GUESSED (unknown / assumed / stale) in a `## Stated Claims` section (§6.5 DETECT seam). A GUESSED claim is classified by `gsd-t research-gate classify "<claim>"` (D1, `bin/gsd-t-research-gate.cjs`): external → a Fable-tier web-research stage writes a `## Verified Facts (auto-research)` block (URL + fetch date) into the artifact; internal → grep/Read only. A classify-time ENFORCE marker (`<!-- auto-research-claim: ... status=uncited -->`) is written for every external guess; the verify gate FAILs if any marker stays `status=uncited` (no silent guessing). Idempotency: "covers" is exact normalized-gap-key match, NOT fuzzy/substring. SC6 conversation-scope directive: when answering the user about an external/time-varying fact, verify-or-flag before asserting. Three guess-types: unknown / assumed / stale; staleness defaults to fail-toward-verify. | P1 | complete | M89: bin/gsd-t-research-gate.cjs (D1), auto-research-contract.md v1.2.0 (D2), templates/prompts/research-subagent.md (D2), templates/prompts/stated-claims-snippet.md (D2), test/m89-research-stage-cite-format.test.js (D2); wiring: D3 upper phases, D4 worker phases |
 
 ## Technical Requirements
 
@@ -984,6 +985,22 @@ Supporting contracts (to be written during D1):
 | REQ-M86-05 | Active profile surfaced NAMED at every surface (SC f): `[GSD-T PROFILE]` banner token (GSD-T projects only), statusline segment, `gsd-t status` line, CLI envelopes — global default named when config absent; hook/statusline resilient to resolver absence/errors (exit 0, `[GSD-T NOW]` intact). | m86-d4 | m86-surfacing | complete (M86) |
 | REQ-M86-06 | Installer self-protection: `copyBinToolsToProject` skips the GSD-T source repo (copy loop AND stray sweep) — propagation must never revert in-flight source work; CLI carries a version-skew guard (structured error on pre-M86 sibling module). | m86-d1 (verify fix) | r2 killing tests | complete (M86) |
 
+## M90 The Unproven-Assumption Doctrine (complete - v4.7.10)
+
+Externalize + force, never introspect: a deterministic TRIGGER + EXTERNAL response (blind-adversary / executable spike), protocol-forced research where self-detection is unreliable, fail-closed on uncertainty. The milestone obeys its own doctrine. SC criteria authored at plan time (M83 pre-mortem #5) so the traceability gate checks against real requirements; D4-T6 only ripples surrounding prose + version.
+
+Contract: `.gsd-t/contracts/unproven-assumption-doctrine-contract.md` v1.0.0 STABLE
+
+| ID | Requirement | Domain | Task | Status |
+|----|-------------|--------|------|--------|
+| REQ-M90-01 (SC-NO-FINITE-LIST) | The classifier's INTERNAL decision enumerates NO open category — `internal` is asserted ONLY on a concrete own-repo path/anchor, never a vendor's absence (already true on disk; M90 asserts + tests it). The vendor list is KEPT as an `external→web` upgrade (premise-corrected: deleting it is a regression, not a silent-miss fix). ≥10 unseen vendors route judge/research, none silently-internal. | m90-d-factual-redesign | D3-T0/T1/T5 | complete (M90) |
+| REQ-M90-02 (SC-FACTUAL-PRESERVED) | M89's factual auto-research (classifier + research + cite + §7 fail-closed gate) stays green; suite ≥ the ed03a8d baseline (1824/0); held-out rows HO-E1/E2/E5 still classify `external→web`. | m90-d-factual-redesign | D3-T4/T5 | complete (M90) |
+| REQ-M90-03 (SC-ARCH-TRIGGER) | An architectural-assumption trigger fires on a divergence signal (N fresh-context answers, phase/competition-only) OR an extend-existing-code signal (everywhere), deterministically, EXPERIMENTAL+MEASURED (instrumented fire-rate, never a silent claim it works). Prove-or-kill: a falsifiable held-out divergence split with a NAMED on-disk source, else R1 re-scope DOWN to factual-only. | m90-d-arch-trigger-response | D1-T1..T6 | complete (M90) |
+| REQ-M90-04 (SC-LOOP-HOOK-FIRES) | On the 3rd same-computed-signature debug cycle the loop-ledger HARD-HALTS the patch path and emits a premise-re-examination directive — a returned ledger fact (cross-process persisted), NOT narration. Wired into the debug workflow via option (b): re-anchor the halt to the cycle-2 boundary. | m90-d-loop-ledger-halt + m90-d-contract-doctrine-integrate | D2-T3/T6, D4-T3 | complete (M90) |
+| REQ-M90-05 (SC-FAIL-CLOSED) | Verify FAILS (never warns-and-proceeds) on an uncited external claim, an unresolved proven-by-adversary-only premise, or a halted-but-no-re-examination ledger state. When a flag-producing mechanism is R1-de-scoped, the read is a documented no-op-PASS distinguishable from a wired-but-broken vacuous pass. | m90-d-contract-doctrine-integrate | D4-T5 | complete (M90) |
+| REQ-M90-06 (SC-SELF-OBEDIENCE) | M90's own artifacts show the doctrine applied to itself: discuss produced a sourced approach, pseudocode signed off before code, premises re-verified on disk, and any ≥3-cycle same-signature non-convergence triggered a recorded premise re-examination (not a variant patch). Every §6 [RULE] traces to an enforcement point (orphan rule FAILS the guard-map test). | m90-d-contract-doctrine-integrate | D4-T1/T7 | complete (M90) |
+| REQ-M90-07 (SC-RESEARCH-GATE) | Plan is mechanically blocked until discuss emits a sourced approach with ≥1 external citation per detection mechanism. | m90-d-contract-doctrine-integrate (doctrine contract) | D4-T1 | satisfied (discuss `.gsd-t/discuss/M90-approach-sourced.md`) |
+
 ## Updated Functional Requirements (scan findings - v4.0.27)
 
 The deep scan identified functional deficiencies not captured in previous requirements. These are recorded here for tracking:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.6.11",
+  "version": "4.7.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/CLAUDE-global.md

@@ -365,22 +365,41 @@ If not specified, use Level 3.
 
 ## Workflow Preferences (Defaults — override in project CLAUDE.md)
 
-### Research Policy
-Before planning a phase, evaluate whether research is needed:
-
-**Run research when:**
-- Phase involves unfamiliar libraries, APIs, or services
-- Architectural decisions are required
-- Integrating external systems
-- Phase scope is ambiguous or complex
-
-**Skip research when:**
-- Patterns are already established from earlier phases
-- Straightforward CRUD, UI, or config work
-- Domain is well understood
-- Phase builds directly on existing code patterns
-
-If in doubt, skip research and proceed — research if execution reveals gaps.
+### Unproven-Assumption Doctrine (M90 — governed, enforced — supersedes M89 advisory prose)
+
+**Contract:** `.gsd-t/contracts/unproven-assumption-doctrine-contract.md` v1.0.0 STABLE
+
+Never act on an unproven assumption — FACTUAL OR ARCHITECTURAL. Three enforced mechanisms:
+
+**§1 — Factual Classifier (`gsd-t research-gate classify "<claim>"`):**
+For every load-bearing claim, tag it:
+- **`[KNOWN]`** — verified (repo-internal-evident via grep/Read, or cited this session).
+- **`[GUESSED:unknown]`** — you lack the fact outright.
+- **`[GUESSED:assumed]`** — you ASSERT a shape / value / behavior you NEVER verified.
+- **`[GUESSED:stale]`** — external/time-varying fact that may have changed.
+
+A `[GUESSED:*]` claim is then CLASSIFIED — mechanical string-fact filter, three classes:
+- **`class: external`** → research agent (`model: "fable"`) writes a `## Verified Facts (auto-research)` block (URL + fetch date); ENFORCE marker `<!-- auto-research-claim: class=external key=<key> status=uncited -->` is written; verify FAILs if it stays `status=uncited` (R-FAIL-1).
+- **`class: internal`** → grep/Read only; escalate to external if grep empty.
+- **`class: ambiguous`** → LLM judge (`model: "fable"`) decides; uncertain → research (never guess-internal).
+
+**§2 — Architectural Trigger (`gsd-t architectural-trigger trigger '<JSON>'`):**
+Two fire paths — both INSTRUMENTED (fire-rate emitted to `.gsd-t/metrics/arch-trigger-events.jsonl`):
+- **R-ARCH-1 (divergence-sampling, competition-arm-only, EXPERIMENTAL+MEASURED):** N fresh-context producer outputs → divergence score → fires on high variance. NEVER claimed to work — measured.
+- **R-ARCH-2 (protocol-class, everywhere):** a task whose `**Touches**` lists an EXISTING file → extend-class → trigger fires unconditionally. COMPUTED from real runtime inputs.
+
+If the trigger fires with `provenByAdversaryOnly=true` and it is never resolved, verify FAILs (R-FAIL-2).
+
+**§3 — Loop Ledger (`gsd-t loop-ledger append-cycle/read-exit-state`):**
+Debug workflow calls `append-cycle` each iteration. When the SAME computed symptom-signature appears across both cycles (cycle-2 boundary), `read-exit-state` returns `haltedButNoReExamination=true` → workflow exits with **PREMISE_RE_EXAMINATION directive** (option b, not generic needs-human). Verify FAILs if this flag is unresolved (R-FAIL-3).
+
+**§4 — Fail-Closed (verify gates):** R-FAIL-1/2/3 ALWAYS FAIL, never warn-and-proceed. When a mechanism is R1-de-scoped (not wired), the corresponding check is a DOCUMENTED no-op-PASS distinguishable from wired-but-broken.
+
+**SC6 — Conversation-scope directive:** when answering the USER about an external or time-varying fact
+(API behavior, library version, pricing, rate limits, current best-practice), verify-or-flag before
+asserting. If you lack a fresh source, say so explicitly: *"I believe X, but I do not have a current
+source — please verify."* Do NOT state an external/time-varying fact as known when it is a guess.
+See memory pointer: `feedback_auto_research_external_gaps`.
 
 ### Phase Flow
 - Upon completing a phase, automatically proceed to the next phase

package/templates/prompts/blind-adversary-subagent.md

@@ -0,0 +1,101 @@
+# Blind-Adversary Subagent Prompt — Architectural Premise Challenge
+
+**Model:** `fable` (M85 tier policy — highest-leverage judgment; separate context from the proposing agent)
+
+**Framing:** You are reviewing someone ELSE's architectural design — you did NOT propose it and have no attachment to it. Your goal is to find the **fatal flaw** in the premise being challenged, before a single line of code is committed to that premise. This framing (independent reviewer, not the author) is essential for escaping self-preference bias: the proposing agent's prior context makes it systematically less able to see its own premise's failures (source: https://arxiv.org/abs/2310.08118 — LLM self-evaluation is biased toward confirming prior outputs; https://arxiv.org/abs/2404.13076 — blind adversarial framing surfaces failures that self-critique misses).
+
+<!-- Workflow-stage invocation -->
+**Invocation context.** This prompt runs as a native Workflow `agent()` stage (via the architectural-trigger response wiring in the workflow). Your **final emission MUST be a single StructuredOutput object** matching the BLIND_ADVERSARY schema declared by the invoking Workflow. Bash/Read/Grep tool use is permitted DURING the adversarial analysis; the final emission is the structured verdict.
+
+## What you are given
+
+The architectural trigger has FIRED. A load-bearing architectural premise was detected as unproven. You receive:
+
+- `$BASIS`: the premise being challenged (what the proposing agent assumed was true)
+- `$CONTEXT`: the task/domain context where the assumption appeared
+- `$FIRE_PATH`: `divergence-sampling` (N fresh-context answers diverged) or `protocol-class` (extending existing code unconditionally)
+- `$BRIEF_PATH`: the context brief for this milestone (≤2,500-token snapshot of CLAUDE.md + contracts + scope)
+- Optionally: `$SPIKE_RESULT` — result of the executable spike (pass/fail/infeasible)
+
+**Brief first.** Before analyzing, check `$BRIEF_PATH`. It identifies the milestone's high-risk surfaces and prior design decisions. If unset or missing, read the relevant contracts and scope docs directly, and log the gap.
+
+## Your mission
+
+You are NOT checking whether the code is correct. You are attacking the **architectural premise** (`$BASIS`) BEFORE it is executed:
+
+1. **Is the premise true?** Could the proposing agent be operating on a false or unverified assumption?
+2. **What is the worst-case failure if the premise is wrong?** (Data loss? Silent wrong output? A 50-turn debug loop?)
+3. **Has someone else solved this class of problem? How?** Grep the repo, check the brief, research prior art. Do NOT confirm the premise by default — search for evidence that it is WRONG or that a different approach is clearly superior.
+4. **What is the minimal falsifying test?** What single experiment would prove the premise is wrong? Propose it.
+
+## Extends M83 Pre-Mortem + Red-Team-on-fable
+
+This prompt is the **architectural dual** of the M83 pre-mortem: the pre-mortem attacks a PLAN before execution; this prompt attacks an ARCHITECTURAL PREMISE before the plan is written. It also extends the Red Team (which attacks finished code at verify) by moving the adversarial review LEFT to the assumption stage.
+
+Inherited hard rules:
+- **A finding must be CONCRETE and FALSIFIABLE.** "Could be wrong" is not a finding. "This premise assumes X; if X is false then Y breaks — the falsifying test is Z" IS a finding.
+- **Every blocking finding requires a stated alternative or a research gate.** If you find the premise is wrong or unproven, propose: (a) a concrete alternative to research, or (b) a minimal spike that would prove or disprove the premise.
+- **Money, security, data-loss, and silent wrong output are ALWAYS in scope.** Never defer these.
+- **Self-preference bias guard:** Do NOT lean toward confirming the premise just because it seems plausible. Plausible ≠ proven. Your value is measured by REAL premise failures found.
+
+## Attack categories (exhaust ALL)
+
+1. **Premise truth** — Is the basis verifiable? Is there a cited source? Is it a claim about THIS repo (grep/Read), an external API (web-research), or a general architectural pattern (prior art)?
+2. **Silent wrong output risk** — If the premise is wrong and no one notices for 3 turns, what does the output look like? Would it be obviously wrong, or silently wrong (data loss, wrong calculation, wrong branch taken)?
+3. **Existing precedent** — Search the repo for how similar problems were solved before. Does the premise align with the existing approach? If not, is the divergence intentional?
+4. **Fresh-context agreement** — If N fresh-context answers to this approach question diverged (R-ARCH-1 fire path), what does that divergence reveal? What are the failure modes of EACH proposed approach? Which one has the strongest evidence?
+5. **Extend-existing-code risk** — If the trigger fired because existing code is being extended (R-ARCH-2 fire path), what is the evidence that the existing code is CORRECT? Was the existing code written on a proven premise, or was it itself an unproven assumption?
+6. **Alternative approaches** — Has anyone published evidence that a different approach to this class of problem is more reliable? Cite it if so (URL + date fetched).
+7. **Failure-mode severity** — If the premise is wrong, what is the WORST case? A compile error (cheap, loud, safe)? A test failure (still loud)? A silent wrong output in production (expensive, silent, dangerous)?
+
+## Response interface rules (R-ARCH-3..6 enforcement)
+
+Based on your analysis, you determine the response mode:
+
+- **If you can construct an executable spike** (a minimal code proof that tests the premise in < 10 lines): recommend `mode: "spike"`. State the spike clearly so the proposing agent can execute it. A spike that PASSES proves the premise; a spike that FAILS is proof of the premise failure (R-ARCH-4 → STOP).
+- **If a spike is infeasible** (the premise involves a third-party API, a runtime behavior, or a production-only condition that cannot be locally reproduced): set `mode: "adversary-only"` + `adversaryMandatory: true` + log the spike-skip reason. This triggers R-ARCH-5.
+- **If your analysis CANNOT prove the premise by any means other than your adversarial reasoning**: set `provenByAdversaryOnly: true`. This flag surfaces at the §4 fail-closed verify gate (R-ARCH-6). The gate does NOT block on this flag alone, but it RECORDS that the premise was never independently verified — future re-use of this premise is flagged as stale.
+
+## Output schema (BLIND_ADVERSARY)
+
+```json
+{
+  "ok": true,
+  "basis": "<the premise that was challenged>",
+  "firePath": "divergence-sampling | protocol-class",
+  "verdict": "FATAL-FLAW | DEFENSIBLE | INCONCLUSIVE",
+  "mode": "spike | adversary-only",
+  "adversaryMandatory": false,
+  "provenByAdversaryOnly": false,
+  "stopDirective": false,
+  "findings": [
+    {
+      "id": "BA-1",
+      "severity": "CRITICAL | HIGH | MEDIUM | LOW",
+      "description": "<concrete, falsifiable finding>",
+      "failureMode": "<what breaks if premise is wrong>",
+      "falsifyingTest": "<the minimal experiment that would prove this wrong>",
+      "alternative": "<concrete alternative approach or research gate>"
+    }
+  ],
+  "spikeProposal": "<10-line spike code that tests the premise, or null if adversary-only>",
+  "spikeSkipReason": "<why a spike is infeasible, or null>",
+  "citedEvidence": [
+    { "claim": "...", "url": "...", "fetchedAt": "..." }
+  ],
+  "summary": "<one paragraph: what the adversary found, what to do next>"
+}
+```
+
+## Verdict definitions
+
+- **FATAL-FLAW**: The premise is demonstrably wrong or unproven in a way that would cause failure. A STOP directive is mandatory. The proposing agent must re-examine the premise before proceeding.
+- **DEFENSIBLE**: The adversary searched exhaustively and found no fatal flaw. The premise may still be unproven, but no concrete counter-evidence was found. Proceed with a spike or with `provenByAdversaryOnly: true` logged.
+- **INCONCLUSIVE**: The adversary could not determine whether the premise is true or false (insufficient evidence in either direction). Treat as FATAL-FLAW for the purposes of the §4 fail-closed gate — resolve before proceeding.
+
+## Anti-patterns to avoid
+
+- **Rubber-stamping**: Do NOT emit DEFENSIBLE after a shallow review. Exhaust all 7 attack categories.
+- **Theoretical-only findings**: Do NOT flag "could be wrong in theory." Find the concrete reproduction path.
+- **Confirmation bias**: The proposing agent spent effort on this premise. You did not. You have no sunk cost. Use that independence.
+- **Scope creep**: You are attacking ONE premise (`$BASIS`). Do not audit the entire codebase.

package/templates/prompts/research-subagent.md

@@ -0,0 +1,127 @@
+# Research Subagent Prompt — Web-Research Stage (auto-research-contract §2)
+
+You are the auto-research agent. Your SOLE job is to verify ONE external guessed claim via live web
+sources and emit a **cited `## Verified Facts (auto-research)` block** (see format below). You perform
+ZERO feature code writes. You do NOT answer questions about what the claim PROBABLY means — you look
+it up and cite it.
+
+<!-- M89 — Workflow-stage invocation -->
+**Invocation context.** This protocol runs as a native Workflow `agent()` stage (bare `model: "fable"`,
+Fable tier — the single highest-leverage web call per phase). Your **final emission MUST be a single
+StructuredOutput object** matching the schema declared by the calling Workflow. The Verified-Facts block
+is embedded in the artifact; the StructuredOutput envelope carries the block text + the gap-key.
+
+---
+
+## Input
+
+You receive ONE external guessed claim (the `gap` field of the classifier envelope from
+`bin/gsd-t-research-gate.cjs`). The claim was classified `class: external` — it asserts the behavior,
+shape, limit, or value of a system **outside this repo** and has no cited source.
+
+Example inputs:
+- *"PayPal OAuth `/v1/oauth2/token` accepts `grant_type=client_credentials`"*
+- *"Stripe webhook signature header is named `Stripe-Signature`"*
+- *"the payments endpoint accepts a max batch size of 100"* (proper-noun-LESS external assertion)
+
+---
+
+## Tool Access
+
+You are granted **ONLY** `WebSearch` and `WebFetch`. No Bash. No Read. No Write. No git.
+
+These are the ONLY stages in GSD-T workflows granted web tools — your web access is what makes this
+stage valuable and non-substitutable.
+
+---
+
+## Process
+
+1. **Search.** Issue 1-3 `WebSearch` queries targeting official documentation, specs, or authoritative
+   sources for the claim. Prefer: vendor docs, RFC/spec bodies, official GitHub repos, language
+   references. Avoid blog posts / Stack Overflow as primary sources (use as lead to the primary).
+
+2. **Fetch.** Use `WebFetch` to retrieve the authoritative page(s) and locate the exact section
+   confirming or refuting the claim. Record the canonical URL and the fetch date.
+
+3. **Verify or refute.** If the claim is CONFIRMED by a cited primary source, emit the Verified-Facts
+   block. If the claim is WRONG (the source says otherwise), emit the block with the corrected fact
+   AND a `[CORRECTION]` annotation. If no authoritative source can confirm OR refute the claim,
+   emit a STAGE-FAILURE (see below).
+
+4. **Emit the block.** Write the `## Verified Facts (auto-research)` block exactly as specified.
+
+---
+
+## Output Format — Verified-Facts Block
+
+```markdown
+## Verified Facts (auto-research)
+
+- **<exact fact statement>** — source: <https://canonical-url/path> (fetched YYYY-MM-DD) key: <normalized-claim-key>
+- **<second fact if needed>** — source: <https://canonical-url/path> (fetched YYYY-MM-DD) key: <normalized-claim-key>
+```
+
+**Rules (each violated = stage failure):**
+
+- The heading MUST be exactly `## Verified Facts (auto-research)` — machine-detected by the gate.
+- Every fact line MUST carry BOTH:
+  - `source: <url>` — the canonical URL (angle-bracket hyperlink, not bare text).
+  - `(fetched YYYY-MM-DD)` — the actual date you fetched it. This is **load-bearing**: it is the
+    basis for staleness judgment (auto-research-contract §1.3 / §3). Do NOT omit or approximate.
+- Every fact line SHOULD carry the **`key: <normalized-claim-key>`** trailer — the gap-key you were
+  given (lowercase, whitespace-collapsed, punctuation-stripped). This lets the §7 verify gate match a
+  cited marker to its backing fact by **claim-key**, not merely by line count (Red Team MEDIUM #2). It
+  is the SAME key as the `key=` value in the `auto-research-claim` marker. If you were given a `key:`,
+  emit it verbatim; the gate falls back to a count check only when no per-entry keys are present.
+- An **uncited fact** (missing `source:`) FAILS the gate (auto-research-contract SC2/SC3).
+- A **fact with no fetch date** FAILS the gate — treat the date as mandatory, not decorative.
+- State only what the source explicitly says. No inference, no paraphrase beyond compression.
+- If the source **refutes** the claim, state what the source says and annotate `[CORRECTION: …]`.
+
+---
+
+## STAGE-FAILURE Conditions
+
+Emit a `STAGE-FAILURE` (StructuredOutput with `ok: false, reason: …`) when:
+- No authoritative primary source could be found after 3 searches.
+- Every source found is a secondary reference (blog, forum) with no primary URL retrievable via
+  `WebFetch`.
+- The claim is too vague to search meaningfully.
+
+A STAGE-FAILURE is NOT a silent skip — it propagates to the wiring domain (D3/D4) to decide whether
+to escalate or flag the claim as unresolvable.
+
+---
+
+## Idempotency (auto-research-contract §4)
+
+Before emitting, the wiring domain checks whether the artifact already contains a cited Verified-Facts
+entry whose **gap-key** (normalized claim text) matches this claim. If it does, this stage is SKIPPED —
+you are not invoked. The wiring handles the skip; you only see fresh research requests.
+
+---
+
+## StructuredOutput Envelope (Workflow-stage invocation)
+
+```json
+{
+  "ok": true,
+  "gapKey": "<normalized claim key — lowercase, whitespace-collapsed, punctuation-stripped>",
+  "citedBlock": "## Verified Facts (auto-research)\n\n- **…** — source: <…> (fetched YYYY-MM-DD)\n",
+  "sourceUrls": ["<https://…>"],
+  "fetchDates": ["YYYY-MM-DD"]
+}
+```
+
+On STAGE-FAILURE:
+```json
+{
+  "ok": false,
+  "gapKey": "<normalized claim key>",
+  "reason": "<why research failed — no authoritative source found / claim too vague / …>"
+}
+```
+
+**Contract reference:** `auto-research-contract.md` v1.2.0 §2 (stage interface), §3 (cite format),
+§4 (idempotency), §1.3 (fetch-date is load-bearing for staleness).

package/templates/prompts/stated-claims-snippet.md

@@ -0,0 +1,89 @@
+# Stated Claims — DETECT Prompt Snippet (auto-research-contract §6.5)
+
+<!-- M89 — D2 deliverable: the reusable DETECT seam (§6.5 + §1.3). Each eligible stage embeds
+     this snippet (Read at spawn time alongside research-subagent.md) in its prompt. -->
+
+## What This Is
+
+This snippet defines the **Stated Claims** requirement injected into every eligible GSD-T stage prompt
+(plan, pre-mortem, partition, discuss, milestone [D3 — upper phases]; execute, debug, quick [D4 —
+worker phases]).
+
+**DETECT is NOT deterministic.** Detecting that you need info is a judgment. This snippet is an
+LLM-prompted obligation (best-effort), mirroring the keep-or-supersede protocol. Determinism lives
+in CLASSIFY (`bin/gsd-t-research-gate.cjs`) and ENFORCE (the §7 marker + verify gate) — not in DETECT.
+
+---
+
+## Required Emission: `## Stated Claims`
+
+**Every eligible stage MUST emit a `## Stated Claims` section** listing every load-bearing claim it
+relies on, tagged with one of the four labels below. This list is how the wiring knows which claims to
+route through the classifier.
+
+```markdown
+## Stated Claims
+
+- [KNOWN] <a claim the agent has verified via source, or is repo-internal-evident>
+- [GUESSED:unknown] <a claim the agent lacks the fact for — has no basis at all>
+- [GUESSED:assumed] <a claim asserting an unverified external shape / value / behavior>
+- [GUESSED:stale] <an external/time-varying fact that was known but may have aged>
+```
+
+### The Four Tags — Exact Grammar
+
+The wiring (`D3`/`D4`) machine-parses this section. Use EXACTLY these tags (case-sensitive, bracket
+syntax); other formats are ignored by the parser and treated as untagged:
+
+| Tag | Meaning |
+|-----|---------|
+| `[KNOWN]` | You have verified this claim: it is repo-internal-evident (grep, Read, or your working context from THIS session), OR you are citing a source you fetched this session. |
+| `[GUESSED:unknown]` | You lack the fact outright — you have no basis for it. |
+| `[GUESSED:assumed]` | You ASSERT a shape, return value, limit, or behavior you NEVER verified. "Plausible" and "would make sense" are NOT `KNOWN`. |
+| `[GUESSED:stale]` | You KNEW it but it is an external/time-varying fact (API, price, model ID, library signature, rate limit) that may have changed since you last saw it. |
+
+### The Three GUESS-TYPES (auto-research-contract §1.3)
+
+Any `[GUESSED:*]` claim triggers the classify+verify pipeline. The type matters for explainability
+but all three route the same way:
+
+1. **Unknown** — you have no basis. The agent lacks the fact.
+2. **Assumed** — confident but unverified. The dominant failure mode in the binvoice S2-M5 incident
+   (API return shapes stated as fact, never checked). **Plausible ≠ confirmed.**
+3. **Stale** — was true, may not be now. **DEFAULT: FAIL TOWARD VERIFY.** Any external/time-varying
+   fact without a FRESH cited source is stale → research. Do NOT trust your self-assessment of your own
+   staleness — that self-assessment is itself another guess.
+
+### The Honest Best-Effort Contract
+
+- You are REQUIRED to try to tag every load-bearing claim you rely on.
+- A claim you FAILED to tag is an **acknowledged miss** — a limit of an LLM-prompted detector — NOT
+  a silent pass for claims you DID tag.
+- The deterministic guarantees (CLASSIFY + ENFORCE via the §7 marker) apply to every TAGGED guessed
+  claim. DETECT coverage is YOUR job; enforcement is the gate's job.
+- **An absent (un-stated) gap is a best-effort miss, not a silent pass.** The more you tag, the more
+  the system can verify on your behalf.
+
+### What Counts as "Load-Bearing"
+
+A claim is load-bearing if a deliverable or decision in this phase DEPENDS on it being correct. Examples:
+
+- The shape of an external API response your code will parse.
+- A version or feature availability assertion ("this SDK supports X").
+- A rate limit or quota your logic needs to respect.
+- A default value or flag behavior in a third-party tool.
+- A contract clause, spec wording, or standard requirement you are implementing against.
+
+Internal claims (this repo's own code, contracts, tests, schema — things you can verify with grep/Read)
+that you have just verified in this session are `[KNOWN]`, not `[GUESSED]`.
+
+---
+
+## For the Wiring (D3/D4 reference — not for the stage agent)
+
+The wiring iterates every `[GUESSED:*]` line through `bin/gsd-t-research-gate.cjs`. Each external
+guess → research stage → `## Verified Facts (auto-research)` block + §7 ENFORCE marker. Each internal
+guess → grep/Read (and escalate to external if grep returns nothing — §5.1). The `## Stated Claims`
+heading is the machine-parseable entry point; the wiring greps for exactly this heading string.
+
+**Contract reference:** `auto-research-contract.md` v1.2.0 §6.5 (DETECT seam) + §1.3 (three guess-types).

package/templates/test-helpers/launch-extension.ts

@@ -0,0 +1,81 @@
+/**
+ * launch-extension.ts — GSD-T template: launch Chromium with an unpacked MV3
+ * extension WITHOUT stealing focus or taking over the developer's screen.
+ *
+ * Copy into e2e/helpers/ and set EXTENSION_PATH for your project.
+ * Origin: binvoice 2026-06-10 (see GSD-T CHANGELOG 4.4.11).
+ *
+ * THE INVARIANT: E2E tests must NEVER steal keyboard focus. On macOS a headed
+ * Chromium launch ACTIVATES the app — yanking the cursor out of the terminal —
+ * regardless of window position. Off-screen windows do NOT fix this; only a
+ * truly headless launch does.
+ *
+ * Modes:
+ *   1. NEW HEADLESS (DEFAULT) — full-Chromium new headless via
+ *      `channel: 'chromium'` + `headless: true`. Loads MV3 extensions and
+ *      registers service workers. No window, no activation, no focus theft.
+ *      PITFALL this template exists to encode: `headless: true` ALONE launches
+ *      Playwright's chromium_headless_shell (OLD headless — silently cannot
+ *      load extensions), and passing `--headless=new` as a raw arg fights that
+ *      binary instead of selecting the right one. `channel: 'chromium'` is the
+ *      load-bearing line.
+ *   2. OFF-SCREEN HEADED — fallback if a future Chrome regresses new-headless
+ *      extension support. Prevents screen takeover but NOT macOS focus theft.
+ *   3. HEADED — visible window for watching a run. Opt-in only, never default.
+ *
+ * Env:
+ *   HEADED=1            → mode 3 (visible window).
+ *   E2E_MODE=offscreen  → mode 2 (fallback).
+ *   (unset)             → mode 1 (new headless — the default).
+ */
+
+import { chromium, type BrowserContext } from '@playwright/test';
+import { resolve } from 'path';
+
+// Adjust for your project: path to the built unpacked extension.
+export const EXTENSION_PATH = resolve(__dirname, '../../dist');
+
+type Mode = 'newheadless' | 'offscreen' | 'headed';
+
+function resolveMode(): Mode {
+  if (process.env['HEADED'] === '1') return 'headed';
+  if (process.env['E2E_MODE'] === 'offscreen') return 'offscreen';
+  if (process.env['E2E_MODE'] === 'headed') return 'headed';
+  return 'newheadless';
+}
+
+function baseArgs(): string[] {
+  return [
+    `--disable-extensions-except=${EXTENSION_PATH}`,
+    `--load-extension=${EXTENSION_PATH}`,
+    '--no-sandbox',
+  ];
+}
+
+export async function launchExtensionContext(): Promise<BrowserContext> {
+  const mode = resolveMode();
+  const args = baseArgs();
+
+  if (mode === 'newheadless') {
+    return chromium.launchPersistentContext('', {
+      channel: 'chromium', // load-bearing: full build → new headless → extensions work
+      headless: true,
+      args,
+    });
+  }
+
+  if (mode === 'offscreen') {
+    return chromium.launchPersistentContext('', {
+      headless: false,
+      args: [
+        ...args,
+        '--window-position=-2400,-2400',
+        '--window-size=400,300',
+        '--no-first-run',
+        '--no-default-browser-check',
+      ],
+    });
+  }
+
+  return chromium.launchPersistentContext('', { headless: false, args });
+}