gsdd-cli 0.27.0 → 0.29.0

package/distilled/templates/ui-proof.md

@@ -1,200 +1,100 @@
-# UI Proof Bundle Template
+# Browser Proof Observation Template
 
-Use this template when work affects rendered UI or when a plan defines `ui_proof_slots`. Keep the bundle compact, claim-specific, and attached to the relevant phase, quick task, or brownfield change.
+Use this template when work affects rendered UI or when a plan sets
+`browser_proof_required: true`. Keep the record compact, claim-specific, and
+attached to the relevant phase, quick task, or brownfield change.
 
-UI proof uses the existing closure evidence kinds only: `code`, `test`, `runtime`, `delivery`, and `human`. Screenshots, traces, videos, reports, accessibility scans, Gherkin, visual diffs, and manual notes are artifact types or activities that map onto those evidence kinds. They are not new evidence kinds.
+Browser proof uses the existing closure evidence kinds only: `code`, `test`,
+`runtime`, `delivery`, and `human`. Screenshots, traces, videos, reports,
+accessibility scans, visual diffs, and manual notes are artifacts or activities
+that map onto those evidence kinds. They are not new evidence kinds.
 
-For live rendered UI evidence, default to `agent-browser`: open the route, capture an interactive snapshot/refs when interaction is part of the claim, exercise the changed flow, capture screenshots for the planned viewport(s), and record console/network observations when they affect the claim. If the repo already has Playwright tests or a package script wrapping them, those remain the canonical repeatable regression path; use them as `test` evidence and use `agent-browser` for complementary live runtime proof. Do not introduce new Playwright, Cypress, Storybook, CI, browser MCP, or visual-regression infrastructure just to satisfy this template. Use Playwright scripting only for checks `agent-browser` cannot cover cleanly, such as JS-disabled behavior, structured console listeners, or multi-context testing.
+For live rendered UI evidence, default to `agent-browser`: open the route,
+capture interactive refs when interaction is part of the claim, exercise the
+changed flow, capture screenshots for planned viewport(s), and record
+console/network observations when they affect the claim. If the repo already
+has Playwright tests or a package script wrapping them, those remain the
+repeatable regression path; use them as `test` evidence and use browser
+observation for complementary runtime proof.
 
-Tool availability is part of the proof record. In runtimes where `agent-browser` is not available, first state that availability constraint, then use the closest project-native interactive browser path and record the fallback in `evidence_inputs.tools_used`, `commands_or_manual_steps`, and `claim_limits`. A fallback can support a narrowed local runtime claim, but it must not silently pretend that the default `agent-browser` path ran.
+Do not introduce new Playwright, Cypress, Storybook, CI, browser MCP, or visual
+regression infrastructure just to satisfy this template. Use Playwright
+scripting only for checks `agent-browser` cannot cover cleanly, such as
+JS-disabled behavior, structured console listeners, or multi-context testing.
 
-## Planned Proof Slots
+Tool availability is part of the proof record. In runtimes where
+`agent-browser` is not available, first state that availability constraint, then
+use the closest project-native interactive browser path and narrow the claim to
+what that fallback actually proves.
 
-Every UI-sensitive plan needs either at least one slot under `ui_proof_slots` or an explicit `no_ui_proof_rationale` explaining why no rendered UI proof is required.
+## Plan Declaration
 
-```yaml
-ui_proof_slots:
-  - slot_id: ui-01
-    requirement_id: REQ-01
-    claim: "User can complete the changed flow without a broken rendered UI."
-    route_state: "/example route, role, data state, and UI state to inspect"
-    required_evidence_kinds: [test, runtime]
-    optional_evidence_kinds: [human]
-    minimum_observations:
-      - "Changed control is visible and usable in the stated state."
-      - "Expected interaction completes without console/runtime error."
-    expected_artifact_types: [screenshot, report]
-    validation_command: "gsdd ui-proof compare {work_item_dir}/ui-proof-slots.json {work_item_dir}/UI-PROOF.md"
-    environment:
-      app_url: "http://localhost:3000"
-      data_state: "synthetic or seeded data"
-    viewport:
-      width: 1280
-      height: 720
-      notes: "State why this viewport is enough for the claim, or add separate slots/observations for mobile, desktop, or responsive states."
-    manual_acceptance_required: false
-    claim_limit: "Does not prove cross-browser layout, full accessibility conformance, production delivery, or unrelated UI states."
-no_ui_proof_rationale: null
-```
+Every UI-sensitive plan should contain:
 
