@haposoft/cafekit 0.14.1 → 0.14.2

package/src/claude/rules/skill-domain-routing.md

@@ -1,88 +1,29 @@
 # Skill Domain Routing
 
-Use this decision tree to choose domain skills from the installed CafeKit skill set. This is advisory routing, not an automatic hook.
-
-## Frontend And UI
-
-```text
-User wants to...
-├── choose style, color, layout, UX, design system       -> /hapo:frontend-design
-├── build React/TypeScript UI components                 -> /hapo:frontend-development
-├── optimize React/Next.js performance or rerenders      -> /hapo:react-best-practices
-├── apply deep UI/UX intelligence, visual polish         -> /hapo:ui-ux-pro-max
-└── test UI in browser                                   -> /hapo:web-testing or /hapo:agent-browser
-```
-
-Use `/hapo:react-best-practices` for performance/re-render patterns. Use `/hapo:frontend-development` for normal implementation.
-
-## Backend, Data, And Infrastructure
-
-```text
-User wants to...
-├── API, service, auth, database-backed feature          -> /hapo:backend-development
-├── deployment, Docker, Kubernetes, Cloudflare, CI/CD     -> /hapo:devops
-└── mobile apps, iOS, Android, React Native, Flutter     -> /hapo:mobile-development
-```
-
-## Codebase Understanding
-
-```text
-User wants to...
-├── answer questions from source code/docs/specs/config    -> /hapo:question
-├── find files, locate code, scan project structure       -> /hapo:inspect
-├── diagnose an error or failing check                    -> /hapo:debug
-├── understand possible side effects                      -> /hapo:inspect
-└── compare external approaches or best practices         -> /hapo:research
-```
-
-Local source truth comes from `/hapo:inspect`; external/current knowledge comes from `/hapo:research`.
-
-## Documentation
-
-```text
-User wants to...
-├── ask/answer documentation questions from source         -> /hapo:question
-├── create missing project docs                           -> /hapo:docs --init
-├── update docs after source changes                      -> /hapo:docs --update
-├── summarize codebase quickly                            -> /hapo:docs --summarize
-├── reconstruct as-is docs from legacy source code        -> /hapo:docs --reconstruct <scope>
-└── create a future feature spec                          -> /hapo:specs
-```
-
-Keep as-is reconstruction separate from future requirements. Reconstructed docs document current behavior; specs define requested changes.
-
-## Testing And Browser
-
-```text
-User wants to...
-├── run test suites, coverage, scoped verification        -> /hapo:test
-├── E2E/unit/integration/load/security/a11y strategy      -> /hapo:web-testing
-├── drive a browser with snapshots or Browserbase         -> /hapo:agent-browser
-└── Chrome DevTools/Puppeteer evidence                    -> /hapo:chrome-devtools
-```
-
-## Documents And Media
-
-```text
-User wants to...
-├── PowerPoint/slides                                     -> /hapo:pptx
-├── Word documents                                        -> /hapo:docx
-├── PDFs                                                  -> /hapo:pdf
-├── spreadsheets/CSV/XLSX                                 -> /hapo:xlsx
-└── image/audio/video/document multimodal analysis        -> /hapo:ai-multimodal
-```
-
-## Git And Release
-
-```text
-User wants to...
-├── commit, branch, tag, push, release prep               -> /hapo:git
-└── review before release                                 -> /hapo:code-review
-```
-
-## Usage Notes
-
-- Read the selected skill's `SKILL.md` before acting.
-- Do not activate a skill only because one keyword appears. Use the whole user intent.
-- If a task spans multiple domains, name the primary skill and mention the secondary skill in the plan.
-- If no domain skill fits, use the core CafeKit workflow in `skill-workflow-routing.md`.
+Advisory routing for installed domain skills (not an automatic hook). Read the selected skill's `SKILL.md` before acting.
+
+| Domain / intent | Skill |
+|---|---|
+| answer questions from source code/docs/specs/config | `/hapo:question` |
+| file discovery, structure, blast radius | `/hapo:inspect` |
+| style / layout / design system | `/hapo:frontend-design` |
+| React/TypeScript UI implementation | `/hapo:frontend-development` |
+| React/Next performance / re-renders | `/hapo:react-best-practices` |
+| deep UI/UX polish | `/hapo:ui-ux-pro-max` |
+| API, service, auth, database | `/hapo:backend-development` |
+| deploy / Docker / K8s / Cloudflare / CI | `/hapo:devops` |
+| mobile (RN / Flutter / iOS / Android) | `/hapo:mobile-development` |
+| docs init / update / summarize | `/hapo:docs --init` / `--update` / `--summarize` |
+| as-is reconstruction from legacy code | `/hapo:docs --reconstruct <scope>` |
+| future feature requirements | `/hapo:specs` |
+| run suites / scoped verification | `/hapo:test` |
+| E2E / load / a11y strategy | `/hapo:web-testing` |
+| browser snapshots / Browserbase | `/hapo:agent-browser` |
+| Chrome DevTools evidence | `/hapo:chrome-devtools` |
+| diagnose error / CI failure | `/hapo:debug` |
+| external best practices / tool compare | `/hapo:research` |
+| pptx / docx / pdf / xlsx / multimodal | `/hapo:pptx` / `docx` / `pdf` / `xlsx` / `ai-multimodal` |
+| commit / branch / release prep | `/hapo:git` |
+| review before release | `/hapo:code-review` |
+
+Pick one primary domain skill; name a secondary only when it changes execution. If none fit, use `skill-workflow-routing.md`.

