gsdd-cli 0.27.0 → 0.29.0

package/distilled/workflows/execute.md

@@ -8,34 +8,34 @@ You follow the plan, verify before reporting completion, document deviations, an
 Load only the context needed for the next safe action. Use these tiers instead of rereading every possible file before implementation.
 
 ### mandatory_now
-Read before mutation: target `PLAN.md` frontmatter/current task/boundaries; bounded `.planning/SPEC.md` current state, active requirement IDs, and relevant constraints; `.planning/ROADMAP.md` phase goal/status/success criteria; immediately prior `.planning/phases/*-SUMMARY.md` `<judgment>` when present; and the preflight result from `<lifecycle_preflight>`.
-If no immediately prior SUMMARY `<judgment>` exists, check whether `.planning/.continue-here.bak` exists before mutation. If it exists, read its `<judgment>`, honor `<anti_regression>`, `<active_constraints>`, and `<decision_posture>`, then run `node .planning/bin/gsdd.mjs file-op delete .planning/.continue-here.bak --missing ok` (workflow-owned auto-clean).
+Read before mutation: target `PLAN.md` frontmatter/current task/boundaries; bounded `.work/SPEC.md` current state, active requirement IDs, and relevant constraints; `.work/ROADMAP.md` phase goal/status/success criteria; immediately prior `.work/phases/*-SUMMARY.md` `<judgment>` when present; and the preflight result from `<lifecycle_preflight>`.
+If no immediately prior SUMMARY `<judgment>` exists, check whether `.work/.continue-here.bak` exists before mutation. If it exists, read its `<judgment>`, honor `<anti_regression>`, `<active_constraints>`, and `<decision_posture>`, then run `node .work/bin/gsdd.mjs file-op delete .work/.continue-here.bak --missing ok` (workflow-owned auto-clean).
 
 ### task_scoped
 Read before editing each task, not all at startup: current task `<files>` entries, relevant source needed for current symbols/callers/tests/generated surfaces, and focused neighboring references found by targeted search.
 
 ### reference_only
-Consult deeper `.planning/SPEC.md` and `.planning/ROADMAP.md` sections only for the specific decision, requirement, or status being validated.
+Consult deeper `.work/SPEC.md` and `.work/ROADMAP.md` sections only for the specific decision, requirement, or status being validated.
 
 ### deferred_or_conditional
 Read only when the current task or a deviation needs them: older phase summaries and broader historical context beyond the mandatory-now handoff.
 </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 implementing or mutating any lifecycle artifact, run:
-- `node .planning/bin/gsdd.mjs lifecycle-preflight execute {phase_num} --expects-mutation phase-status`
+- `node .work/bin/gsdd.mjs lifecycle-preflight execute {phase_num} --expects-mutation phase-status`
 If the preflight result is `blocked`, STOP and surface the blocker instead of inferring eligibility from workflow-local prose.
 
 Treat the preflight as an authorization seam over shared repo truth only:
 - it may authorize or reject execution
-- it does not mutate `.planning/ROADMAP.md` by itself
-- owned writes remain execution artifacts, and ROADMAP mutation stays explicit in `<state_updates>` via `node .planning/bin/gsdd.mjs phase-status`
+- it does not mutate `.work/ROADMAP.md` by itself
+- owned writes remain execution artifacts, and ROADMAP mutation stays explicit in `<state_updates>` via `node .work/bin/gsdd.mjs phase-status`
 </lifecycle_preflight>
-<control_map_check>Before code mutation, run `node .planning/bin/gsdd.mjs control-map --json` when available. Confirm the intended execution surface, dirty buckets, sibling/detached worktrees, and overlapping write-set risk. If it reports stale annotations, dubious git access, dirty out-of-plan canonical files, or unannotated dirty sibling worktrees, stop or ask for explicit acknowledgement before broad writes. Local annotations are intent hints only; computed repo/worktree truth stays primary.
+<control_map_check>Before code mutation, run `node .work/bin/gsdd.mjs control-map --json` when available. Confirm the intended execution surface, dirty buckets, sibling/detached worktrees, and overlapping write-set risk. If it reports stale annotations, dubious git access, dirty out-of-plan canonical files, or unannotated dirty sibling worktrees, stop or ask for explicit acknowledgement before broad writes. Local annotations are intent hints only; computed repo/worktree truth stays primary.
 </control_map_check>
 <runtime_contract>
 Execution uses the same `Runtime` and `Assurance` types as planning and verification.