-Slot rules:
-- Keep each slot tied to one exact UI claim.
-- Use the lightest proof that can catch a botched rendered experience for that claim.
-- Specify the route/state, viewport choice, minimum observations, expected artifact types, and runnable validation path tightly enough that a checker can reject vague proof before execution.
-- The planner chooses the viewport set, but the slot must explain the choice. Include desktop and mobile proof when the claim covers responsive layout or when the changed surface is likely to behave differently across those sizes; otherwise narrow the claim limit.
-- Source annotations, AST/cAST findings, semantic search hits, comments, and Semble-like retrieval may help discover proof obligations. They are discovery hints only; they do not satisfy proof slots.
-- Do not add Playwright, Cypress, Storybook, Cucumber, CI, browser MCP, or visual-regression tooling by default.
-- Human approval is required for visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, and privacy publication decisions.
-- Human approval does not replace required non-human evidence when the slot requires `code`, `test`, `runtime`, or `delivery` evidence.
-
-## Observed Proof Bundle
-
-Create or update this bundle during execution or verification when planned UI proof slots exist. JSON is the canonical machine-readable proof bundle format. Markdown proof files must include fenced JSON for deterministic validation.
-
-Replace placeholders such as `{work_item_dir}` with the current phase, quick-task, or brownfield-change directory before running commands or validating the bundle.
-
-```json
-{
-  "proof_bundle_version": 1,
-  "scope": {
-    "work_item": "phase-or-quick-or-brownfield-id",
-    "requirement_ids": ["REQ-01"],
-    "slot_ids": ["ui-01"],
-    "claim": "User can complete the changed flow without a broken rendered UI."
-  },
-  "route_state": {
-    "route": "/example",
-    "state": "role, data state, feature flag, loading/error/empty state, or component story"
-  },
-  "environment": {
-    "app_url": "http://localhost:3000",
-    "browser": "agent-browser default; record fallback when unavailable",
-    "browser_version": "record if known",
-    "os": "record if relevant",
-    "data_state": "synthetic or seeded data"
-  },
-  "viewport": {
-    "width": 1280,
-    "height": 720,
-    "device_scale_factor": "record if relevant"
-  },
-  "evidence_inputs": {
-    "kinds": ["test", "runtime"],
-    "tools_used": ["playwright", "agent-browser"]
-  },
-  "commands_or_manual_steps": [
-    {
-      "command": "npm run test:e2e -- changed-flow.spec.ts",
-      "exit_code": 0,
-      "result": "passed",
-      "attempts": 1
-    },
-    {
-      "command": "agent-browser open http://localhost:3000/example && agent-browser snapshot -i && agent-browser screenshot {work_item_dir}/artifacts/example-1280.png --full",
-      "result": "passed",
-      "attempts": 1
-    },
-    {
-      "manual_step": "Using agent-browser refs, complete the changed interaction as a synthetic user and check for visible breakage or relevant console/network failures.",
-      "result": "passed"
-    }
-  ],
-  "observations": [
-    {
-      "observation": "Changed control is visible and completes the flow.",
-      "claim": "User can complete the changed flow without a broken rendered UI.",
-      "route_state": {
-        "route": "/example",
-        "state": "role, data state, feature flag, loading/error/empty state, or component story"
-      },
-      "evidence_kind": "runtime",
-      "artifact_refs": ["test-results/changed-flow-report/index.html", "{work_item_dir}/artifacts/example-1280.png"],
-      "privacy": {
-        "data_classification": "synthetic",
-        "raw_artifacts_safe_to_publish": false,
-        "retention": "temporary_review"
-      },
-      "result": "passed",
-      "claim_limit": "Does not prove Safari/WebKit behavior."
-    }
-  ],
-  "artifacts": [
-    {
-      "path": "test-results/changed-flow-report/index.html",
-      "type": "report",
-      "visibility": "local_only",
-      "retention": "temporary_review",
-      "sensitivity": "possible",
-      "safe_to_publish": false,
-      "notes": "Local report only; not public proof."
-    },
-    {
-      "path": "{work_item_dir}/artifacts/example-1280.png",
-      "type": "screenshot",
-      "visibility": "local_only",
-      "retention": "temporary_review",
-      "sensitivity": "possible",
-      "safe_to_publish": false,
-      "notes": "Local screenshot only; not public proof unless sanitized and reclassified."
-    }
-  ],
-  "privacy": {
-    "data_classification": "synthetic",
-    "redactions": [],
-    "raw_artifacts_safe_to_publish": false,
-    "retention": "Keep metadata bundle; keep raw artifacts only while needed for review or failed proof triage."
-  },
-  "manual_acceptance": {
-    "required": false,
-    "reviewer": null,
-    "result": "not_applicable"
-  },
-  "result": {
-    "claim_status": "passed",
-    "comparison_status_by_slot": {
-      "ui-01": "satisfied"
-    },
-    "failure_classification": null
-  },
-  "claim_limits": [
-    "Does not prove Safari/WebKit behavior.",
-    "Does not prove full WCAG conformance.",
-    "Does not prove deployed production behavior."
-  ]
-}
+```yaml
+browser_proof_required: true
+browser_proof_rationale: Visible route or interaction changes require rendered browser proof.
 ```
 
-Bundle rules:
-- Reference raw screenshots, traces, videos, DOM snapshots, reports, accessibility scans, Gherkin, and visual diffs by path or link. Do not store raw binary or sensitive artifacts inline.
-- Each observation must identify the claim, route/state, evidence kind, artifact references behind it, privacy metadata, result, and claim limit it supports.
-- Every observation `artifact_refs` value must match an `artifacts[].path` or `artifacts[].url` value.
-- Artifact count is never proof. Unsupported or weakly linked artifacts are `partial`, `missing`, `waived`, or `deferred`, not `satisfied`.
-- Each artifact must record the locked privacy fields `visibility`, `retention`, `sensitivity`, and `safe_to_publish`.
-- Raw screenshots, traces, videos, DOM snapshots, and reports default to `visibility: local_only` plus `safe_to_publish: false` unless explicitly classified as sanitized and safe to publish.
-- Local-only or `safe_to_publish: false` artifacts can support local review only; they must not back tracked, public, delivery, release, or publication proof claims.
-- Human acceptance may close a narrowed claim only by recording waiver, deferment, or proof debt; it must not upgrade missing or mismatched non-human proof to `satisfied`.
-- Quick-mode UI proof should use deterministic synthetic IDs such as `quick-001` and `quick-001-ui-01` when roadmap requirement IDs do not exist.
-- Classify failed UI proof using existing GSDD gap/proof-debt language: `product_bug`, `missing_infra`, `flaky_harness`, or `ambiguous_spec`. Do not add new result statuses or evidence kinds for those causes.
+Plans that do not claim rendered UI behavior should contain:
 
-## Deterministic Validation
+```yaml
+browser_proof_required: false
+browser_proof_rationale: CLI/docs/backend-only work; no visible UI behavior is claimed.
+```
 
-Use `gsdd ui-proof validate <path>` on JSON proof-bundle metadata or markdown fenced JSON before relying on a bundle for closure; add `--claim <public|publication|tracked|delivery|release>` only when validating that stronger proof use. Use `gsdd ui-proof compare <planned-slots-json> [observed-bundle-json ...]` when verifying planned proof slots against observed bundles through the deterministic product-facing path. Required planned-slot fields are `slot_id`, `claim`, `route_state`, `required_evidence_kinds`, `minimum_observations`, `expected_artifact_types`, `validation_command`, `environment`, `viewport`, `manual_acceptance_required`, and `claim_limit`. Required observed-bundle top-level fields are `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`. The validator checks planned-slot specificity, required bundle and observation fields, structured command/manual-step entries, fixed evidence kinds, concise `tools_used` IDs, `result.claim_status`, observation `result`, comparison statuses, failure classification for failed/partial proof, non-empty claim limits, locked artifact and observation privacy fields, observation-to-artifact references, workspace-relative/http(s) artifact references, existing local artifact paths when validating from files, and explicit public/tracked/delivery proof claims that rely on local-only, unsafe, unsanitized, or privacy-contradictory artifacts. `claim_status`, observation `result`, and command/manual-step `result` use `passed`, `failed`, `partial`, `waived`, `deferred`, or `not_applicable`; failed/partial proof uses `product_bug`, `missing_infra`, `flaky_harness`, or `ambiguous_spec`. It does not inspect raw screenshot, trace, video, DOM, or report contents and does not require any specific browser provider such as `agent-browser`.
+When browser proof is required, the plan body should include:
+
+```markdown
+## Browser Proof Plan
+Routes/states: /example route, role, data state, and UI state to inspect
+Viewports: Desktop 1280px and mobile 390px, or a narrowed viewport claim
+Runtime path: agent-browser preferred; explain fallback constraints if unavailable
+Evidence kind: runtime
+No-command rationale: agent-browser/manual refs were required for this local runtime; claim is limited to the observed session.
+Observations: Changed control is visible, interaction completes, no relevant console/network failures
+Artifacts: .work/.../artifacts/example-1280.png (local-only unless sanitized)
+Claim limit: Proves only this changed route/state and viewport set
+```
 
-## Comparison Statuses
+If no command can reproduce the proof because the runtime path is manual or
+interactive only, replace `Evidence command:` with:
 
-Use these statuses when comparing planned slots to observed proof:
+```markdown
+No-command rationale: agent-browser/manual refs were required for this local runtime; claim is limited to the observed session.
+```
 
-| Status | Meaning | Claim impact |
-| --- | --- | --- |
-| `satisfied` | Required observations and evidence kinds are present, scoped, and inspectable for the exact claim. | Supports the scoped UI claim. |
-| `partial` | Some proof exists, but observations, artifact references, evidence kinds, privacy metadata, or assurance are weaker than planned. | Record a reduced claim or gap. |
-| `missing` | Required proof is absent. | Blocks the UI claim unless explicitly waived or deferred. |
-| `waived` | A human or approved plan waiver accepts the risk. | Does not prove the UI claim. |
-| `deferred` | Proof moved to later work. | Current work must not claim the UI behavior is proven. |
-| `not_applicable` | Accepted rationale says no UI proof is required. | No UI proof gap for that claim. |
+## Observation Record
+
+Write one record per checked flow:
+
+```markdown
+## Browser Proof Observation
+
+- Plan: 01-example/01-PLAN.md
+- Flow: /example route, role, data state, and UI state checked
+- Viewports: 1280x720 desktop, 390x844 mobile
+- Runtime path: agent-browser
+- Evidence kind: runtime
+- No-command rationale: agent-browser/manual refs were required for this local runtime; claim is limited to the observed session.
+- Observed: Changed control rendered, interaction completed, no relevant console/network failures
+- Artifacts:
+  - .work/.../artifacts/example-1280.png — local-only, not safe to publish
+  - .work/.../artifacts/example-390.png — local-only, not safe to publish
+- Privacy/safety: artifacts are local-only and not safe to publish unless sanitized
+- Result: passed
+- Claim limit: Proves only the scoped route/state, data setup, and viewport set.
+- Stale after: route markup, interaction behavior, data fixture, or viewport assumptions change.
+```
 
-Proof debt notes should name the slot, claim, route/state, missing or weak linkage, human acceptance basis, narrowed claim limit, and follow-up trigger.
+For failed or partial proof, use the failure-cause names defined in
+`distilled/references/proof-rules.md` and record the narrowed claim or follow-up
+trigger.
 
 ## Claim Boundary
 
-A UI proof bundle proves only the scoped claim, route/state, environment, viewport, observations, and evidence kinds it records. It does not imply broad visual quality, cross-browser coverage, full accessibility conformance, production delivery, release readiness, or public proof unless those dimensions are explicitly planned, evidenced, and classified safe to publish.
+Browser proof proves only the scoped route/state, environment, viewport,
+observations, artifacts, and evidence kinds it records. It does not imply broad
+visual quality, cross-browser coverage, full accessibility conformance,
+production delivery, release readiness, or public proof unless those dimensions
+are explicitly planned, evidenced, and safe to publish.

package/distilled/workflows/audit-milestone.md

@@ -6,28 +6,28 @@ Core mindset: individual phases can pass while the milestone fails. Integration
 
 <load_context>
 Before starting, read these files:
-1. `.planning/ROADMAP.md` - milestone phases, definitions of done, requirement assignments
-2. `.planning/SPEC.md` - requirement IDs, descriptions, and checkbox status
-3. All phase VERIFICATION.md files (from `.planning/phases/`)
-4. All phase SUMMARY.md files (from `.planning/phases/`)
-5. `.planning/AUTH_MATRIX.md` (if it exists) — authorization matrix for matrix-driven auth verification
+1. `.work/ROADMAP.md` - milestone phases, definitions of done, requirement assignments
+2. `.work/SPEC.md` - requirement IDs, descriptions, and checkbox status
+3. All phase VERIFICATION.md files (from `.work/phases/`)
+4. All phase SUMMARY.md files (from `.work/phases/`)
+5. `.work/AUTH_MATRIX.md` (if it exists) — authorization matrix for matrix-driven auth verification
 </load_context>
 
 <repo_root_helper_contract>
-All `node .planning/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
+All `node .work/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
 </repo_root_helper_contract>
 
 <lifecycle_preflight>
 Before determining milestone scope or spawning the integration checker, run:
 
-- `node .planning/bin/gsdd.mjs lifecycle-preflight audit-milestone`
+- `node .work/bin/gsdd.mjs lifecycle-preflight audit-milestone`
 
 If the preflight result is `blocked`, STOP and report the blocker instead of inferring milestone eligibility from workflow-local prose.
 
 Treat the preflight as an authorization seam over shared repo truth only:
 - it may authorize or reject milestone audit
 - it does not archive or mutate milestone state
-- the owned write for this workflow remains `.planning/v{version}-MILESTONE-AUDIT.md`
+- the owned write for this workflow remains `.work/v{version}-MILESTONE-AUDIT.md`
 </lifecycle_preflight>
 
 <evidence_contract>
@@ -64,25 +64,25 @@ Rules:
 - deferrals must name the unsupported claim, missing evidence kind(s), and later workflow or milestone candidate when known
 - contradiction checks must cover evidence, public-surface, runtime, delivery, planning-drift, and generated-surface contradictions; stop or downgrade when the claim outruns the evidence
 - `delivery_posture` and `release_claim_posture` must remain compatible: `repo_closeout` and `runtime_validated_closeout` pair with `repo_only`; `delivery_supported_closeout` pairs with `delivery_sensitive`
-- local-only `.planning/` proof may support `repo_closeout`, but public-facing release/support claims need tracked public or repo-visible evidence when intended for external readers
+- local-only `.work/` proof may support `repo_closeout`, but public-facing release/support claims need tracked public or repo-visible evidence when intended for external readers
 </evidence_contract>
 
 <process>
 
 ## 1. Determine Milestone Scope
 
-Parse `.planning/ROADMAP.md` for:
+Parse `.work/ROADMAP.md` for:
 - All phases in the current milestone (sorted numerically)
 - Milestone definition of done
 - Phase-to-requirement mappings (the Requirements field in each phase detail)
 
-Parse `.planning/SPEC.md` for:
+Parse `.work/SPEC.md` for:
 - All requirement IDs with descriptions
 - Current checkbox status (`[x]` vs `[ ]`)
 
 ## 2. Read All Phase Verifications
 
-For each phase directory in `.planning/phases/`, read the VERIFICATION.md.
+For each phase directory in `.work/phases/`, read the VERIFICATION.md.
 
 From each VERIFICATION.md, extract:
 - **Status:** passed | gaps_found | human_needed
@@ -99,14 +99,14 @@ With phase context collected, delegate cross-phase integration checking:
 
 <delegate>
 **Identity:** Integration Checker
-**Instruction:** Read `.planning/templates/roles/integration-checker.md`, then check cross-phase integration.
+**Instruction:** Read `.work/templates/roles/integration-checker.md`, then check cross-phase integration.
 
 **Context to provide:**
 - Phase directories in milestone scope
 - Key exports from each phase (extracted from SUMMARYs)
 - API routes and endpoints created
 - Milestone requirement IDs with descriptions and assigned phases
-- `.planning/AUTH_MATRIX.md` path (if it exists)
+- `.work/AUTH_MATRIX.md` path (if it exists)
 
 **Task:** Verify cross-phase wiring, API coverage, auth protection, and E2E user flows. Return structured integration report with wiring summary, API coverage, auth protection, E2E flow status, and Requirements Integration Map.
 
@@ -126,7 +126,7 @@ Combine:
 - Integration checker's report (wiring gaps, auth gaps, broken flows, requirements integration map)
 - Evidence observations by kind (`code`, `test`, `runtime`, `delivery`, `human`) from phase verifications, summaries, integration findings, and delivery metadata
 - Release claim posture observations: selected `release_claim_posture`, unsupported claims, waivers, deferrals, and contradiction checks for public, runtime, delivery, planning-drift, and generated-surface claims
-- UI proof debt from phase/quick proof bundles or verification gaps, preserving the rule that waiver/deferment/human acceptance narrows claims rather than satisfying missing proof
+- Browser-proof debt from phase/quick observation records or verification gaps, preserving the rule that waiver/deferment/human acceptance narrows claims rather than satisfying missing proof
 
 ## 5. 3-Source Cross-Reference
 
@@ -134,12 +134,12 @@ Cross-reference three independent sources for each requirement to determine sati
 
 ### 5a. Parse SPEC.md Requirements
 
-Extract all requirement IDs from `.planning/SPEC.md`:
+Extract all requirement IDs from `.work/SPEC.md`:
 - Requirement ID, description, checkbox status (`[x]` vs `[ ]`)
 
 ### 5b. Parse ROADMAP.md Phase-to-Requirement Mapping
 
-For each phase in `.planning/ROADMAP.md`, extract the Requirements field:
+For each phase in `.work/ROADMAP.md`, extract the Requirements field:
 - Which requirements are assigned to which phase
 
 ### 5c. Parse Phase VERIFICATION.md Requirements Tables
@@ -170,11 +170,11 @@ For each requirement, determine status using all available sources:
 
 **FAIL gate:** Any `unsatisfied` requirement forces `gaps_found` status on the milestone audit. No exceptions.
 
-**Orphan detection:** Requirements in `.planning/SPEC.md` that are mapped to phases in `.planning/ROADMAP.md` but absent from ALL phase VERIFICATION.md files are orphaned. Orphaned requirements are treated as `unsatisfied` - they were assigned but never verified by any phase.
+**Orphan detection:** Requirements in `.work/SPEC.md` that are mapped to phases in `.work/ROADMAP.md` but absent from ALL phase VERIFICATION.md files are orphaned. Orphaned requirements are treated as `unsatisfied` - they were assigned but never verified by any phase.
 
 ## 6. Write Milestone Audit Report
 
-Create `.planning/v{version}-MILESTONE-AUDIT.md` with structured frontmatter:
+Create `.work/v{version}-MILESTONE-AUDIT.md` with structured frontmatter:
 
 ```yaml
 ---
