feat: update downstream skills, hook, and docs for per-unit specs

DESIGN.md

@@ -50,7 +50,7 @@ Persistent record of systemic issues that per-change gates miss: architecture de
 |-------|---------|----------------|
 | `sw-init` | Project setup | Ask, detect, configure. Creates constitution + charter |
 | `sw-design` | Interactive solution architecture | Research, design, adversarial critic, assumption surfacing, user approval throughout |
-| `sw-plan` | Decompose + spec | Reads design artifacts, breaks into work units, testable acceptance criteria |
+| `sw-plan` | Decompose + spec | Per-unit specs with individual user approval. Self-contained unit directories |
 | `sw-build` | TDD implementation | Tester → executor delegation. Context doc travels with agents |
 | `sw-verify` | Interactive quality gates | Shows findings, not badges. Orchestrates gate skills in dependency order |
 | `sw-ship` | Strategy-aware merge | PR with evidence-mapped body |
@@ -83,10 +83,11 @@ Solution architecture and implementation planning are separate skills:
 - Adaptive phases: small requests skip critic, large requests get full treatment.
 - Design is per-request (shared across work units). Change requests via `/sw-design <changes>`.
 
-**sw-plan** (decomposition + specs):
+**sw-plan** (decomposition + per-unit specs):
 - Reads design artifacts. Decomposes into work units if large.
-- Writes testable acceptance criteria (`spec.md`) and task breakdown (`plan.md`).
-- May append to `context.md` but never overwrites design research.
+- For multi-unit work: creates per-unit directories (`units/{unit-id}/`) each containing self-contained `spec.md`, `plan.md`, and curated `context.md`. Each unit's spec is individually reviewed and approved via `AskUserQuestion`.
+- For single-unit work: writes `spec.md` and `plan.md` at the work root (flat layout, unchanged).
+- Parent `context.md` (design research) is never overwritten.
 
 ### Verify Skill Gates
 
@@ -198,7 +199,19 @@ Runtime state (created by init):
 ├── AUDIT.md          # Codebase health findings (optional)
 ├── state/
 │   └── workflow.json # Current state