@@ -55,7 +55,7 @@ If plan runtime/assurance is missing, use `status: unknown`.
 A phase often contains multiple plans. When invoked at the phase level (no specific plan provided), run this orchestration step first.
 
 ### Discover Plans and Group by Wave
-1. Scan `.planning/phases/{phase_dir}/` for all `*-PLAN.md` files.
+1. Scan `.work/phases/{phase_dir}/` for all `*-PLAN.md` files.
 2. For each plan, read its frontmatter `wave` field (default: `wave: 1` if absent).
 3. Group plans by wave number. Collect the set of distinct wave numbers and sort them ascending.
 4. Check for `*-SUMMARY.md` files — plans that already have a matching SUMMARY are complete; skip them.
@@ -107,7 +107,7 @@ For each task in the plan, follow this loop:
 
 ### Frontmatter And Task Semantics
 The executor consumes the plan schema defined by `/gsdd-plan`:
-- frontmatter keys: `phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `must_haves`, `tdd`
+- frontmatter keys: `phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `browser_proof_required`, `browser_proof_rationale`, `must_haves`, `tdd`
 - task types:
   - `type="auto"` - proceed without pausing
   - `type="checkpoint:user"` - stop for a required user decision or human-only step
@@ -119,8 +119,8 @@ Checkpoint tasks are contract boundaries. Continuing past one silently breaks th
 ### Implementation Rules
 - Follow the `<action>` precisely.
 - If a task references existing code, read it first and match existing patterns.
-- If you are unsure about something, check `.planning/SPEC.md` decisions first, then ask if still unclear.
-- Do not run destructive git, broad cleanup, or file deletion actions without explicit human approval, except explicitly named workflow-owned housekeeping commands such as `.planning/.continue-here.bak` auto-clean.
+- If you are unsure about something, check `.work/SPEC.md` decisions first, then ask if still unclear.
+- Do not run destructive git, broad cleanup, or file deletion actions without explicit human approval, except explicitly named workflow-owned housekeeping commands such as `.work/.continue-here.bak` auto-clean.
 
 ### Change-Impact Discipline
 Before modifying any existing behavior, run a targeted ripple check for the current task:
@@ -164,11 +164,10 @@ Before reporting a task complete:
 - if an API change is involved, hit the endpoint or targeted integration path
 - A task is not complete because code was written. It is complete when the intended verification path actually passes.
 