package/src/claude/rules/skill-workflow-routing.md

@@ -4,92 +4,21 @@ Use this rule instead of automatic prompt routing. Read the user's intent, choos
 
 Do not inject or force a skill when the user explicitly asks for a direct answer, a specific command, or a different workflow.
 
-## Core Specification Workflow
+Claude Code selects skills from frontmatter descriptions; trust it for clear intents.
 
-```text
-/hapo:question -> /hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
-```
-
-| User intent | Suggested start |
-|---|---|
-| ask about source code, docs, specs, config, dependencies, or external/current technical facts | `/hapo:question` |
-| vague request, missing acceptance criteria, unclear scope, stakeholder questions | ask one clarification or use `/hapo:brainstorm` |
-| unclear idea, possible approaches, scope tradeoffs | `/hapo:brainstorm` |
-| create requirements, design, task breakdown, validate spec | `/hapo:specs` |
-| implement an approved spec or a specific task file | `/hapo:develop` |
-| run tests, QA, runtime verification | `/hapo:test` |
-| review code quality, security, regressions, maintainability | `/hapo:code-review` |
-| commit, tag, push, branch, release prep | `/hapo:git` |
-
-## Bug And Incident Workflow
-
-```text
-/hapo:debug -> /hapo:hotfix -> /hapo:test -> /hapo:code-review
-```
-
-| User intent | Suggested start |
-|---|---|
-| diagnose why something fails, find root cause, inspect CI/logs | `/hapo:debug` |
-| fix a known bug after diagnosis, urgent regression, production issue | `/hapo:hotfix` |
-| verify the fix and affected behavior | `/hapo:test` |
-| check side effects before closeout | `/hapo:code-review` |
-
-`/hapo:debug` is diagnostic-only. Do not edit product code there. Use `/hapo:hotfix` when the user asks to fix.
-
-## Existing System Documentation Workflow
-
-```text
-/hapo:inspect -> /hapo:docs --reconstruct -> human review -> /hapo:specs -> /hapo:develop
-```
-
-| User intent | Suggested start |
-|---|---|
-| understand source structure or locate implementation areas | `/hapo:inspect` |
-| rebuild as-is docs/requirements from a legacy codebase | `/hapo:docs --reconstruct <scope>` |
-| update normal project docs | `/hapo:docs --update` |
-| initialize missing docs | `/hapo:docs --init` |
-| summarize a codebase without full docs work | `/hapo:docs --summarize` |
-
-Do not turn reconstructed docs directly into implementation. Human review must approve the as-is docs before `/hapo:specs` defines future changes.
-
-## Research And Analysis Workflow
+## Core chain
 
 ```text
-/hapo:inspect -> /hapo:research
+/hapo:question -> /hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
 ```
 