@@ -240,10 +240,10 @@ Evidence gate:
 - `repo_only` audits cannot be downgraded merely because `runtime` or `delivery` evidence was never relevant
 - a `passed` audit must have no unsupported stronger release claims unless they are explicitly downgraded or deferred in `release_claim_contract`
 - invalid waivers are blockers: human approval cannot replace missing `code`, `test`, `runtime`, or `delivery` evidence for a stronger claim
-- public/support wording must be scoped to tracked public or repo-visible evidence; local-only `.planning/` artifacts cannot carry public release claims by themselves
+- public/support wording must be scoped to tracked public or repo-visible evidence; local-only `.work/` artifacts cannot carry public release claims by themselves
 - generated-surface freshness is claim-scoped: W11-style drift blocks only claims that depend on generated runtime/helper freshness, not unrelated repo-only closeout
 
-**MANDATORY: The milestone audit report must exist at `.planning/v{version}-MILESTONE-AUDIT.md` on disk before presenting results. If the file was not written, STOP and report the write failure. Do NOT present audit results from conversation context alone — this is the highest-cost artifact to regenerate. Do NOT downgrade a write failure into "results shown inline anyway."**
+**MANDATORY: The milestone audit report must exist at `.work/v{version}-MILESTONE-AUDIT.md` on disk before presenting results. If the file was not written, STOP and report the write failure. Do NOT present audit results from conversation context alone — this is the highest-cost artifact to regenerate. Do NOT downgrade a write failure into "results shown inline anyway."**
 
 ## 7. Present Results
 