-### UI Proof Execution
-If the plan defines non-empty `ui_proof_slots`, create or update the observed UI proof bundle before claiming completion; required 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`.
-Use `agent-browser` as the default live UI proof path. Record the planned route/state open, interactive snapshots/refs when interaction is part of the claim, changed-flow interaction, screenshots for planned viewport(s), and relevant console/network observations. If `agent-browser` is unavailable, record the availability constraint and the closest project-native interactive browser fallback in the proof bundle instead of silently treating the fallback as the default path. If the repo already has Playwright tests or a package script wrapping them, run the relevant targeted test as canonical repeatable regression evidence; keep `agent-browser` as complementary runtime proof. Use Playwright scripting only for checks `agent-browser` cannot cover cleanly, such as JS-disabled, structured console, or multi-context verification. Do not install Playwright, Cypress, Cucumber, Storybook, browser MCP, CI, or visual-regression tooling by default. Screenshots, traces, videos, reports, accessibility scans, Gherkin, visual diffs, and manual notes map onto existing evidence kinds, not new evidence kinds; reference raw artifacts by path/link instead of storing them inline.
-Each artifact entry must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports default to `local_only` and `safe_to_publish: false` unless explicitly sanitized. Use `gsdd ui-proof validate <path>` when bundle metadata exists, adding `--claim <...>` only when relying on the bundle for public, tracked, delivery, release, or publication proof. Visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, and privacy publication decisions require human evidence or explicit waiver; artifact count, source comments, AST/cAST findings, semantic search, and Semble-like retrieval are not proof. If evidence does not match the slot claim, route/state, observation, artifact path/manual step, privacy metadata, result, and claim limit, record proof debt, waiver, deferment, or reduced claim language rather than `satisfied` proof.
-Classify failed UI proof using existing gap/proof-debt language: `product_bug`, `missing_infra`, `flaky_harness`, or `ambiguous_spec`. Do not add new evidence kinds or result statuses for those causes.
+### Browser Proof Execution
+If the plan sets `browser_proof_required: true`, execute the `## Browser Proof Plan` before claiming completion. Record the exact `Plan:` artifact path plus route/state, viewport(s), runtime path, evidence kind, evidence command or narrowed no-command rationale, observations, artifact paths, privacy/safety note, result, and claim limit in the summary or a linked observation record.
+Use `agent-browser` as the default live browser proof path. Record the planned route/state open, interactive snapshots/refs when interaction is part of the claim, changed-flow interaction, screenshots for planned viewport(s), and relevant console/network observations. If `agent-browser` is unavailable, record the availability constraint and closest project-native interactive browser fallback instead of silently treating the fallback as the default path. If the repo already has Playwright tests or a package script wrapping them, run the relevant targeted test as canonical repeatable regression evidence; keep browser runtime observation as complementary proof. Use Playwright scripting only for checks `agent-browser` cannot cover cleanly, such as JS-disabled, structured console, or multi-context verification. Do not install Playwright, Cypress, Cucumber, Storybook, browser MCP, CI, or visual-regression tooling by default.
+Screenshots, traces, videos, reports, accessibility scans, Gherkin, visual diffs, and manual notes map onto existing evidence kinds, not new evidence kinds. Raw screenshots, traces, videos, DOM snapshots, and reports default to local-only and unsafe to publish unless explicitly sanitized. Visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, and privacy publication decisions require human evidence or explicit waiver; artifact count, source comments, AST/cAST findings, semantic search, and Semble-like retrieval are not proof. If evidence does not match the planned route/state, viewport, observation, artifact path/manual step, privacy note, result, and claim limit, record proof debt, waiver, deferment, or reduced claim language rather than satisfied proof. Use the failure-cause names in `distilled/references/proof-rules.md` when proof fails or is partial.
 
 ### Git Guidance
 
@@ -195,7 +194,7 @@ git commit -m "feat: wire users page to real route"
 
 Git rules:
 - **Repo and user conventions win first.** This table is a reference, not a mandate.
-- `.planning/config.json -> gitProtocol` is advisory only.
+- `.work/config.json -> gitProtocol` is advisory only.
 - **Stage only files listed in the plan's `files-modified` frontmatter.** Never use `git add .` or `git add -A`. If you need to stage a file not in `files-modified`, record it as a deviation.
 - **Wrong-branch check:** Before significant implementation begins, verify HEAD is not `main` or `master` if repo convention expects a feature branch; if it is, STOP and hard-warn the user before proceeding.
 - **Transition-safety warning pass:** Before significant implementation begins, inspect staged, unstaged, untracked, unpushed, PR-less, stale/spent, and mixed-scope branch signals. Warn on these conditions explicitly; ordinary delivery risk remains warning-level unless the current branch is clearly the wrong integration surface for the planned work.
@@ -279,7 +278,7 @@ If a task fails verification 3 times after fixes, STOP and report the failure to
 <state_updates>
 After completing all tasks in the plan:
 
-### 1. Update `.planning/SPEC.md` "Current State"
+### 1. Update `.work/SPEC.md` "Current State"
 Keep the update factual and compact:
 
 ```markdown
@@ -292,18 +291,18 @@ Keep the update factual and compact:
 
 ### 2. Update ROADMAP.md Phase Status
 Do not hand-edit the ROADMAP checkbox line. Use the status-aware helper instead:
-- Run `node .planning/bin/gsdd.mjs phase-status {N} in_progress` when implementation work has started or this plan completes.
-- Do NOT run `node .planning/bin/gsdd.mjs phase-status {N} done` from execute. Only verify may close a phase after writing a `status: passed` VERIFICATION.md.
+- Run `node .work/bin/gsdd.mjs phase-status {N} in_progress` when implementation work has started or this plan completes.
+- Do NOT run `node .work/bin/gsdd.mjs phase-status {N} done` from execute. Only verify may close a phase after writing a `status: passed` VERIFICATION.md.
 
-The helper owns the `[ ]` / `[-]` / `[x]` mutation for `.planning/ROADMAP.md`, including both the overview line and the matching `## Phase Details` `**Status**` line when both exist.
+The helper owns the `[ ]` / `[-]` / `[x]` mutation for `.work/ROADMAP.md`, including both the overview line and the matching `## Phase Details` `**Status**` line when both exist.
 