-| User intent | Suggested start |
-|---|---|
-| file discovery, codebase structure, source scouting | `/hapo:inspect` |
-| affected files, blast radius, dependency impact, side effects | `/hapo:inspect` |
-| external best practices, tool comparison, technical investigation | `/hapo:research` |
-
-Use `/hapo:research` for external knowledge. Use `/hapo:inspect` for local source truth.
-
-## Delegation Workflow
-
-| User intent | Suggested skill |
-|---|---|
-| assign/offload an implementation task to an external agent CLI (codex, grok) | `/hapo:delegate` |
-
-Claude Code remains the orchestrator: it writes the task brief, dispatches, monitors, and independently verifies the returned work.
-
-## Output Artifact Workflow
-
-| User intent | Suggested skill |
-|---|---|
-| PowerPoint or slide deck creation/editing | `/hapo:pptx` |
-| Word documents | `/hapo:docx` |
-| PDF processing | `/hapo:pdf` |
-| spreadsheets | `/hapo:xlsx` |
-| screenshots, images, audio, video, OCR, multimodal understanding | `/hapo:ai-multimodal` |
+Bug path: `/hapo:debug -> /hapo:hotfix` then test/review. As-is docs: `/hapo:inspect` → `/hapo:docs --reconstruct <scope>` → human review → specs → develop. Delegate implementation to an external agent CLI: `/hapo:delegate`.
 
-## Selection Rules
+## Ambiguous cases
 
-- Pick one primary workflow first.
-- Add a secondary skill only when it materially changes execution.
-- Prefer explicit user commands over this table.
-- If two workflows conflict, ask one concise clarification.
-- If the user asks a factual or project question before workflow selection, use `/hapo:question`.
-- If missing information blocks workflow selection, ask one concise clarification or use `/hapo:brainstorm`.
-- If the user asks to "fix" and root cause is unknown, start with `/hapo:debug` unless the issue is trivial and local.
+| Ambiguity | Prefer | Not when |
+|---|---|---|
+| debug-vs-hotfix | `/hapo:debug` first when root cause unknown | Root cause is known / trivial local fix → `/hapo:hotfix` |
+| question-vs-research | `/hapo:question` to ask about source code, docs, specs, config, dependencies, or project facts | External best-practice comparison / multi-source investigation → `/hapo:research` |
+| question-vs-brainstorm | `/hapo:question` for factual answers with evidence | Vague idea, missing acceptance criteria, unclear scope, multi-approach tradeoffs → `/hapo:brainstorm` |
+| specs-vs-brainstorm | `/hapo:specs` when intent and acceptance are concrete enough | Unclear idea / architecture choices still open → `/hapo:brainstorm` first |

package/src/claude/rules/state-sync.md

@@ -28,4 +28,4 @@ Before returning control to the user or orchestrator, the agent **MUST**:
 
 ### Completion gate (Stop)
 
-Marking a task `done` is now machine-gated on the **Stop** hook (`spec-gate.cjs`), not only reminded on each prompt. When a turn ends with *newly-done* tasks, the gate requires a verification receipt in each task markdown: `Status: done`, an Evidence section (or legacy `Task Test Plan & Verification Evidence` / `Verification & Evidence`) with real proof (no `{{...}}` placeholders; at least one fenced command block or PASS/FAIL line), and a non-empty `task_registry[path].completed_at`. First adoption (no cache yet) seeds history without blocking. Escape hatch for humans: `"spec": { "completion_gate": false }` in `.claude/runtime.json` (missing key keeps the gate ON).
+Marking a task `done` is now machine-gated on the **Stop** hook (`spec-gate.cjs`), not only reminded on each prompt. When a turn ends with *newly-done* tasks, the gate requires a verification receipt in each task markdown: `Status: done`, `## Evidence` (legacy heading aliases still parse) with real proof (no `{{...}}` placeholders; at least one fenced command block or PASS/FAIL line), and a non-empty `task_registry[path].completed_at`. First adoption (no cache yet) seeds history without blocking. Escape hatch for humans: `"spec": { "completion_gate": false }` in `.claude/runtime.json` (missing key keeps the gate ON).

package/src/claude/runtime.json