@@ -285,13 +285,13 @@ Audit is complete when all of these are true:
 Report the audit result to the user, then present the next step:
 
 ---
-**Completed:** Milestone audit — created `.planning/v{version}-MILESTONE-AUDIT.md`.
+**Completed:** Milestone audit — created `.work/v{version}-MILESTONE-AUDIT.md`.
 
 If status is `passed`:
 **Next step:** `/gsdd-complete-milestone` — archive the milestone and prepare for the next
 
 If status is `gaps_found`:
-**Next step:** `/gsdd-plan-milestone-gaps` — create gap-closure phases for the unsatisfied requirements
+**Next step:** `/gsdd-plan` amend/extend mode — create gap-closure phases for the unsatisfied requirements
 
 If status is `tech_debt`:
 **Next step:** Either `/gsdd-complete-milestone` (accept debt) or `/gsdd-plan` (cleanup phase)

package/distilled/workflows/complete-milestone.md

@@ -7,39 +7,39 @@ Scope boundary: you archive the current milestone. You do not start the next one
 </role>
 
 <prerequisites>
-`.planning/ROADMAP.md` must exist with phases.
-`.planning/SPEC.md` must exist.
-If `.planning/MILESTONES.md` does not exist, create it now (this is the first milestone completion — Step 8 will write the first entry).
+`.work/ROADMAP.md` must exist with phases.
+`.work/SPEC.md` must exist.
+If `.work/MILESTONES.md` does not exist, create it now (this is the first milestone completion — Step 8 will write the first entry).
 