-### 3. Rebaseline Reviewed Planning State
-After `.planning/SPEC.md` and `phase-status` updates are complete and reviewed as intentional, run:
-- `node .planning/bin/gsdd.mjs session-fingerprint write`
-This is the explicit planning-state handoff. Do not rely on a no-op `phase-status` command to rebaseline SPEC drift.
+### 3. Confirm Reviewed Planning State
+After `.work/SPEC.md` and `phase-status` updates are complete and reviewed as intentional, run:
+- `node .work/bin/gsdd.mjs next --json`
+This is the explicit routing-state handoff. Do not rely on a no-op `phase-status` command to prove the next action reflects reviewed SPEC or ROADMAP changes.
 
 ### 4. Write Phase Summary
-Create `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md` with:
+Create `.work/phases/{phase_dir}/{plan_id}-SUMMARY.md` with:
 
 ```markdown
 ---
@@ -377,7 +376,7 @@ Write the structured sections honestly:
 Do not invent an inline PLAN task-state mutation scheme if the plan does not define one.
 Summary-driven progress tracking avoids silent drift between the plan contract and what execution actually completed.
 
-**MANDATORY: You MUST write SUMMARY.md to disk at `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md`. Output to conversation alone is NOT sufficient. If this file is not written to disk, execution is NOT complete.**
+**MANDATORY: You MUST write SUMMARY.md to disk at `.work/phases/{phase_dir}/{plan_id}-SUMMARY.md`. Output to conversation alone is NOT sufficient. If this file is not written to disk, execution is NOT complete.**
 </state_updates>
 
 <checkpoint_protocol>
@@ -414,9 +413,9 @@ For each completed task:
   [ ] Local verification passed
 
 For state updates:
-  [ ] .planning/SPEC.md "Current State" is accurate
+  [ ] .work/SPEC.md "Current State" is accurate
   [ ] ROADMAP.md status remains open (`[-]` if status was updated) until verification passes
-  [ ] `node .planning/bin/gsdd.mjs session-fingerprint write` ran after reviewed SPEC and phase-status updates
+  [ ] `node .work/bin/gsdd.mjs next --json` ran after reviewed SPEC and phase-status updates
   [ ] SUMMARY.md exists with `<checks>`, `<handoff>`, `<deltas>`, and `<judgment>` and reflects the actual work
 
 Overall:
@@ -435,21 +434,21 @@ Execution is done when all of these are true:
 - [ ] Deviation rules were followed
 - [ ] Mandatory-now context and task-scoped files read at the correct execution point
 - [ ] Authentication gates handled with the auth-gate protocol
-- [ ] `.planning/SPEC.md` current state is updated accurately
+- [ ] `.work/SPEC.md` current state is updated accurately
 - [ ] `ROADMAP.md` uses `[ ]`, `[-]`, `[x]` consistently and is not marked `[x]` by execute
-- [ ] `node .planning/bin/gsdd.mjs session-fingerprint write` was run after reviewed planning-state updates
+- [ ] `node .work/bin/gsdd.mjs next --json` was run after reviewed planning-state updates
 - [ ] `SUMMARY.md` is written
 - [ ] `SUMMARY.md` frontmatter records `runtime` and `assurance`
 - [ ] `SUMMARY.md` includes structured `<checks>`, `<handoff>`, `<deltas>`, and `<judgment>` sections
 - [ ] Self-check passed
-- [ ] Any git actions honor repo or user conventions and `.planning/config.json`
+- [ ] Any git actions honor repo or user conventions and `.work/config.json`
 </success_criteria>
 
 <completion>
 Report what was accomplished, then present the next step:
 ---
-**Completed:** Plan execution — created `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md`.
-**Next step:** Check `.planning/config.json` → `workflow.verifier`:
+**Completed:** Plan execution — created `.work/phases/{phase_dir}/{plan_id}-SUMMARY.md`.
+**Next step:** Check `.work/config.json` → `workflow.verifier`:
 - If `true`: run `/gsdd-verify` — verify that the phase goal was achieved
 - If `false` (or key missing): run `/gsdd-progress` — check status and route to the next phase
 

package/distilled/workflows/map-codebase.md

@@ -1,7 +1,7 @@
 <role>
 You are a Codebase Mapper Orchestrator. You analyze an existing codebase using 4 specialized mapper delegates, each focused on one dimension. The delegates write their documents directly -- you only coordinate, validate, and synthesize a bounded brownfield routing summary from their results.
 
-Output: `.planning/codebase/` with 4 structured documents about the codebase state.
+Output: `.work/codebase/` with 4 structured documents about the codebase state.
 </role>
 
 <when_to_use>
@@ -21,22 +21,22 @@ Do NOT use when:
 <load_context>
 ### 1. Read Config
 
-Read `.planning/config.json` to extract:
+Read `.work/config.json` to extract:
 - `parallelization` -- determines whether mappers run in parallel or sequentially
 - `commitDocs` -- determines whether to commit generated documents
 
-If `.planning/config.json` does not exist, assume `parallelization: true` and `commitDocs: false` (safe default -- do not commit potentially sensitive codebase documents without explicit opt-in).
+If `.work/config.json` does not exist, assume `parallelization: true` and `commitDocs: false` (safe default -- do not commit potentially sensitive codebase documents without explicit opt-in).
 </load_context>
 
 <check_existing>
 ### 2. Check Existing Maps
 
-Check whether `.planning/codebase/STACK.md`, `.planning/codebase/ARCHITECTURE.md`, `.planning/codebase/CONVENTIONS.md`, or `.planning/codebase/CONCERNS.md` already exist and contain content.
+Check whether `.work/codebase/STACK.md`, `.work/codebase/ARCHITECTURE.md`, `.work/codebase/CONVENTIONS.md`, or `.work/codebase/CONCERNS.md` already exist and contain content.
 
 **If maps exist, present the user with three options:**
 
 ```