-└── work/             # Work unit artifacts (specs, evidence, plans)
+└── work/             # Work unit artifacts
+    └── {work-id}/
+        ├── design.md       # Solution design (design-level)
+        ├── context.md      # Research findings (design-level)
+        ├── assumptions.md  # Design assumptions (design-level)
+        ├── spec.md         # Single-unit: acceptance criteria here
+        ├── plan.md         # Single-unit: task breakdown here
+        └── units/          # Multi-unit: per-unit directories
+            └── {unit-id}/
+                ├── spec.md     # Unit-scoped acceptance criteria
+                ├── plan.md     # Unit-scoped task breakdown
+                ├── context.md  # Curated subset of parent context
+                └── evidence/   # Gate evidence for this unit
 ```
 
 ## History

hooks/session-start.mjs

@@ -59,13 +59,17 @@ try {
       }
     }
 
+    const workDir = work.workDir || `.specwright/work/${work.id}`;
+    const unitLine = work.unitId ? `  Active Unit: ${work.unitId}\n` : '';
+
     const summary = [
       `Specwright: Work in progress`,
       `  Unit: ${work.id} (${work.status})`,
+      unitLine ? unitLine.trimEnd() : null,
       `  Progress: ${completed}/${total} tasks`,
       `  Gates: ${gatesSummary}`,
-      `  Spec: .specwright/work/${work.id}/spec.md`,
-      `  Plan: .specwright/work/${work.id}/plan.md`,
+      `  Spec: ${workDir}/spec.md`,
+      `  Plan: ${workDir}/plan.md`,
       lockWarning,
       continuationContent,
     ].filter(Boolean).join('\n');

skills/gate-build/SKILL.md

@@ -25,7 +25,7 @@ if the code doesn't build or tests don't pass, nothing else matters.
 
 ## Outputs
 
-- Evidence file at `.specwright/work/{id}/evidence/build-report.md`
+- Evidence file at `{currentWork.workDir}/evidence/build-report.md`
 - Gate status update in workflow.json: PASS, FAIL, or ERROR
 - Console output showing results inline (users see findings, not just badges)
 

skills/gate-security/SKILL.md

@@ -28,7 +28,7 @@ judgment for analysis that tools can't do.
 
 ## Outputs
 
-- Evidence file at `.specwright/work/{id}/evidence/security-report.md`
+- Evidence file at `{currentWork.workDir}/evidence/security-report.md`
 - Gate status in workflow.json
 - Findings shown inline with severity, location, and remediation
 

skills/gate-spec/SKILL.md

@@ -24,13 +24,13 @@ that closes the loop.
 
 ## Inputs
 
-- `.specwright/work/{id}/spec.md` -- acceptance criteria
+- `{currentWork.workDir}/spec.md` -- acceptance criteria
 - `.specwright/state/workflow.json` -- current work unit
 - The codebase (implementation and tests)
 
 ## Outputs
 
-- Evidence file at `.specwright/work/{id}/evidence/spec-compliance.md`
+- Evidence file at `{currentWork.workDir}/evidence/spec-compliance.md`
 - Compliance matrix: each criterion → implementation ref + test ref + status
 - Gate status in workflow.json
 

skills/gate-tests/SKILL.md

@@ -29,7 +29,7 @@ test quality, not just pass/fail.
 
 ## Outputs
 
-- Evidence file at `.specwright/work/{id}/evidence/test-quality.md`
+- Evidence file at `{currentWork.workDir}/evidence/test-quality.md`
 - Gate status in workflow.json
 - Findings organized by category with specific file:line references
 

skills/gate-wiring/SKILL.md

@@ -29,7 +29,7 @@ can still be wired incorrectly.
 
 ## Outputs
 
-- Evidence file at `.specwright/work/{id}/evidence/wiring-report.md`
+- Evidence file at `{currentWork.workDir}/evidence/wiring-report.md`
 - Gate status in workflow.json
 - Findings with specific file:line references and remediation
 

skills/sw-learn/SKILL.md

@@ -27,8 +27,8 @@ work benefits.
 ## Inputs
 
 - `.specwright/state/workflow.json` -- current work unit (should be shipped)
-- `.specwright/work/{id}/evidence/` -- gate evidence files
-- `.specwright/work/{id}/plan.md` -- architecture decisions
+- `{currentWork.workDir}/evidence/` -- gate evidence files
+- `{currentWork.workDir}/plan.md` -- architecture decisions
 - `.specwright/CONSTITUTION.md` -- existing practices
 - `.specwright/learnings/` -- prior work unit learnings (for retrospective)
 - Git log for the work unit's commits

skills/sw-status/SKILL.md

@@ -38,12 +38,14 @@ next. If they're stuck, give them a way out with `--reset`.
 **Display (HIGH freedom):**
 - Read workflow.json and format it clearly for the user.
 - Show gate results with freshness (e.g., "PASS (12 min ago)").
-- If `workUnits` array exists, show the full queue:
+- If `currentWork.unitId` is present, show the active unit ID in the current work display.
+- If `workUnits` array exists, show the full queue with `workDir` paths:
   ```
   Work Units:
-    1. [SHIPPED] stage-boundary-enforcement
-    2. [BUILDING] git-operations-overhaul  ← current
-    3. [PENDING] state-enhancements
+    1. [SHIPPED] stage-boundary-enforcement (.specwright/work/{id}/units/stage-boundary-enforcement/)
+    2. [BUILDING] git-operations-overhaul (.specwright/work/{id}/units/git-operations-overhaul/)  ← current
+    3. [PLANNED] state-enhancements (.specwright/work/{id}/units/state-enhancements/)
+    4. [PENDING] final-cleanup (.specwright/work/{id}/units/final-cleanup/)
   ```
 - If no active work: say so and suggest `/sw-design`.
 - If work is complete: suggest `/sw-ship`.

skills/sw-verify/SKILL.md

@@ -27,12 +27,12 @@ and be able to discuss or override before proceeding to ship.
 
 - `.specwright/state/workflow.json` -- current work unit, previous gate results
 - `.specwright/config.json` -- `gates.enabled` list
-- `.specwright/work/{id}/spec.md` -- for spec compliance gate
+- `{currentWork.workDir}/spec.md` -- for spec compliance gate
 - Gate skill files in `skills/gate-*/SKILL.md`
 
 ## Outputs
 
-- Evidence files in `.specwright/work/{id}/evidence/`, one per gate
+- Evidence files in `{currentWork.workDir}/evidence/`, one per gate
 - `workflow.json` gates section updated; status set to `verifying` during run
 - Aggregate summary shown to user with all findings