-If `.planning/milestones/` does not exist, create it before writing archive files.
+If `.work/milestones/` does not exist, create it before writing archive files.
 </prerequisites>
 
 <load_context>
 Before starting, read these files:
 
-1. `.planning/ROADMAP.md` — phase statuses, milestone name, phase range
-2. `.planning/SPEC.md` — requirements, validated capabilities, current state section
-3. `.planning/MILESTONES.md` — previous milestone entries (for format reference); if this is the first milestone, skip — no previous entries exist yet
-4. `.planning/config.json` — `gitProtocol`, `mode` (for STOP gate behavior)
-5. All phase SUMMARY.md files in `.planning/phases/` — accomplishments, task counts
-6. Most recent `.planning/v*-MILESTONE-AUDIT.md` — audit status (passed / gaps_found)
+1. `.work/ROADMAP.md` — phase statuses, milestone name, phase range
+2. `.work/SPEC.md` — requirements, validated capabilities, current state section
+3. `.work/MILESTONES.md` — previous milestone entries (for format reference); if this is the first milestone, skip — no previous entries exist yet
+4. `.work/config.json` — `gitProtocol`, `mode` (for STOP gate behavior)
+5. All phase SUMMARY.md files in `.work/phases/` — accomplishments, task counts
+6. Most recent `.work/v*-MILESTONE-AUDIT.md` — audit status (passed / gaps_found)
 </load_context>
 
 <repo_root_helper_contract>