-.planning/codebase/ already exists with these documents:
+.work/codebase/ already exists with these documents:
 [List files found with sizes]
 
 Options:
@@ -47,7 +47,7 @@ Options:
 
 Wait for user response.
 
-- **Refresh**: Delete all files in `.planning/codebase/`, continue to mapping step.
+- **Refresh**: Delete all files in `.work/codebase/`, continue to mapping step.
 - **Update**: Ask which documents to regenerate (STACK, ARCHITECTURE, CONVENTIONS, CONCERNS), then continue to mapping step with only the selected delegates.
 - **Skip**: End workflow. Inform user maps are unchanged.
 
@@ -83,55 +83,55 @@ Wait for user response.
 <mapping>
 ### 3. Spawn Mapper Delegates
 
-Ensure `.planning/codebase/` directory exists before spawning.
+Ensure `.work/codebase/` directory exists before spawning.
 
 **If `parallelization: true` and your platform supports parallel execution -- run all selected mappers in parallel.**
 **If `parallelization: false` or your platform lacks parallel execution -- run the same mappers sequentially.**
 
 ```
 Spawning codebase mappers...
-  -> Tech mapper     -> .planning/codebase/STACK.md
-  -> Arch mapper     -> .planning/codebase/ARCHITECTURE.md
-  -> Quality mapper  -> .planning/codebase/CONVENTIONS.md
-  -> Concerns mapper -> .planning/codebase/CONCERNS.md
+  -> Tech mapper     -> .work/codebase/STACK.md
+  -> Arch mapper     -> .work/codebase/ARCHITECTURE.md
+  -> Quality mapper  -> .work/codebase/CONVENTIONS.md
+  -> Concerns mapper -> .work/codebase/CONCERNS.md
 ```
 
 <delegate>
 Agent: TechMapper
-Parallel: (use parallelization value from .planning/config.json)
+Parallel: (use parallelization value from .work/config.json)
 Context: Current working directory. DO NOT share conversation history.
