* test(#3576): gate shipped reference citations on the canonical resolvable form Failing-first gate for #3576: a backticked bare references/<name>.md cite resolves from no install location (agents, workflows, and references all install where a bare relative references/ path is dead). The gate walks the runtime-loaded trees the issue prescribes, strips @~/ include tokens PER-TOKEN (a line-skip guard would miss a bare cite sharing a line with an include — the issue-named trap), pins the genuinely relative ../ href and canonical forms as non-offenders, and checks canonical cite targets exist. 43 offenders today across 19 files. * fix(#3576): repair all 43 dead references/ cites to the canonical resolvable form Every backticked bare references/<name>.md cite across the 19 shipped files rewritten to gsd-core/references/<name>.md — the form every required_reading block and @~/ include already uses, and the only form that resolves from any install location. All 20 cited targets verified to exist; the one genuinely relative href (plan-phase.md's ../references/mvp-concepts.md) is untouched (the repair is backtick-anchored). Growth acks: new fragment for the three first-time paths, #3206-pattern appends to the five fragments already naming the other grown files (two ack sources may never name the same path). execute-phase.md lands at 93,391/93,400 and gsd-executor.md at 49,150/49,152 — exactly the issue's projections; every repair fits. * fix(#3576): drop stale default.md growth ack (nested modes file is hash-attributed, not growth-ratcheted) Review finding: the emitted-attribution ratchet covers only top-level workflows/ + agents/ files; discuss-phase/modes/default.md's delta is source-attributed, so acknowledging its growth is a stale entry the differential lane fails on. * chore(#3576): add changeset fragment * chore(#3576): backfill changeset pr number --------- Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
@@ -2,7 +2,7 @@
|
||||
|
||||
Standard rules for keeping orchestrator context lean. Reference this in workflows that spawn subagents or read significant content.
|
||||
|
||||
See also: `references/universal-anti-patterns.md` for the complete set of universal rules.
|
||||
See also: `gsd-core/references/universal-anti-patterns.md` for the complete set of universal rules.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@ Exit WITHOUT writing any destination files. The gate must hold regardless of WAR
|
||||
|
||||
**If only WARNINGS and/or INFO (no blockers):**
|
||||
|
||||
Render the full report, then prompt for approval via the `approve-revise-abort` or `yes-no` pattern from `references/gate-prompts.md`. Respect text mode (see the workflow's own text-mode handling). If the user aborts, exit cleanly with a cancellation message.
|
||||
Render the full report, then prompt for approval via the `approve-revise-abort` or `yes-no` pattern from `gsd-core/references/gate-prompts.md`. Respect text mode (see the workflow's own text-mode handling). If the user aborts, exit cleanly with a cancellation message.
|
||||
|
||||
**If the report is empty (no entries in any bucket):**
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## When this gate fires
|
||||
|
||||
- `MVP_MODE` is `true` (resolved from CLI flag → ROADMAP `**Mode:**` field → config; see `references/planner-mvp-mode.md`).
|
||||
- `MVP_MODE` is `true` (resolved from CLI flag → ROADMAP `**Mode:**` field → config; see `gsd-core/references/planner-mvp-mode.md`).
|
||||
- `TDD_MODE` is `true` (resolved from `--tdd` flag → `workflow.tdd_mode` config).
|
||||
- The current task being executed has `tdd="true"` in its `<task>` frontmatter (set by the planner per Phase 1).
|
||||
- The task's `<behavior>` block lists at least one expected behavior.
|
||||
@@ -71,11 +71,11 @@ The `--force-mvp-gate` flag is documented but not introduced by this plan — it
|
||||
|
||||
## What this gate does NOT do
|
||||
|
||||
- It does not enforce REFACTOR commits. REFACTOR remains optional (per `references/tdd.md`).
|
||||
- It does not enforce REFACTOR commits. REFACTOR remains optional (per `gsd-core/references/tdd.md`).
|
||||
- It does not check test quality (the test could be trivially passing). That's the planner's job.
|
||||
- It does not run tests. The executor only inspects git log + file system. Running tests is the implementation step's job.
|
||||
- It does not gate config-only or doc-only tasks (see "behavior-adding task" definition).
|
||||
|
||||
## Compatibility with existing TDD discipline
|
||||
|
||||
This gate is additive to `references/tdd.md`. Tasks not under MVP+TDD continue to use the existing advisory TDD discipline (RED/GREEN/REFACTOR commits with end-of-phase review checkpoint). Only the runtime gate and the blocking escalation are new.
|
||||
This gate is additive to `gsd-core/references/tdd.md`. Tasks not under MVP+TDD continue to use the existing advisory TDD discipline (RED/GREEN/REFACTOR commits with end-of-phase review checkpoint). Only the runtime gate and the blocking escalation are new.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
0. **Context exhaustion guard — `context_guard` (BEFORE spawning, #1452):**
|
||||
|
||||
Before spawning any agents for this wave, self-assess context pressure using the
|
||||
degradation signals in `references/context-budget.md`. Signs of POOR tier (70%+):
|
||||
degradation signals in `gsd-core/references/context-budget.md`. Signs of POOR tier (70%+):
|
||||
increasing vagueness, skipped steps, silent partial completion.
|
||||
|
||||
Read `workflow.context_guard_mode` from `.planning/config.json` (default `warn`).
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Reusable prompt patterns for structured gate checks in workflows and agents.
|
||||
|
||||
**For checkpoint box format details, see `references/ui-brand.md`** -- checkpoint boxes use double-line border drawing with 62-character inner width.
|
||||
**For checkpoint box format details, see `gsd-core/references/ui-brand.md`** -- checkpoint boxes use double-line border drawing with 62-character inner width.
|
||||
|
||||
## Rules
|
||||
|
||||
|
||||
@@ -8,12 +8,12 @@ Canonical domain terms for the concepts named below live in [CONTEXT.md](../../C
|
||||
|
||||
| File | Purpose | Loaded by |
|
||||
|---|---|---|
|
||||
| `references/planner-mvp-mode.md` | **Rules.** Vertical-slice planning rules, slice ordering, Walking Skeleton constraints. | `gsd-planner` agent when `MVP_MODE=true` |
|
||||
| `references/skeleton-template.md` | **Template.** Shape of `SKELETON.md` for new-project Phase 1 under `--mvp`. | `gsd-planner` agent when the Walking Skeleton gate fires |
|
||||
| `references/user-story-template.md` | **Template.** Format and slot definitions for `As a / I want to / So that`. | `gsd-mvp-phase` workflow during interactive prompting; `gsd-planner` when emitting the `## Phase Goal` header |
|
||||
| `references/spidr-splitting.md` | **Splitting discipline.** Five-axis decomposition (Spike, Paths, Interfaces, Data, Rules) for stories too large for one phase. | `gsd-mvp-phase` workflow when the user story exceeds size threshold |
|
||||
| `references/execute-mvp-tdd.md` | **Gate.** MVP+TDD runtime gate semantics: when it fires, what it checks, halt-and-report protocol, end-of-phase blocking escalation, Behavior-Adding Task definition. | `gsd-executor` agent when `MVP_MODE=true && TDD_MODE=true` |
|
||||
| `references/verify-mvp-mode.md` | **UAT framing.** Three-section UAT structure (user-flow → technical → coverage), anti-patterns, `User Flow Coverage` section in VERIFICATION.md. | `gsd-verifier` agent when the phase under verification has `mode: mvp` |
|
||||
| `gsd-core/references/planner-mvp-mode.md` | **Rules.** Vertical-slice planning rules, slice ordering, Walking Skeleton constraints. | `gsd-planner` agent when `MVP_MODE=true` |
|
||||
| `gsd-core/references/skeleton-template.md` | **Template.** Shape of `SKELETON.md` for new-project Phase 1 under `--mvp`. | `gsd-planner` agent when the Walking Skeleton gate fires |
|
||||
| `gsd-core/references/user-story-template.md` | **Template.** Format and slot definitions for `As a / I want to / So that`. | `gsd-mvp-phase` workflow during interactive prompting; `gsd-planner` when emitting the `## Phase Goal` header |
|
||||
| `gsd-core/references/spidr-splitting.md` | **Splitting discipline.** Five-axis decomposition (Spike, Paths, Interfaces, Data, Rules) for stories too large for one phase. | `gsd-mvp-phase` workflow when the user story exceeds size threshold |
|
||||
| `gsd-core/references/execute-mvp-tdd.md` | **Gate.** MVP+TDD runtime gate semantics: when it fires, what it checks, halt-and-report protocol, end-of-phase blocking escalation, Behavior-Adding Task definition. | `gsd-executor` agent when `MVP_MODE=true && TDD_MODE=true` |
|
||||
| `gsd-core/references/verify-mvp-mode.md` | **UAT framing.** Three-section UAT structure (user-flow → technical → coverage), anti-patterns, `User Flow Coverage` section in VERIFICATION.md. | `gsd-verifier` agent when the phase under verification has `mode: mvp` |
|
||||
|
||||
## Concept-to-file map
|
||||
|
||||
@@ -22,10 +22,10 @@ If you're looking for the canonical statement of a concept, this is where to fin
|
||||
- **MVP Mode resolution chain** — `workflows/plan-phase.md` Step 1 (CLI flag → roadmap → config → false). Mirrored in `execute-phase.md` and `verify-work.md`.
|
||||
- **`**Mode:** mvp` parser** — `gsd-core/bin/lib/roadmap.cjs` (`searchPhaseInContent` + `cmdRoadmapAnalyze`). Workflows compare against the parser output, never re-parse.
|
||||
- **User Story regex** — `/^As a .+, I want to .+, so that .+\.$/` — applied at runtime by `gsd-verifier` (the user-story-format guard) and `gsd-mvp-phase` (interactive validation).
|
||||
- **Behavior-Adding Task predicate** — `references/execute-mvp-tdd.md` (the canonical three-check definition). Applied at runtime by `gsd-executor`.
|
||||
- **Behavior-Adding Task predicate** — `gsd-core/references/execute-mvp-tdd.md` (the canonical three-check definition). Applied at runtime by `gsd-executor`.
|
||||
- **Walking Skeleton gate condition** — `workflows/plan-phase.md` (Phase 1 + new project + `--mvp` + no prior summaries → emit `SKELETON.md`).
|
||||
- **MVP+TDD Gate** (RED→GREEN enforcement) — `references/execute-mvp-tdd.md`.
|
||||
- **MVP-mode UAT framing** (user-flow first, technical deferred) — `references/verify-mvp-mode.md`.
|
||||
- **MVP+TDD Gate** (RED→GREEN enforcement) — `gsd-core/references/execute-mvp-tdd.md`.
|
||||
- **MVP-mode UAT framing** (user-flow first, technical deferred) — `gsd-core/references/verify-mvp-mode.md`.
|
||||
- **Per-phase mode authoring** — `workflows/mvp-phase.md` (writes `**Mode:** mvp` to ROADMAP.md after collecting the user story).
|
||||
- **Project-wide mode prompt at init** — `workflows/new-project.md` (Vertical MVP vs Horizontal Layers question).
|
||||
|
||||
|
||||
@@ -70,7 +70,7 @@ issues. You must reduce the count or the loop will terminate.
|
||||
If issues persist after 3 revision cycles:
|
||||
|
||||
1. Present remaining issues to the user
|
||||
2. Use gate prompt (pattern: yes-no from `references/gate-prompts.md`):
|
||||
2. Use gate prompt (pattern: yes-no from `gsd-core/references/gate-prompts.md`):
|
||||
question: "Issues remain after 3 revision attempts. Proceed with current output?"
|
||||
header: "Proceed?"
|
||||
options:
|
||||
|
||||
@@ -127,7 +127,7 @@ verification: backstop }` in `must_haves.truths`, NOT a prose note (the verifier
|
||||
deterministically on the `verification: backstop` field; a parenthetical is unparseable — the #1110
|
||||
fragility; flat scalar `verification:` key, never a nested object, ADR-550 #1278). A `backstop` truth
|
||||
the verifier cannot confirm with explicit evidence abstains → `human_needed` (reason
|
||||
`insufficient_spec`), never a silent pass (#1154; `references/honest-verifier.md`). **Never
|
||||
`insufficient_spec`), never a silent pass (#1154; `gsd-core/references/honest-verifier.md`). **Never
|
||||
auto-dismiss** (a wrong dismissal is the exact silent failure this eliminates). An `unclassified` row
|
||||
stays **`unresolved`** (#1110) — never auto-resolved with backstop — and is surfaced to the planner as a flagged
|
||||
assumption. Pass `$COVERAGE` (+ the gate's `$SPECLESS_FALLBACK_DISABLED` note) into the gsd-planner
|
||||
|
||||
@@ -8,7 +8,7 @@ Rules that apply to ALL workflows and agents. Individual workflows may have addi
|
||||
|
||||
1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them. Reading agent definitions into the orchestrator wastes context for content automatically injected into subagent sessions.
|
||||
2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead. Agents have their own context windows.
|
||||
3. **Read depth scales with context window** -- check `context_window` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000 (1M model): full body reads permitted when content is needed for inline decisions. See `references/context-budget.md` for the complete table.
|
||||
3. **Read depth scales with context window** -- check `context_window` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000 (1M model): full body reads permitted when content is needed for inline decisions. See `gsd-core/references/context-budget.md` for the complete table.
|
||||
4. **Delegate** heavy work to subagents -- the orchestrator routes, it does not build, analyze, research, investigate, or verify.
|
||||
5. **Proactive pause warning**: If you have already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
|
||||
|
||||
@@ -26,7 +26,7 @@ Rules that apply to ALL workflows and agents. Individual workflows may have addi
|
||||
|
||||
## Questioning Anti-Patterns
|
||||
|
||||
Reference: `references/questioning.md` for the full anti-pattern list.
|
||||
Reference: `gsd-core/references/questioning.md` for the full anti-pattern list.
|
||||
|
||||
12. **Do not** walk through checklists -- checklist walking (asking items one by one from a list) is the #1 anti-pattern. Instead, use progressive depth: start broad, dig where interesting.
|
||||
13. **Do not** use corporate speak -- avoid jargon like "stakeholder alignment", "synergize", "deliverables". Use plain language.
|
||||
@@ -59,5 +59,5 @@ Reference: `references/questioning.md` for the full anti-pattern list.
|
||||
|
||||
## iOS / Apple Platform Rules
|
||||
|
||||
28. **NEVER use `Package.swift` + `.executableTarget` (or `.target`) as the primary build system for iOS apps.** SPM executable targets produce macOS CLI binaries, not iOS `.app` bundles. They cannot be installed on iOS devices or submitted to the App Store. Use XcodeGen (`project.yml` + `xcodegen generate`) to create a proper `.xcodeproj`. See `references/ios-scaffold.md` for the full pattern.
|
||||
28. **NEVER use `Package.swift` + `.executableTarget` (or `.target`) as the primary build system for iOS apps.** SPM executable targets produce macOS CLI binaries, not iOS `.app` bundles. They cannot be installed on iOS devices or submitted to the App Store. Use XcodeGen (`project.yml` + `xcodegen generate`) to create a proper `.xcodeproj`. See `gsd-core/references/ios-scaffold.md` for the full pattern.
|
||||
29. **Verify SwiftUI API availability before use.** Many SwiftUI APIs require a specific minimum iOS version (e.g., `NavigationSplitView` is iOS 16+, `List(selection:)` with multi-select and `@Observable` require iOS 17). If a plan uses an API that exceeds the declared `IPHONEOS_DEPLOYMENT_TARGET`, raise the deployment target or add `#available` guards.
|
||||
|
||||
@@ -17,7 +17,7 @@ The framing fires when:
|
||||
- The phase under verification has `**Mode:** mvp` in ROADMAP.md (parsed via `gsd-tools query roadmap.get-phase --pick mode`).
|
||||
- AND the phase has a user-story-formatted goal (set by `/gsd mvp-phase` per Phase 2): "As a [user role], I want to [capability], so that [outcome]."
|
||||
|
||||
If the phase has `mode: mvp` but the goal is NOT in user-story format, the verifier surfaces this as a discrepancy and asks the user to run `/gsd mvp-phase` to reformat the goal — same pattern as the planner agent under MVP_MODE (per `references/planner-mvp-mode.md`).
|
||||
If the phase has `mode: mvp` but the goal is NOT in user-story format, the verifier surfaces this as a discrepancy and asks the user to run `/gsd mvp-phase` to reformat the goal — same pattern as the planner agent under MVP_MODE (per `gsd-core/references/planner-mvp-mode.md`).
|
||||
|
||||
## Generated UAT script structure under MVP mode
|
||||
|
||||
|
||||
@@ -183,7 +183,7 @@ None — all verifiable items checked programmatically.
|
||||
- `⚠️ PRESENT_BEHAVIOR_UNVERIFIED` — present + wired, but a state transition or cancellation/cleanup/ordering invariant was not exercised by any test. Counts toward `behavior_unverified`, routes to human verification, and is *excluded* from the verified score. Per-truth only — on its own the overall `status:` becomes `human_needed` (unless a higher-precedence `gaps_found` also applies); the item is preserved in `behavior_unverified_items` regardless.
|
||||
- `✓ VERIFIED (coincidental-reliance)` — an **advisory** qualifier on a truth that *is* verified but holds for an incidental reason rather than a guaranteed one (#1955): `undeclared-precondition` (state nothing in the phase's artifacts or a declared prerequisite guarantees), `incidental-ordering` (an order or side effect nothing in the code enforces), or `fixture-only` (the test's own setup establishes the precondition; the production path has no equivalent). The base `✓ VERIFIED` token is kept verbatim and leading, so it counts toward the verified score exactly as before — the advisory changes no score and no status, and never produces a human-verification item. Each flagged truth is listed in `coincidental_reliance_items` with the reason and what to harden. Not applied to a truth that never reached `✓ VERIFIED`, nor to a `PASSED (override)` truth.
|
||||
|
||||
**Filling this column — apply the reliance check to every `✓ VERIFIED` truth before writing the row.** Ask why the truth holds and classify the evidence you already recorded, not your confidence in it. Flag it when the evidence names one of the three reasons above. Do NOT flag: a precondition the code establishes or explicitly defaults; ordering the code enforces (await, explicit sequencing); a fixture merely supplying input the real caller also supplies; unease naming no specific state, ordering, or fixture. The check is endogenous and so weaker than an exogenous tag (`references/honest-verifier.md`) — which is why it is advisory and never a gate. The usual fix is to promote the hidden assumption into a declared precondition.
|
||||
**Filling this column — apply the reliance check to every `✓ VERIFIED` truth before writing the row.** Ask why the truth holds and classify the evidence you already recorded, not your confidence in it. Flag it when the evidence names one of the three reasons above. Do NOT flag: a precondition the code establishes or explicitly defaults; ordering the code enforces (await, explicit sequencing); a fixture merely supplying input the real caller also supplies; unease naming no specific state, ordering, or fixture. The check is endogenous and so weaker than an exogenous tag (`gsd-core/references/honest-verifier.md`) — which is why it is advisory and never a gate. The usual fix is to promote the hidden assumption into a declared precondition.
|
||||
- `✗ FAILED` — artifact missing, stub, or unwired
|
||||
- `? UNCERTAIN` — can't verify programmatically
|
||||
|
||||
|
||||
@@ -96,7 +96,7 @@ These user-referenced docs are often MORE important than ROADMAP.md refs because
|
||||
|
||||
**Thinking partner (conditional):**
|
||||
If `features.thinking_partner` is enabled in config, check the user's answer for tradeoff signals
|
||||
(see `references/thinking-partner.md` for signal list). If tradeoff detected:
|
||||
(see `gsd-core/references/thinking-partner.md` for signal list). If tradeoff detected:
|
||||
|
||||
```text
|
||||
I notice competing priorities here — {option_A} optimizes for {goal_A} while {option_B} optimizes for {goal_B}.
|
||||
|
||||
@@ -709,7 +709,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
|
||||
|
||||
<worktree_branch_check>
|
||||
ORCHESTRATOR build-time embed (NOT a sub-agent runtime step): before this dispatch, read `gsd-core/references/worktree-branch-check.md`, substitute `{EXPECTED_BASE}` with the base SHA captured above ({EXPECTED_BASE}), and replace this note with that fragment's `<worktree_branch_check>` block so the dispatched prompt carries the runnable guard verbatim — do not pass this instruction through in its place.
|
||||
Per-commit HEAD/cwd-drift/path-guard: `agents/gsd-executor.md` steps 0/0a/0b + `references/worktree-path-safety.md` (in <execution_context>).
|
||||
Per-commit HEAD/cwd-drift/path-guard: `agents/gsd-executor.md` steps 0/0a/0b + `gsd-core/references/worktree-path-safety.md` (in <execution_context>).
|
||||
</worktree_branch_check>
|
||||
|
||||
<parallel_execution>
|
||||
|
||||
@@ -113,7 +113,7 @@ Extract from the imported content:
|
||||
|
||||
<step name="plan_conflict_detection">
|
||||
|
||||
Run conflict checks against the loaded project context. The report format, severity semantics, and safety-gate behavior are defined by `references/doc-conflict-engine.md` — read it and apply it here. Operation noun: `import`.
|
||||
Run conflict checks against the loaded project context. The report format, severity semantics, and safety-gate behavior are defined by `gsd-core/references/doc-conflict-engine.md` — read it and apply it here. Operation noun: `import`.
|
||||
|
||||
### BLOCKER checks (any one prevents import):
|
||||
|
||||
@@ -134,7 +134,7 @@ Run conflict checks against the loaded project context. The report format, sever
|
||||
- Plan uses a library not currently in the project tech stack → [INFO]
|
||||
- Plan adds a new phase to the ROADMAP.md structure → [INFO]
|
||||
|
||||
Render the full Conflict Detection Report using the format in `references/doc-conflict-engine.md`.
|
||||
Render the full Conflict Detection Report using the format in `gsd-core/references/doc-conflict-engine.md`.
|
||||
|
||||
**If any [BLOCKER] exists:** apply the safety gate from the reference — exit WITHOUT writing any files. No PLAN.md is written when blockers exist.
|
||||
|
||||
@@ -142,7 +142,7 @@ Render the full Conflict Detection Report using the format in `references/doc-co
|
||||
|
||||
**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
|
||||
|
||||
Ask via AskUserQuestion using the approve-revise-abort pattern (see `references/gate-prompts.md`):
|
||||
Ask via AskUserQuestion using the approve-revise-abort pattern (see `gsd-core/references/gate-prompts.md`):
|
||||
- question: "Review the warnings above. Proceed with import?"
|
||||
- header: "Approve?"
|
||||
- options: Approve | Abort
|
||||
@@ -256,7 +256,7 @@ Show: plan filename written, phase directory, validation result, next steps.
|
||||
## Anti-Patterns
|
||||
|
||||
Do NOT:
|
||||
- Violate the shared conflict-engine contract in `references/doc-conflict-engine.md` (no markdown tables, no new severity labels, no bypass of the BLOCKER gate)
|
||||
- Violate the shared conflict-engine contract in `gsd-core/references/doc-conflict-engine.md` (no markdown tables, no new severity labels, no bypass of the BLOCKER gate)
|
||||
- Write PLAN.md files as `PLAN-01.md` or `plan-01.md` — always use `{NN}-{MM}-PLAN.md`
|
||||
- Use `pbr:plan-checker` or `pbr:planner` — use `gsd-plan-checker` and `gsd-planner`
|
||||
- Write `.planning/.active-skill` — this is a PBR pattern with no GSD equivalent
|
||||
|
||||
@@ -68,7 +68,7 @@ Parse `project_exists`, `planning_exists`, `has_git`, `git_worktree_root`, `in_n
|
||||
- `planning_exists: true` → `MODE=merge`
|
||||
- `planning_exists: false` → `MODE=new`
|
||||
|
||||
If user passed `--mode new` but `.planning/` already exists: display warning and require explicit confirm via `AskUserQuestion` (approve-revise-abort from `references/gate-prompts.md`) before overwriting.
|
||||
If user passed `--mode new` but `.planning/` already exists: display warning and require explicit confirm via `AskUserQuestion` (approve-revise-abort from `gsd-core/references/gate-prompts.md`) before overwriting.
|
||||
|
||||
Git initialisation (Bug #3491 — never create a nested `.git` inside an existing worktree):
|
||||
|
||||
@@ -140,7 +140,7 @@ GSD > Discovered {N} docs, which exceeds the v1 cap of 50.
|
||||
|
||||
Exit without proceeding.
|
||||
|
||||
**Display discovered set** and request approval (see `references/gate-prompts.md` — `yes-no-pick` pattern works; or `approve-revise-abort`):
|
||||
**Display discovered set** and request approval (see `gsd-core/references/gate-prompts.md` — `yes-no-pick` pattern works; or `approve-revise-abort`):
|
||||
|
||||
```
|
||||
Discovered {N} documents:
|
||||
@@ -225,7 +225,7 @@ The synthesizer writes:
|
||||
|
||||
Read `.planning/INGEST-CONFLICTS.md`. Count entries in each bucket (the synthesizer always writes the three-bucket header; parse the `### BLOCKERS ({N})`, `### WARNINGS ({N})`, `### INFO ({N})` lines).
|
||||
|
||||
Apply the safety semantics from `references/doc-conflict-engine.md`. Operation noun: `ingest`.
|
||||
Apply the safety semantics from `gsd-core/references/doc-conflict-engine.md`. Operation noun: `ingest`.
|
||||
|
||||
**If BLOCKERS > 0:**
|
||||
|
||||
@@ -340,7 +340,7 @@ Show:
|
||||
## Anti-Patterns
|
||||
|
||||
Do NOT:
|
||||
- Violate the shared conflict-engine contract in `references/doc-conflict-engine.md` (no markdown tables, no new severity labels, no bypass of the BLOCKER gate)
|
||||
- Violate the shared conflict-engine contract in `gsd-core/references/doc-conflict-engine.md` (no markdown tables, no new severity labels, no bypass of the BLOCKER gate)
|
||||
- Write PROJECT.md, REQUIREMENTS.md, ROADMAP.md, or STATE.md when BLOCKERs exist in the conflict report
|
||||
- Skip the 50-doc cap — larger sets must use `--manifest` to narrow the scope
|
||||
- Auto-resolve LOCKED-vs-LOCKED ADR contradictions — those are BLOCKERs in both modes
|
||||
|
||||
@@ -48,7 +48,7 @@ INIT_EARLY=$(gsd_run query init.new-milestone)
|
||||
if [[ "$INIT_EARLY" == @file:* ]]; then INIT_EARLY=$(cat "${INIT_EARLY#@file:}"); fi
|
||||
```
|
||||
|
||||
`GSD_WS` must chain to every downstream routing suggestion in this workflow (Step 4's shared-file guard, and the `/gsd:discuss-phase`/`/gsd:plan-phase` routing hints below) per the routing-propagation contract in `references/workstream-flag.md` — never let it silently drop.
|
||||
`GSD_WS` must chain to every downstream routing suggestion in this workflow (Step 4's shared-file guard, and the `/gsd:discuss-phase`/`/gsd:plan-phase` routing hints below) per the routing-propagation contract in `gsd-core/references/workstream-flag.md` — never let it silently drop.
|
||||
|
||||
**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow (including the "What do you want to build next?" prompt and seed-selection questions below) MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
|
||||
|
||||
@@ -160,7 +160,7 @@ AskUserQuestion:
|
||||
|
||||
## 4. Update PROJECT.md
|
||||
|
||||
PROJECT.md is shared across workstreams (`references/workstream-flag.md` marks it `# Shared` in the directory diagram). This step has two independently-scoped parts — only Part A is workstream-guarded.
|
||||
PROJECT.md is shared across workstreams (`gsd-core/references/workstream-flag.md` marks it `# Shared` in the directory diagram). This step has two independently-scoped parts — only Part A is workstream-guarded.
|
||||
|
||||
<!-- gsd:section id="project-md-milestone-write" when="state:flat-mode" -->
|
||||
If `section_manifest` (from `INIT_EARLY`) is `null` or `"project-md-milestone-write"` is in its `included` list: read and execute `gsd-core/workflows/new-milestone/steps/project-md-milestone-write.md`. Otherwise (a workstream is active) skip — do not read the file; Part B below still runs regardless of `GSD_WS`.
|
||||
|
||||
@@ -90,7 +90,7 @@ CONTEXT_WINDOW=$(gsd_run query config-get context_window 2>/dev/null || echo "20
|
||||
MVP_MODE_CFG=$(gsd_run query config-get workflow.mvp_mode 2>/dev/null || echo "false")
|
||||
```
|
||||
|
||||
When the tdd capability's `workflow.tdd_mode` is active (resolved via the plan:pre render-hooks), the planner agent is instructed to apply `type: tdd` to eligible tasks using heuristics from `references/tdd.md`. The TDD guidance is injected via the tdd capability's contribution hook at §5.6; no inline config-get is needed.
|
||||
When the tdd capability's `workflow.tdd_mode` is active (resolved via the plan:pre render-hooks), the planner agent is instructed to apply `type: tdd` to eligible tasks using heuristics from `gsd-core/references/tdd.md`. The TDD guidance is injected via the tdd capability's contribution hook at §5.6; no inline config-get is needed.
|
||||
|
||||
When `CONTEXT_WINDOW >= 500000`, the planner prompt includes the 3 most recent prior-phase CONTEXT.md/SUMMARY.md files plus any phases in the current phase's `Depends on:` field (explicit deps load regardless of recency).
|
||||
|
||||
@@ -168,7 +168,7 @@ When `WALKING_SKELETON=true`:
|
||||
- Planner is instructed to produce `SKELETON.md` in the phase directory alongside `PLAN.md`. The template lives at `~/.claude/gsd-core/references/skeleton-template.md` — the planner reads it when producing SKELETON.md (lazy; not loaded on non-skeleton runs).
|
||||
- The plan must scaffold project + routing + one real DB read/write + one real UI interaction + dev deployment — the thinnest possible end-to-end working slice.
|
||||
|
||||
**Interaction with `--prd <filepath>`.** `--mvp` and `--prd` compose. The PRD express path (Step 3.5) creates `CONTEXT.md` from the PRD file and continues to research; the Walking Skeleton gate fires independently from the conditions above. When both are active on Phase 1 of a new project, the planner receives `WALKING_SKELETON=true` and PRD-derived context simultaneously — the PRD informs *what the skeleton should prove*. No precedence is needed; the two signals are orthogonal. See [`references/mvp-concepts.md`](../references/mvp-concepts.md) for the broader interaction map.
|
||||
**Interaction with `--prd <filepath>`.** `--mvp` and `--prd` compose. The PRD express path (Step 3.5) creates `CONTEXT.md` from the PRD file and continues to research; the Walking Skeleton gate fires independently from the conditions above. When both are active on Phase 1 of a new project, the planner receives `WALKING_SKELETON=true` and PRD-derived context simultaneously — the PRD informs *what the skeleton should prove*. No precedence is needed; the two signals are orthogonal. See [`gsd-core/references/mvp-concepts.md`](../references/mvp-concepts.md) for the broader interaction map.
|
||||
|
||||
Extract express-path args from $ARGUMENTS: `PRD_FILE` (`--prd <filepath>`), `INGEST_PATH` (`--ingest <path-or-glob>`), and optional `INGEST_FORMAT` (`--ingest-format <auto|nygard|madr|narrative>`, default `auto`).
|
||||
|
||||
@@ -784,7 +784,7 @@ Output consumed by /gsd:execute-phase. Plans need:
|
||||
- Tasks in XML format with read_first and acceptance_criteria fields (MANDATORY on every task)
|
||||
- Verification criteria
|
||||
- must_haves for goal-backward verification
|
||||
- If the SPEC has an `## Edge Coverage` section, lift every resolved (verification: explicit) edge's acceptance criterion into `must_haves.truths` as a plain string, and every resolved (verification: backstop) edge **as a structured flat-scalar marker** — an object item `{ statement: <the check>, verification: backstop }`, NOT a prose note (the verifier branches deterministically on the `verification: backstop` field; a parenthetical is unparseable — the #1110 fragility). Use a flat scalar `verification:` continuation key, never a nested object (ADR-550 #1278). At verify time a `backstop` truth the verifier cannot confirm with explicit evidence abstains → `human_needed` (reason `insufficient_spec`), never a silent pass (#1154; see `references/honest-verifier.md`). `unresolved` edges are explicit assumptions — surface them in the plan, do not silently drop them. **Otherwise** (`EDGE_ABSENT`): apply the SAME lift to the fallback report `{COVERAGE}` (per §C of `references/specless-probe-fallback.md`); a SPEC-supplied section is never re-run.
|
||||
- If the SPEC has an `## Edge Coverage` section, lift every resolved (verification: explicit) edge's acceptance criterion into `must_haves.truths` as a plain string, and every resolved (verification: backstop) edge **as a structured flat-scalar marker** — an object item `{ statement: <the check>, verification: backstop }`, NOT a prose note (the verifier branches deterministically on the `verification: backstop` field; a parenthetical is unparseable — the #1110 fragility). Use a flat scalar `verification:` continuation key, never a nested object (ADR-550 #1278). At verify time a `backstop` truth the verifier cannot confirm with explicit evidence abstains → `human_needed` (reason `insufficient_spec`), never a silent pass (#1154; see `gsd-core/references/honest-verifier.md`). `unresolved` edges are explicit assumptions — surface them in the plan, do not silently drop them. **Otherwise** (`EDGE_ABSENT`): apply the SAME lift to the fallback report `{COVERAGE}` (per §C of `gsd-core/references/specless-probe-fallback.md`); a SPEC-supplied section is never re-run.
|
||||
- If the SPEC has a `## Prohibitions` section, lift every resolved prohibition into the `must_haves.prohibitions:` sibling block (NOT `truths` — ADR-550 D3) with `statement`+`status`+`verification`, via the single `projectProhibitions` serializer (Hyrum — no second serializer); unresolved -> flagged assumptions, don't drop; never put a must-NOT under `truths`. **Otherwise** (`PROHIB_ABSENT`), author the recalled prohibitions into the SAME block via the SAME `projectProhibitions` contract but **descriptor-less** (no `check_*`) so each disposes flagged-unverified; never auto-dismiss. Section-level precedence + no-silent-drop equality apply (§C).
|
||||
- If a `-UI-SPEC.md` exists (resolved above as `UI_SPEC_PATH`) with a `## UI Considerations` section, lift it by the **identical rule** as `## Edge Coverage` above — resolved (explicit) → `must_haves.truths` string, resolved (backstop) → flat scalar `{ statement, verification: backstop }`, `unresolved` → explicit planner assumption (no new verb — ADR-550 #1278/#1154; #1867). Read it from `UI_SPEC_PATH` (the SPEC glob excludes `-UI-SPEC.md`).
|
||||
- **"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.
|
||||
|
||||
Reference in New Issue
Block a user