-All `node .planning/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
+All `node .work/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
 </repo_root_helper_contract>
 
 <lifecycle_preflight>
 Before verifying readiness or gathering archive stats, run:
 
-- `node .planning/bin/gsdd.mjs lifecycle-preflight complete-milestone`
+- `node .work/bin/gsdd.mjs lifecycle-preflight complete-milestone`
 
 If the preflight result is `blocked`, STOP and report the blocker instead of inferring milestone-close eligibility from workflow-local prose.
 
 Treat the preflight as an authorization seam over shared repo truth only:
 - it may authorize or reject milestone completion
 - it does not mutate lifecycle state by itself
-- owned writes remain the archive artifacts, `MILESTONES.md`, `.planning/SPEC.md`, and the retained `ROADMAP.md` collapse
+- owned writes remain the archive artifacts, `MILESTONES.md`, `.work/SPEC.md`, and the retained `ROADMAP.md` collapse
 </lifecycle_preflight>
 
 <evidence_contract>
@@ -66,7 +66,7 @@ Read the audit frontmatter and preserve:
 Shared closure rules:
 - `repo_only` completion may proceed with repo-local closure evidence only; do not invent `runtime` or `delivery` proof
 - `delivery_sensitive` completion must not proceed on code/prose-only evidence; the audit must already show required `code`, `test`, `runtime`, and `delivery` evidence with no missing required kinds