-Instruction: Read `.planning/templates/delegates/mapper-tech.md` for full task instructions. Follow them exactly.
-Output: `.planning/codebase/STACK.md`
+Instruction: Read `.work/templates/delegates/mapper-tech.md` for full task instructions. Follow them exactly.
+Output: `.work/codebase/STACK.md`
 Return: Routing summary to Orchestrator (100-200 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3. No static dumps. Never read .env contents.
 </delegate>
 
 <delegate>
 Agent: ArchMapper
-Parallel: (use parallelization value from .planning/config.json)
+Parallel: (use parallelization value from .work/config.json)
 Context: Current working directory. DO NOT share conversation history.
-Instruction: Read `.planning/templates/delegates/mapper-arch.md` for full task instructions. Follow them exactly.
-Output: `.planning/codebase/ARCHITECTURE.md`
+Instruction: Read `.work/templates/delegates/mapper-arch.md` for full task instructions. Follow them exactly.
+Output: `.work/codebase/ARCHITECTURE.md`
 Return: Routing summary to Orchestrator (100-200 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3. No static directory dumps. Never read .env contents.
 </delegate>
 
 <delegate>
 Agent: QualityMapper
-Parallel: (use parallelization value from .planning/config.json)
+Parallel: (use parallelization value from .work/config.json)
 Context: Current working directory. DO NOT share conversation history.
-Instruction: Read `.planning/templates/delegates/mapper-quality.md` for full task instructions. Follow them exactly.
-Output: `.planning/codebase/CONVENTIONS.md`
+Instruction: Read `.work/templates/delegates/mapper-quality.md` for full task instructions. Follow them exactly.
+Output: `.work/codebase/CONVENTIONS.md`
 Return: Routing summary to Orchestrator (100-200 tokens); full findings stay in the output artifact.
 Guardrails: Max Agent Hops = 3. Rules not inventories. Never read .env contents.
 </delegate>
 
 <delegate>
 Agent: ConcernsMapper
-Parallel: (use parallelization value from .planning/config.json)
+Parallel: (use parallelization value from .work/config.json)
 Context: Current working directory. DO NOT share conversation history.
-Instruction: Read `.planning/templates/delegates/mapper-concerns.md` for full task instructions. Follow them exactly. Hard stop if secrets found -- report immediately.
-Output: `.planning/codebase/CONCERNS.md`
+Instruction: Read `.work/templates/delegates/mapper-concerns.md` for full task instructions. Follow them exactly. Hard stop if secrets found -- report immediately.
+Output: `.work/codebase/CONCERNS.md`
 Return: Routing summary to Orchestrator (100-200 tokens); full findings stay in the output artifact. If secrets found, STOP and report immediately.
 Guardrails: Max Agent Hops = 3. Hard stop on secrets. Never read .env contents.
 </delegate>
@@ -163,7 +163,7 @@ These 4 documents are consumed by downstream GSDD workflows:
 
 After all mappers complete, verify:
 
-- [ ] All 4 documents exist in `.planning/codebase/` (L1: exists)
+- [ ] All 4 documents exist in `.work/codebase/` (L1: exists)
 - [ ] No document is empty or trivially short — each must exceed 20 non-empty lines (L2: substantive)
 - [ ] Each document contains actual file path references in backtick format — not generic advice (L2: specificity)
 - [ ] STACK.md names at least 2 concrete technologies with version information (L2: specificity)
@@ -180,7 +180,7 @@ If any check fails, note the specific failure and inform the user which document
 
 **CRITICAL SECURITY CHECK:** Scan all generated documents for accidentally leaked secrets before committing.
 
-Search `.planning/codebase/*.md` for these patterns (use your platform's search/grep capability):
+Search `.work/codebase/*.md` for these patterns (use your platform's search/grep capability):
 
 **Reference patterns (regex):**
 - `sk-[a-zA-Z0-9]{20,}` | `sk_live_[a-zA-Z0-9]+` | `sk_test_[a-zA-Z0-9]+` -- Stripe/OpenAI keys
@@ -218,11 +218,11 @@ Wait for user confirmation before continuing.
 <commit>
 ### 6. Commit (if configured)
 
-Read `commitDocs` from `.planning/config.json`.
+Read `commitDocs` from `.work/config.json`.
 
 **If `commitDocs: true`:** Commit the generated codebase documents.
 Suggested commit message: `docs: map existing codebase`
-Files: `.planning/codebase/*.md`
+Files: `.work/codebase/*.md`
 
 **If `commitDocs: false`:** Skip commit. Documents remain local-only.
 </commit>
@@ -231,7 +231,7 @@ Files: `.planning/codebase/*.md`
 Report to the user what was accomplished, then present the next step:
 
 ---
-**Completed:** Codebase mapping — 4 documents written to `.planning/codebase/` (STACK.md, ARCHITECTURE.md, CONVENTIONS.md, CONCERNS.md).
+**Completed:** Codebase mapping — 4 documents written to `.work/codebase/` (STACK.md, ARCHITECTURE.md, CONVENTIONS.md, CONCERNS.md).
 
 **Brownfield routing summary:** Synthesize this directly from the 4 generated documents before recommending the next workflow.
 - Safest next change lane — which module or surface looks cheapest and safest to modify first
@@ -247,14 +247,14 @@ Use only the 4 generated documents for this synthesis. Do NOT create a fifth per
 
 Also available:
 - `/gsdd-map-codebase` — re-map if results need refinement
-- Review specific file: read `.planning/codebase/STACK.md`
+- Review specific file: read `.work/codebase/STACK.md`
 
 Consider clearing context before starting the next workflow for best results.
 ---
 </completion>
 
 <success_criteria>
-- `.planning/codebase/` directory exists with 4 documents
+- `.work/codebase/` directory exists with 4 documents
 - All selected mapper delegates were spawned (parallel or sequential per config)
 - Delegates wrote documents directly (orchestrator did not receive document contents)
 - Security scan completed -- no secrets in generated documents

package/distilled/workflows/new-milestone.md

@@ -7,8 +7,8 @@ Scope boundary: you produce updated SPEC.md requirements and a new set of phases
 </role>
 
 <prerequisites>
-`.planning/SPEC.md` must exist (project has been initialized and at least one milestone shipped).
-`.planning/MILESTONES.md` must exist (at least one milestone was completed and archived).
+`.work/SPEC.md` must exist (project has been initialized and at least one milestone shipped).
+`.work/MILESTONES.md` must exist (at least one milestone was completed and archived).
 
 If SPEC.md is missing, the project has not been initialized — run `/gsdd-new-project` instead.
 If MILESTONES.md is missing, no milestone has been completed — complete the current milestone first with `/gsdd-complete-milestone`.
@@ -17,21 +17,21 @@ If MILESTONES.md is missing, no milestone has been completed — complete the cu
 <load_context>
 Before starting, read these files:
 
-1. `.planning/SPEC.md` — project identity, core value, validated requirements, constraints, decisions
-2. `.planning/MILESTONES.md` — what shipped previously, last milestone version and date
-3. `.planning/ROADMAP.md` — collapsed milestone phases, current phase numbering (to determine where to continue)
-4. `.planning/config.json` — `workflow.research`, `researchDepth`, `gitProtocol`
-5. `.planning/brownfield-change/CHANGE.md`, `.planning/brownfield-change/HANDOFF.md`, and `.planning/brownfield-change/VERIFICATION.md` when an active bounded change is being widened into the next milestone
+1. `.work/SPEC.md` — project identity, core value, validated requirements, constraints, decisions
+2. `.work/MILESTONES.md` — what shipped previously, last milestone version and date
+3. `.work/ROADMAP.md` — collapsed milestone phases, current phase numbering (to determine where to continue)
+4. `.work/config.json` — `workflow.research`, `researchDepth`, `gitProtocol`
+5. `.work/brownfield-change/CHANGE.md`, `.work/brownfield-change/HANDOFF.md`, and `.work/brownfield-change/VERIFICATION.md` when an active bounded change is being widened into the next milestone
 </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 presenting the last milestone or gathering new milestone goals, run:
 
-- `node .planning/bin/gsdd.mjs lifecycle-preflight new-milestone`
+- `node .work/bin/gsdd.mjs lifecycle-preflight new-milestone`
 
 If the preflight result is `blocked`, STOP and report the blocker instead of inferring milestone-start eligibility from workflow-local prose.
 
@@ -52,7 +52,7 @@ If milestone truth on disk is local-only or AI-generated draft truth, or if the
 </integration_surface_check>
 
 <brownfield_widening_inputs>
-If `.planning/brownfield-change/CHANGE.md` exists, treat invocation of `/gsdd-new-milestone` as an explicit widen request for that active bounded change.
+If `.work/brownfield-change/CHANGE.md` exists, treat invocation of `/gsdd-new-milestone` as an explicit widen request for that active bounded change.
 
 Before gathering new milestone goals, read and preserve:
 - `CHANGE.md` for the current goal, scope, done-when, next action, and declared write scope
@@ -66,7 +66,7 @@ Do not force the user to rediscover this context and do not create a new promoti
 
 ## 1. Present What Shipped Last
 
-Read `.planning/MILESTONES.md`. Find the most recent milestone entry. Present it to the user:
+Read `.work/MILESTONES.md`. Find the most recent milestone entry. Present it to the user:
 
 ```
 Last milestone: v[X.Y] — [Name] (shipped [date])
@@ -87,8 +87,8 @@ Ask the user what the next milestone should focus on. Explore:
 
 If widening from an active brownfield change, start by presenting the preserved brownfield goal/scope/proof context and ask what now needs milestone-owned lifecycle state beyond that bounded lane.
 
-If a `.planning/MILESTONE-BRIEF.md` exists, use it as the input instead of asking. Note any assumptions inferred from the brief.
-(MILESTONE-BRIEF.md is an optional pre-written document with goals and scope for the next milestone — useful when the user wants to skip the interactive questioning. Create it manually in `.planning/` before running this workflow.)
+If a `.work/MILESTONE-BRIEF.md` exists, use it as the input instead of asking. Note any assumptions inferred from the brief.
+(MILESTONE-BRIEF.md is an optional pre-written document with goals and scope for the next milestone — useful when the user wants to skip the interactive questioning. Create it manually in `.work/` before running this workflow.)
 
 ## 3. Determine Version
 
@@ -121,11 +121,11 @@ Use `<delegate>` blocks to spawn researchers. Pass milestone context to each:
 ```
 <delegate>
 **Identity:** Researcher — Stack
-**Instruction:** Read `.planning/templates/roles/researcher.md`, then research what stack additions are needed for the new milestone capabilities.
+**Instruction:** Read `.work/templates/roles/researcher.md`, then research what stack additions are needed for the new milestone capabilities.
 
 **Milestone context:** [existing validated capabilities, new capabilities being added]
 **Question:** What library/framework additions are needed? What should NOT be added?
-**Output:** Write findings to `.planning/research/STACK.md`
+**Output:** Write findings to `.work/research/STACK.md`
 **Return:** 2-3 sentence summary of key findings
 </delegate>
 ```
@@ -219,7 +219,7 @@ Also update the Milestones list at the top of ROADMAP.md:
 Create placeholder directories for each new phase:
 
 ```
-.planning/phases/[NN]-[phase-name-kebab]/
+.work/phases/[NN]-[phase-name-kebab]/
 ```
 
 No files inside — the `/gsdd-plan` workflow populates them.
@@ -258,7 +258,7 @@ Update the `## Current State` section in SPEC.md:
 - [ ] Phase directories created
 </success_criteria>
 
-**MANDATORY: `.planning/SPEC.md` and `.planning/ROADMAP.md` must be updated on disk before this workflow is complete. If either write fails, STOP and report the failure. These are the handoff artifacts — without them, the next session cannot proceed.**
+**MANDATORY: `.work/SPEC.md` and `.work/ROADMAP.md` must be updated on disk before this workflow is complete. If either write fails, STOP and report the failure. These are the handoff artifacts — without them, the next session cannot proceed.**
 
 <completion>
 Report to the user what was created, then present the next step:
@@ -269,7 +269,7 @@ Report to the user what was created, then present the next step:
 Created:
 - [N] new requirements in `SPEC.md` Must Have section
 - [M] new phases in `ROADMAP.md` (Phases [start]–[end])
-- Phase directories in `.planning/phases/`
+- Phase directories in `.work/phases/`
 
 **Next step:** `/gsdd-plan [N]` — plan Phase [N]: [phase name]