@@ -13,21 +13,21 @@
   },
   "paths": {
     "docs": "docs",
-    "specs": "specs"
+    "specs": "specs",
+    "plans": "plans"
   },
   "spec": {
     "scaffold_guard": true,
-    "completion_gate": true
+    "completion_gate": true,
+    "tollgate": true
+  },
+  "develop": {
+    "parallel": true
   },
   "locale": {
     "thinkingLanguage": null,
     "responseLanguage": null
   },
-  "skills": {
-    "research": {
-      "useGemini": true
-    }
-  },
   "usage": {
     "enabled": true
   },

package/src/claude/scripts/validate-spec-output.cjs

@@ -113,6 +113,7 @@ function validateTaskSections(taskPath, content, errors) {
     hasHeading(content, 'Requirements') || /_Requirements:\s*[^_\n]+_/i.test(content);
   const hasRelatedFiles = hasHeading(content, 'Related Files');
   const hasCompletionCriteria = hasHeading(content, 'Completion Criteria');
+  // legacy heading aliases: read-compat only, no longer advertised
   const hasEvidence =
     hasHeading(content, 'Evidence') ||
     hasHeading(content, 'Task Test Plan & Verification Evidence') ||
@@ -365,6 +366,11 @@ function validateSpec(specDir) {
   const contractDefs = fs.existsSync(designPath)
     ? extractContractDefs(fs.readFileSync(designPath, 'utf8'))
     : new Map();
+  if (taskFiles.length >= 5 && contractDefs.size === 0) {
+    warnings.push(
+      'design.md declares no contract blocks; specs spanning BE/FE must declare shared shapes (<!-- contract:NAME -->)',
+    );
+  }
   for (const taskFile of taskFiles) {
     const fullPath = path.join(specDir, taskFile);
     const content = fs.readFileSync(fullPath, 'utf8');

package/src/claude/skills/code-review/references/spec-compliance-review.md

@@ -24,7 +24,7 @@ Do not attempt a standard text-based review if the project includes Visual Specs
 3. If NO (Markdown Spec only): Read the spec directly and extract:
    - requirement bullets
    - task `Completion Criteria`
-   - task `Evidence` (or `Task Test Plan & Verification Evidence` / legacy `Verification & Evidence`)
+   - task `## Evidence` (legacy heading aliases still parse)
    - canonical contracts/invariants from `design.md`
    Then verify the changed files against those concrete obligations.
 

package/src/claude/skills/develop/SKILL.md

@@ -5,7 +5,7 @@ user-invocable: true
 when_to_use: "Invoke to implement specs and tasks end-to-end after scope is clear."
 category: utilities
 keywords: [implementation, specs, build, orchestration]
-argument-hint: "[feature-name|specs-directory-path] [task-file] [--flash] [--no-notes]"
+argument-hint: "[feature-name|specs-directory-path] [task-file] [--flash] [--parallel [N]] [--no-notes]"
 metadata:
   author: haposoft
   version: "1.0.0"
@@ -48,6 +48,27 @@ Triggered by `/hapo:develop <feature>` or `/hapo:develop specs/<feature>`.
 - STOP the overall run on the first blocked task, unresolved gate failure, or missing proof.
 - In `--flash` mode, missing full test proof does not stop the loop; record `FLASH_UNVERIFIED` and continue to the next unblocked task.
 
+### 2b. Parallel Wave Mode (opt-in)
+Triggered by adding `--parallel [N]` to Full-Spec mode. Load `references/parallel-waves.md` and follow it exactly — it is the operating procedure (wave planning, dispatch, merge, cleanup).
+
+Contracts: WAVE_CONFIG
+
+<!-- contract:WAVE_CONFIG -->
+```jsonc
+// .claude/runtime.json — develop parallel toggle (missing key = allowed)
+"develop": {
+  "parallel": true   // false = --parallel refused, sequential run + notice
+}
+// Flag: /hapo:develop <feature> --parallel [N]   (N = wave cap, 1..5, default 3)
+```
+
+- Preconditions first: if `runtime.json` sets `develop.parallel: false`, refuse `--parallel`, name the key, and run the sequential loop. If the work context is not a git repository or worktree isolation is unavailable, state the reason and fall back sequential (see parallel-waves.md §1).
+- Waves are computed from `task_registry.dependencies` with the single-writer-per-file rule; wave cap = N (1..5, default 3).
+- Dispatch one `god-developer` per wave task — worktree isolation, background, self-contained prompt per `rules/orchestrator.md`, plus the mandatory lines in parallel-waves.md §3 (commit mandate; never edit `spec.json`/`tasks/*.md`; never touch files outside the task's `Related Files`).
+- Quality gate (Stage A+B, unchanged) runs inside each task's worktree BEFORE merge; merge = sequential `git cherry-pick` of agent commits with explicit worktree/branch cleanup (spike-verified — see parallel-waves.md §5); post-merge integration check gates the next wave.
+- The orchestrator is the single writer of spec state: registry/task-md/receipts update after each cherry-pick, exactly as in sequential mode.
+- Without `--parallel`, nothing in this section applies — the sequential Full-Spec loop below is unchanged.
+
 ### 3. Flash Mode
 Triggered by adding `--flash` to either specific-task or full-spec mode.
 
@@ -76,7 +97,7 @@ DO NOT write implementation code until an approved spec exists.
 
 <DEFINITION-OF-DONE>
 A task is NOT done because code compiles or a placeholder renders.
-A task is done only when the task file's Completion Criteria AND Evidence section are satisfied with real execution proof. Existing specs may use `Task Test Plan & Verification Evidence` or legacy `Verification & Evidence`; treat those as the same contract.
+A task is done only when the task file's Completion Criteria AND `## Evidence` (legacy heading aliases still parse) are satisfied with real execution proof.
 `--flash` is the only exception: it records fast implementation closeout with `FLASH_UNVERIFIED`, not full Definition of Done.
 </DEFINITION-OF-DONE>
 
@@ -95,7 +116,7 @@ You MUST implement all scoped behavior for the active task, MUST NOT add out-of-
 | Thought (Excuse) | Reality (Rule) |
 |-------------------|----------------|
 | "No need to scout first" | Coding without knowing the architecture is blind. ALWAYS call the `inspector` agent to scan files. |
-| "Review process is too tedious, let me just finish it myself" | The system needs an audit trail through agents. ALWAYS delegate via `Task` tool. |
+| "Review process is too tedious, let me just finish it myself" | The system needs an audit trail through agents. ALWAYS delegate via the `Agent` tool. |
 
 ## Absolute Workflow
 
@@ -132,7 +153,7 @@ flowchart TD
   - Objective + Constraints
   - Related Files
   - Completion Criteria
-  - Evidence (or `Task Test Plan & Verification Evidence` / legacy `Verification & Evidence`)
+  - `## Evidence` (legacy heading aliases still parse)
   - Exact executable verification commands named in the task
   - Requirement IDs referenced by the task
   - Named technologies, frameworks, protocols, and data stores that the task/spec explicitly requires
@@ -192,7 +213,7 @@ The moment you finish coding, DO NOT proceed further. Switch to `references/qual
 If `--flash` is active, use **Step 4F: Flash Gate** instead of the full automatic review loop.
 
 - Passing Step 4 requires ALL of the following:
-  1. Automated verification passes, including preflight compile/typecheck/build health and every exact command named in the task's `Evidence` section (or `Task Test Plan & Verification Evidence` / legacy `Verification & Evidence`)
+  1. Automated verification passes, including preflight compile/typecheck/build health and every exact command named in the task's `## Evidence` (legacy heading aliases still parse)
   2. Spec compliance review passes: every scoped requirement and active task criterion is implemented, with no extras and no omissions
   3. Code quality review passes
   4. Task evidence passes (artifacts/runtime surfaces/reachability/negative-path checks from the task file are proven)

package/src/claude/skills/develop/references/parallel-waves.md

@@ -0,0 +1,112 @@
+# Parallel Waves — hapo:develop `--parallel` operating procedure
+
+Normative protocol for executing independent spec tasks concurrently. Loaded by
+`develop/SKILL.md` when Full-Spec mode runs with `--parallel [N]`. Verified against
+live worktree-subagent behavior (spec `develop-parallel-wave`,
+`reports/worktree-spike.md`, 2026-07-19).
+
+## 1. Preconditions (check before anything else)
+
+1. `.claude/runtime.json` → `develop.parallel` is not `false` (escape hatch; missing
+   key = allowed). If `false`: refuse `--parallel`, tell the user the hatch is active
+   and which key controls it, then run the standard sequential loop.
+2. The work context is a git repository and worktree isolation is available.
+   Otherwise: state the reason ("not a git repo" / "isolation unavailable") and run
+   the standard **sequential fallback**.
+3. `--parallel N`: **wave cap** = N clamped to 1..5; default 3. Never exceed 5 —
+   each subagent carries a ~200K context budget (orchestrator.md resource rule).
+
+## 2. Wave planning (normative)
+
+```
+ready(t) = t.status == "pending" AND every dep in task_registry[t].dependencies
+           has status == "done"
+candidates = ready tasks in task_registry order
+wave = first ≤cap candidates, EXCLUDING any task that shares a Create or Modify
+       path (exact normalized string match over its Related Files table) with an
+       earlier task already in the wave — the excluded task returns to the pool
+```
+
+**Single writer per file per wave** is absolute. `Read` rows never conflict.
+If the wave is empty but pending tasks remain, dependencies are unsatisfiable in
+parallel — finish them with the sequential loop and say so.
+
+### Worked example
+
+Registry: A (deps: –), B (deps: –), C (deps: A), D (deps: – but shares
+`src/api/users.ts` Modify with B). Cap 3.
+
+- Wave 1 = A, B (D excluded: path collision with B; C excluded: dep on A)
+- Wave 2 = C, D (A done unblocks C; B done releases D's path)
+
+## 3. Dispatch (one god-developer per wave task)
+
+Every dispatch uses worktree isolation + background execution and a
+self-contained prompt per `rules/orchestrator.md` (task file content, design and
+requirements excerpts, work-context/specs/docs paths, acceptance criteria) plus
+these mandatory lines:
+
+1. "You are in an isolated git worktree. Implement ONLY this task."
+2. "Do NOT edit `spec.json` or any `tasks/*.md` — the orchestrator owns spec state."
+3. "Do NOT touch files outside this task's `Related Files`."
+4. "When done, `git add` your changes and `git commit -m \"task(<id>): <title>\"` —
+   an uncommitted worktree cannot be merged."
+5. End with the standard `Status: DONE|CONCERNS|BLOCKED|NEEDS_INFO` block, plus
+   your worktree path, branch, and commit hash(es).
+
+The Agent result returns `worktreePath` and `worktreeBranch` — record both per task.
+
+## 4. Quality gate — inside the worktree, before merge
+
+Run the unchanged Stage A + Stage B gate (`references/quality-gate.md`) per task
+**with the task's worktree as working directory**. Gate evidence from that run
+feeds the task receipt. 3 failed rounds → COLLAPSE protocol for that task only;
+sibling tasks in the wave keep running.
+
+## 5. Merge protocol (spike-verified — do not improvise)
+
+⚠️ Spike finding: worktree branches are based on **`origin/<default-branch>`**
+(`worktree.baseRef: "fresh"` default), NOT the session HEAD. On repos whose origin
+default diverges, `git merge <agent-branch>` explodes into unrelated conflicts.
+
+Therefore, for each gate-passed task, **sequentially** (one at a time, registry order):
+
+```bash
+git cherry-pick <agent-commit>       # base-agnostic: applies only the agent's diff
+# conflict? → git cherry-pick --abort
+#   → task_registry[task].status = "blocked", blocker = one-line conflict summary
+#   → continue with the next passed task
+git worktree remove --force .claude/worktrees/agent-<id>   # NOT auto-cleaned —
+git branch -D worktree-agent-<id>                          # explicit cleanup, always
+```
+
+Cleanup runs for unchanged/failed worktrees too (spike: even a read-only run
+leaves its worktree and branch behind). Optionally set `worktree.baseRef: "head"`
+in settings; cherry-pick remains the recipe regardless.
+
+## 6. Post-merge integration check (per wave)
+
+After the wave's last cherry-pick: run the project build or the affected test
+subset (never the full suite mid-flight — that runs once at develop completion).
+Failure = fix before computing the next wave. This is the wave gate of
+`quality-gate.md`.
+
+## 7. State sync — orchestrator is the single writer
+
+Only the orchestrator writes `spec.json` and task markdown, after each task's
+cherry-pick: registry `status`/`completed_at`/`last_updated_at`, task-md `Status`,
+checkbox ticks, and a verification receipt citing the worktree gate evidence plus
+the post-merge check result. The Stop completion gate (`spec-gate.cjs`) applies
+unchanged — a receipt-less done blocks the turn. After syncing the wave, recompute
+§2 and continue until no pending tasks remain.
+
+## 8. Failure summary
+
+| Event | Action |
+|---|---|
+| Escape hatch on / not a git repo / no isolation | Sequential fallback + stated reason |
+| Same-wave path collision | Defer the later task to next wave (§2) |
+| Gate fails 3× for a task | COLLAPSE for that task; wave continues |
+| Cherry-pick conflict | Abort pick; task `blocked` + conflict blocker; wave continues |
+| Post-merge check fails | No next wave until fixed |
+| Empty wave, tasks pending | Sequential loop for the remainder + notice |

package/src/claude/skills/develop/references/quality-gate.md

@@ -12,7 +12,7 @@ Green tests are NOT enough. The gate requires four proofs:
 
 ## Automation Semantics
 
-- If the task names exact commands in `Evidence` (or `Task Test Plan & Verification Evidence` / legacy `Verification & Evidence`), those exact commands are mandatory and must run before any fallback repo defaults.
+- If the task names exact commands in `## Evidence` (legacy heading aliases still parse), those exact commands are mandatory and must run before any fallback repo defaults.
 - Preflight compile/typecheck/build health is mandatory. If compile/typecheck/build fails before tests are meaningful, the gate result is `PRECHECK_FAIL`, not `NO_TESTS`.
 - `NO_TESTS` is never an automatic PASS.
 - `NO_TESTS` is acceptable only when the task does **not** require a dedicated test suite command and every other required automated command/evidence item passes.
@@ -55,7 +55,7 @@ Variable: retry_count = 0
 
 Before START_LOOP:
   - Read the active task file(s)
-  - Extract Related Files, Completion Criteria, Evidence (or Task Test Plan & Verification Evidence / legacy Verification & Evidence)
+  - Extract Related Files, Completion Criteria, `## Evidence` (legacy heading aliases still parse)
   - Extract the exact executable verification commands in declaration order
   - Extract relevant design contracts/invariants for the touched area
   - Extract scope_lock, requirement IDs, runtime entrypoints/callers, and reachability proof obligations
@@ -129,3 +129,11 @@ Must log the Quality Gate result to the terminal for user visibility:
 - **Preflight Fail:** `[x] Step 4 Quality Gate: PRECHECK_FAIL → compile/typecheck/build failed before tests mattered`
 - **Fix Needed:** `[~] Step 4 Quality Gate: Tests/spec/evidence failed → returned to god-developer`
 - **Awaiting Rescue:** `[!] Step 4 Quality Gate: Failed 3 rounds! Awaiting user intervention...`
+
+## Working directory (parallel mode)
+
+When `hapo:develop` runs in Parallel Wave Mode (`references/parallel-waves.md`), every Stage A and Stage B command for a task executes **with that task's worktree as the working directory**. Gate evidence recorded from the worktree run feeds the task's verification receipt. Thresholds, retry counter, and the COLLAPSE protocol are identical to sequential mode. A COLLAPSE of one task does not cancel other in-flight tasks of the wave.
+
+## Post-merge integration check (per wave)
+
+After the orchestrator cherry-picks the last gate-passed task of a wave: run the project build **or** the affected test subset (never the full suite mid-flight — it runs once at develop completion). While this check fails, the next wave MUST NOT start.

package/src/claude/skills/hotfix/references/parallel-patterns.md

@@ -1,6 +1,6 @@
 # Parallel Patterns & Task Coordination
 
-How to effectively leverage multiple subagents and native Task tools during fix workflows.
+How to effectively leverage multiple subagents (the `Agent` tool) and native task tracking (`TaskCreate`/`TaskUpdate`) during fix workflows.
 
 ## When to Go Parallel