-- if the audit omits the evidence contract or still has missing required kinds, STOP and route back to `/gsdd-audit-milestone` or `/gsdd-plan-milestone-gaps` instead of silently closing the milestone
+- if the audit omits the evidence contract or still has missing required kinds, STOP and route back to `/gsdd-audit-milestone` or `/gsdd-plan` amend/extend mode instead of silently closing the milestone
 - release claim postures are inherited from audit:
   - `repo_closeout` permits repo-local milestone closure only and must not imply public support, delivery, runtime validation, generated-surface freshness, package publication, tags, or GitHub Releases
   - `runtime_validated_closeout` may name only the runtime or surface with explicit `runtime` evidence
@@ -74,7 +74,7 @@ Shared closure rules:
 - inherited `delivery_posture` and `release_claim_posture` must be compatible: `repo_closeout` and `runtime_validated_closeout` use `repo_only`; `delivery_supported_closeout` uses `delivery_sensitive`
 - waivers are valid only when they narrow the release claim or defer an unsupported claim. Deferrals must name the unsupported claim, missing evidence kind(s), and later workflow or milestone candidate when known. STOP if a waiver preserves a stronger claim while required evidence is missing.
 - STOP if `release_claim_contract.unsupported_claims` remain without downgrade or deferral, if unsupported claims, invalid waivers, or failed contradiction checks remain, or if completion wording would claim more than the audit evidence supports. Failed contradiction checks are claim-scoped: generated-surface failures block only runtime/generated freshness claims, not unrelated `repo_closeout` completion.
-- local-only `.planning/` proof can support repo closeout, but cannot become public release proof by itself.
+- local-only `.work/` proof can support repo closeout, but cannot become public release proof by itself.
 </evidence_contract>
 
 <process>
@@ -93,7 +93,7 @@ Check:
 
 STOP without archiving. Route to the narrowest corrective workflow instead:
 1. **Run audit first** — `/gsdd-audit-milestone` if audit is missing, stale, or missing required release-claim schema.
-2. **Close gaps first** — `/gsdd-plan-milestone-gaps` if audit found gaps or the release claim outruns available evidence.
+2. **Close gaps first** — `/gsdd-plan` amend/extend mode if audit found gaps or the release claim outruns available evidence.
 3. **Abort** — stop without archiving if the user does not want corrective work now.
 
 **If all phases complete, audit passed, the audit evidence contract is satisfied, and the inherited release claim contract has no unsupported stronger claims:** Proceed.
@@ -122,7 +122,7 @@ Present 4-8 accomplishments for review. Trim or adjust with user before writing
 
 ## 5. Archive Roadmap
 
-Create `.planning/milestones/v[X.Y]-ROADMAP.md` with full milestone details:
+Create `.work/milestones/v[X.Y]-ROADMAP.md` with full milestone details:
 
 ```markdown
 # Milestone v[X.Y]: [Name]
@@ -173,19 +173,19 @@ Plans:
 
 ---
 
-*For current project status, see `.planning/ROADMAP.md`*
+*For current project status, see `.work/ROADMAP.md`*
 ```
 
 ## 6. Archive Requirements
 
-Create `.planning/milestones/v[X.Y]-REQUIREMENTS.md`:
+Create `.work/milestones/v[X.Y]-REQUIREMENTS.md`:
 
 ```markdown
 # Requirements Archive: v[X.Y] Milestone
 
 **Archived:** [date]
 **Milestone:** [name]
-**Source:** `.planning/SPEC.md` requirements section at milestone completion
+**Source:** `.work/SPEC.md` requirements section at milestone completion
 
 ---
 
@@ -211,17 +211,17 @@ Create `.planning/milestones/v[X.Y]-REQUIREMENTS.md`:
 
 ---
 
-*Source: `.planning/SPEC.md` as of [date]*
+*Source: `.work/SPEC.md` as of [date]*
 *Next milestone requirements: defined via `/gsdd-new-milestone`*
 ```
 
 ## 7. Move Audit File
 
-If `.planning/v[X.Y]-MILESTONE-AUDIT.md` exists, note its location in the MILESTONES.md entry. (Leave the file in `.planning/` — it is already in the gitignored planning directory. No move required unless you prefer to co-locate it with the other archives.)
+If `.work/v[X.Y]-MILESTONE-AUDIT.md` exists, note its location in the MILESTONES.md entry. (Leave the file in `.work/` — it is already in the gitignored planning directory. No move required unless you prefer to co-locate it with the other archives.)
 
 ## 8. Update MILESTONES.md
 
-Append an entry to `.planning/MILESTONES.md`:
+Append an entry to `.work/MILESTONES.md`:
 
 ```markdown
 ## ✅ v[X.Y] — [Name] ([date])
@@ -239,8 +239,8 @@ Append an entry to `.planning/MILESTONES.md`:
 3. [Accomplishment 3]
 4. [Accomplishment 4]
 
-**Archive:** `.planning/milestones/v[X.Y]-ROADMAP.md`
-**Requirements:** `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
+**Archive:** `.work/milestones/v[X.Y]-ROADMAP.md`
+**Requirements:** `.work/milestones/v[X.Y]-REQUIREMENTS.md`
 **Suggested tag:** `v[X.Y]` (advisory; omit or mark not created unless git confirms it exists)
 ```
 
@@ -259,7 +259,7 @@ Update SPEC.md to reflect the completed milestone:
 
 - **Milestone:** v[X.Y] [Name] — COMPLETED [date]
 - **Phases:** [N]–[M] complete, all requirements verified ([N]/[N]), [test count] tests passing
-- **Archive:** `.planning/milestones/v[X.Y]-ROADMAP.md`
+- **Archive:** `.work/milestones/v[X.Y]-ROADMAP.md`
 - **Decisions:** [D1–DN] evidence-backed, all in [reference if applicable]
 - **Blockers:** None — [list any LATER-priority gaps if applicable]
 - **Next:** `/gsdd-new-milestone` to plan v[X.next] work
@@ -288,7 +288,7 @@ Replace the active milestone phases in ROADMAP.md with a collapsed `<details>` b
 - [x] **Phase [N+1]: [Name]** — completed [date]
 [...]
 
-Full details: [`.planning/milestones/v[X.Y]-ROADMAP.md`](milestones/v[X.Y]-ROADMAP.md)
+Full details: [`.work/milestones/v[X.Y]-ROADMAP.md`](milestones/v[X.Y]-ROADMAP.md)
 
 </details>
 
@@ -315,9 +315,9 @@ Advisory: Tag this milestone in git:
 - [ ] Version confirmed
 - [ ] Stats gathered from SUMMARY.md files and git
 - [ ] Accomplishments extracted and reviewed
-- [ ] `.planning/milestones/v[X.Y]-ROADMAP.md` created with full phase details
-- [ ] `.planning/milestones/v[X.Y]-REQUIREMENTS.md` created with all requirement statuses
-- [ ] `.planning/MILESTONES.md` updated with new entry
+- [ ] `.work/milestones/v[X.Y]-ROADMAP.md` created with full phase details
+- [ ] `.work/milestones/v[X.Y]-REQUIREMENTS.md` created with all requirement statuses
+- [ ] `.work/MILESTONES.md` updated with new entry
 - [ ] SPEC.md Must Have requirements moved to Validated section
 - [ ] SPEC.md Current State updated to reflect completed status
 - [ ] ROADMAP.md collapsed with `<details>` block pointing to archive
@@ -333,11 +333,11 @@ Report to the user what was archived, then present the next step:
 **Completed:** Milestone v[X.Y] [Name] archived.
 
 Archived:
-- `.planning/milestones/v[X.Y]-ROADMAP.md` — full phase details
-- `.planning/milestones/v[X.Y]-REQUIREMENTS.md` — requirements at milestone completion
-- `.planning/MILESTONES.md` — updated milestone history
-- `.planning/SPEC.md` — requirements evolved, current state updated
-- `.planning/ROADMAP.md` — active phases collapsed to `<details>`
+- `.work/milestones/v[X.Y]-ROADMAP.md` — full phase details
+- `.work/milestones/v[X.Y]-REQUIREMENTS.md` — requirements at milestone completion
+- `.work/MILESTONES.md` — updated milestone history
+- `.work/SPEC.md` — requirements evolved, current state updated
+- `.work/ROADMAP.md` — active phases collapsed to `<details>`
 
 **Next step:** `/gsdd-new-milestone` — start the next milestone cycle