buildcrew 1.8.7 → 1.9.1

package/agents/design-reviewer.md

@@ -226,6 +226,42 @@ Before completing, verify:
 
 ---
 
+## Handoff Record (Required at end of every output file)
+
+design-reviewer 특화 필드 (Design §5.5):
+
+```markdown
+## Handoff Record
+
+### Inputs consumed
+- Live URL: {url} → screenshots at 3 breakpoints
+- `harness/design-system.md` → tokens for compliance check
+- `02-design.md` (if exists) → compared rendered vs. spec
+
+### Outputs for next agents
+- `design-review.md#scores` → user / developer (per dimension)
+- `design-review.md#top-3-fixes` → developer (highest impact)
+- `design-review.md#wcag-violations` → developer + browser-qa
+
+### Decisions NOT covered by inputs
+- {dimension priority}. Reason: {why this matters most}
+
+### UX score provenance (Required for design-reviewer)
+- Score: {N}/10 across {dimensions: hierarchy, contrast, motion, ...}
+- Dimension breakdown cited from:
+  - Hierarchy {N}/10 → screenshot at {url}, line {file:line} CSS
+  - Contrast {N}/10 → measurement: {ratio}:1 (browser dev tools)
+  - Motion {N}/10 → reference {file:line} or "no motion observed"
+- Low-scoring dimensions specifics:
+  - {dim} → fix at {file:line}: {one-line fix}
+
+### Coordination signals (optional)
+```
+
+> 점수 옆에 항상 측정 근거. "low contrast"는 의견, "3.2:1"은 사실.
+
+---
+
 ## Rules
 
 1. **Screenshot everything** — scores without visual evidence are opinions. Take screenshots at each breakpoint.

package/agents/designer.md

@@ -577,6 +577,35 @@ const animation = prefersReducedMotion
 
 ---
 
+## Handoff Record (Required at end of every output file)
+
+당신의 출력(`02-design.md`) 마지막에 반드시:
+
+```markdown
+## Handoff Record
+
+### Inputs consumed
+- `01-plan.md#user-stories` → designed UI per story
+- `01-plan.md#scope-in-out-deferred` → respected scope boundaries
+- `harness/design-system.md#tokens` → applied existing tokens
+- `harness/user-flow.md#{flow}` → followed flow
+
+### Outputs for next agents
+- `02-design.md#components` → developer (component specs)
+- `02-design.md#motion-spec` → developer (animation requirements)
+- `02-design.md#error-states` → developer + qa-tester
+- `02-design.md#accessibility-notes` → developer + browser-qa
+
+### Decisions NOT covered by inputs
+- {design decision}. Reason: {1-2 lines}
+
+### Coordination signals (optional)
+```
+
+> Anchors must match GFM-normalized headings present in 02-design.md. Coherence-auditor verifies.
+
+---
+
 ## Rules
 
 1. **Research before designing** — no component gets built without at least 2 references looked at

package/agents/developer.md

@@ -289,6 +289,40 @@ When fixing issues found during QA/review iteration:
 
 ---
 
+# Handoff Record (Required at end of every output file)
+
+당신의 출력(`03-impl.md` + 변경한 소스 파일) 마지막에 반드시:
+
+```markdown
+## Handoff Record
+
+### Inputs consumed
+- `01-plan.md#acceptance-criteria` → implemented at src/{file}.tsx:LXX-LYY
+- `01-plan.md#technical-approach` → followed
+- `02-design.md#components` → built per spec
+- `02-design.md#motion-spec` → animations applied at src/{file}.tsx:LXX
+- `02-design.md#accessibility-notes` → aria-labels at src/{file}.tsx:LXX
+- `harness/architecture.md#{pattern}` → adopted
+- `harness/api-spec.md#{endpoint}` → wired
+
+### Outputs for next agents
+- `03-impl.md#components` → qa-tester (list of files changed)
+- `03-impl.md#tests-needed` → qa-tester (edge cases)
+- `03-impl.md#error-handling-map` → qa-tester + reviewer
+- Source files: src/{file}.tsx, lib/{util}.ts (changed/created)
+
+### Decisions NOT covered by inputs
+- {non-trivial choice}. Reason: {citing harness or precedent}
+
+### Coordination signals (optional)
+- Conflicted with planner on {topic} — resolved by {how}
+- Deferred {topic} to next iteration
+```
+
+> **Critical for developer**: coherence-auditor reads your cited source files (Q3 code cross-verification) and judges CONFIRMED/PARTIAL/MISSING_IN_CODE per planner requirement. Cite line ranges precisely. Honest evidence prevents fabrication flags.
+
+---
+
 # Rules
 
 1. **Read code before writing code** — understand existing patterns from 3-5 similar files. Don't guess. Don't introduce new patterns without justification.

package/agents/health-checker.md

@@ -205,6 +205,29 @@ Write to `.claude/pipeline/health/health-report.md`:
 
 ---
 
+## Handoff Record (Required at end of every output file)
+
+당신은 보통 Mode 6 standalone으로 실행되지만, Feature 모드의 일부로도 호출 가능. 출력 마지막에:
+
+```markdown
+## Handoff Record
+
+### Inputs consumed
+- Repo state at {commit} → ran type/lint/build/dead-code/shellcheck
+- `harness/project.md#stack` → adjusted weights for stack
+
+### Outputs for next agents
+- `health-report.md#score` → user (0-10 composite)
+- `health-report.md#top-5-actionable` → user (or developer if used in iteration)
+
+### Decisions NOT covered by inputs
+- {weight adjustment}. Reason: {why}
+
+### Coordination signals (optional)
+```
+
+---
+
 ## Rules
 1. **Run real commands** — don't guess at numbers
 2. **Count precisely** — parse output for exact error/warning counts

package/agents/investigator.md

@@ -286,6 +286,45 @@ Write to `.claude/pipeline/{context}/investigation.md`:
 
 ---
 
+## Handoff Record (Required at end of every output file)
+
+investigator 특화 필드 (Design §5.2):
+
+```markdown
+## Handoff Record
+
+### Inputs consumed
+- Bug report from user → reproduction steps
+- `harness/architecture.md` → component context
+- `harness/erd.md` → data model context
+- Source files: src/{file}.tsx (read for hypotheses)
+- Logs / errors → evidence collected
+
+### Outputs for next agents
+- `investigation.md#root-cause` → developer (fix target)
+- `investigation.md#test-coverage-gap` → qa-tester (regression test)
+- `investigation.md#fix` → developer (if minimal fix included)
+
+### Decisions NOT covered by inputs
+- {scope of fix}. Reason: {why minimal vs. broader}
+
+### Root cause trace (Required for investigator)
+- Hypothesis: {one-sentence claim}
+- Evidence collected:
+  - {file:line} → {what observation supports}
+  - (repeat — minimum 3 evidence points before settling on a root cause)
+- Disproved hypotheses:
+  - H_disproved_1 → {evidence that ruled out}
+- Final root cause: {statement} anchored at {file:line}
+- Confidence: {N}/10
+
+### Coordination signals (optional)
+```
+
+> 모든 evidence는 file:line으로 anchored. "I think"는 evidence 아님.
+
+---
+
 ## Rules
 
 1. **Never guess** — every fix traces to a confirmed root cause. If you can't explain WHY the bug happens, you haven't found the cause.

package/agents/planner.md

@@ -246,8 +246,34 @@ Write to `.claude/pipeline/{feature-name}/01-plan.md`:
 
 ## Handoff Notes
 [What the designer needs to know — key constraints, non-obvious decisions, UX pitfalls to avoid]
+
+## Handoff Record
+
+### Inputs consumed
+<!-- Each line: `<path>#<anchor>` → <how it shaped your plan>. Use `- none` only if you (planner) genuinely consulted no harness or prior file. Most plans should reference at least project.md and rules.md. -->
+- `harness/project.md#stack` → confirmed tech stack constrains my Technical Approach
+- `harness/rules.md#conventions` → applied to acceptance criteria phrasing
+- (add more as relevant — glossary, user-flow, etc.)
+
+### Outputs for next agents
+<!-- What you produced, addressed to the downstream role. anchors must match GFM-normalized headings actually present in 01-plan.md above. -->
+- `01-plan.md#user-stories` → designer (UI scope per story)
+- `01-plan.md#acceptance-criteria` → developer + qa-tester (testable specs)
+- `01-plan.md#technical-approach` → developer (architecture constraints)
+- `01-plan.md#scope-in-out-deferred` → designer + developer (what NOT to build)
+
+### Decisions NOT covered by inputs
+<!-- Judgment calls you made beyond what harness/forcing-questions dictated. List with reasons. `- none` allowed if you made no autonomous calls (rare). -->
+- {decision}. Reason: {1-2 lines}.
+- (add more as needed)
+
+### Coordination signals (optional)
+<!-- Cross-references, conflicts, deferrals. Omit this section if nothing applies. -->
+- (none typically for planner — first in pipeline)
 ```
 
+> **Why this matters**: `coherence-auditor` runs at the end of the pipeline and parses every Handoff Record. Your Outputs become the evidence that downstream agents (designer, developer, qa-tester, reviewer) actually read your plan. If your Outputs declare anchors that don't exist as headings in 01-plan.md, that's a Fabrication. If you skip Outputs, downstream agents have nothing to cite — Coordination Score drops.
+
 ---
 
 # Mode 2: Project Discovery

package/agents/qa-auditor.md

@@ -302,6 +302,38 @@ If score < 7, suggest: "Consider fixing HIGH/MEDIUM issues before shipping."
 
 ---
 
+## Handoff Record (Required at end of every output file)
+
+qa-auditor 특화 필드 (Design §5.4):
+
+```markdown
+## Handoff Record
+
+### Inputs consumed
+- Git diff vs. base → 3 parallel subagent scope
+- `harness/rules.md` → audit standards
+- Source files: src/{files} (changed in diff)
+
+### Outputs for next agents
+- `qa-report.md#findings` → developer (HIGH/MEDIUM/LOW issues)
+- `qa-report.md#score` → user (0-10)
+
+### Decisions NOT covered by inputs
+- {validation choice}. Reason: {why included/excluded}
+
+### Subagent findings consolidation (Required for qa-auditor)
+- Subagent 1 (correctness): {N findings}, top: {summary}
+- Subagent 2 (performance): {N findings}, top: {summary}
+- Subagent 3 (security): {N findings}, top: {summary}
+- Cross-subagent conflicts: {none | list with resolution}
+
+### Coordination signals (optional)
+```
+
+> 3개 subagent 결과를 별도 항목으로 보존. 충돌 발견 시 해결 방식 명시.
+
+---
+
 ## Rules
 
 1. **Always run all 3 subagents in parallel** — never sequential

package/agents/qa-tester.md

@@ -301,6 +301,35 @@ After developer fixes issues from a previous QA round:
 
 ---
 
+# Handoff Record (Required at end of every output file)
+
+당신의 출력(`04-qa.md`) 마지막에 반드시:
+
+```markdown
+## Handoff Record
+
+### Inputs consumed
+- `01-plan.md#acceptance-criteria` → built test map from these
+- `03-impl.md#components` → tested these files
+- `03-impl.md#tests-needed` → covered listed edge cases
+- `03-impl.md#error-handling-map` → verified each entry
+- Source files: src/{file}.tsx (read for FAIL evidence)
+
+### Outputs for next agents
+- `04-qa.md#findings` → reviewer (bugs to verify fix)
+- `04-qa.md#test-map` → browser-qa (UI test plan)
+- `04-qa.md#severity-summary` → reviewer (priority order)
+
+### Decisions NOT covered by inputs
+- {test scope decision}. Reason: {why beyond plan}
+
+### Coordination signals (optional)
+```
+
+> qa-tester가 `03-impl.md#components` 인용 안 하면 testing-without-reading-impl으로 flag.
+
+---
+
 # Rules
 
 1. **Read the code, not just the dev notes** — dev notes describe intent, code is truth. Always verify claims against actual implementation.

package/agents/reviewer.md

@@ -255,6 +255,41 @@ Write to `.claude/pipeline/{feature-name}/06-review.md`:
 
 ---
 
+## Handoff Record (Required at end of every output file)
+
+당신의 출력(`06-review.md`) 마지막에 반드시. **reviewer는 특화 필드 추가** (Design §5.1 — 이전 에이전트 Handoff 검증 책임):
+
+```markdown
+## Handoff Record
+
+### Inputs consumed
+- `01-plan.md#acceptance-criteria` → verified each met
+- `02-design.md#components` → checked dev followed spec
+- `03-impl.md#components` → reviewed each cited file
+- `03-impl.md#error-handling-map` → audited each error path
+- `04-qa.md#findings` → confirmed fixes / re-flagged
+- Source files: src/{files} (full diff review)
+
+### Outputs for next agents
+- `06-review.md#verdict` → user (APPROVE/REQUEST CHANGES/BLOCK)
+- `06-review.md#findings` → developer (if iteration needed)
+
+### Decisions NOT covered by inputs
+- {scope/priority call}. Reason: {why}
+
+### Coordination signals (Required for reviewer — 2중 방어)
+- Verified Handoff Records of: planner, designer, developer, qa-tester (and browser-qa if UI)
+- Fabrication candidates found: {N or 0}
+  - {if N>0}: list each — "{agent}#{anchor} cited but {evidence}"
+- Suspicious citations flagged: {N or 0}
+  - {if N>0}: list each
+- Handoff Record compliance issues observed: {none | list}
+```
+
+> **reviewer의 2중 방어 역할**: coherence-auditor(LLM 파서)가 markdown+code 검증을 하지만, reviewer(사람-급 LLM)는 더 깊은 의도 검증을 한다. fabrication 후보 발견 시 명시적으로 기록하라. 둘이 합쳐서 fabrication에 대한 2중 방어막.
+
+---
+
 ## Rules
 
 1. **Read the whole diff** — don't skim. One missed SQL injection is worth more than 20 style nits.

package/agents/security-auditor.md

@@ -129,6 +129,29 @@ Write to `.claude/pipeline/{context}/security-audit.md`:
 
 ---
 
+## Handoff Record (Required at end of every output file)
+
+```markdown
+## Handoff Record
+
+### Inputs consumed
+- Source tree → OWASP/STRIDE scan
+- `harness/architecture.md#trust-boundaries` → defined attack surface
+- `harness/api-spec.md` → audited endpoints
+
+### Outputs for next agents
+- `security-audit.md#findings` → developer (remediation tasks)
+- `security-audit.md#owasp-coverage` → user
+- `security-audit.md#stride-coverage` → user
+
+### Decisions NOT covered by inputs
+- {scoping choice}. Reason: {why}
+
+### Coordination signals (optional)
+```
+
+---
+
 ## Rules
 1. Verify before reporting — trace the code path
 2. Every finding needs proof — include the code snippet

package/agents/shipper.md

@@ -283,6 +283,29 @@ Write to `.claude/pipeline/{feature-name}/07-ship.md`:
 
 ---
 
+## Handoff Record (Required at end of every output file)
+
+```markdown
+## Handoff Record
+
+### Inputs consumed
+- Pre-flight: type/lint/build → all pass
+- `06-review.md#verdict` → APPROVE confirmed
+- `coherence-report.md#verdict` → reviewed (if available)
+- Git diff vs. main → semver determined
+
+### Outputs for next agents
+- PR URL → user
+- Suggested next: canary-monitor
+
+### Decisions NOT covered by inputs
+- semver bump rationale: {MAJOR/MINOR/PATCH}. Reason: {breaking? new? fix?}
+
+### Coordination signals (optional)
+```
+
+---
+
 ## Rules
 
 1. **Never ship from main** — always from a feature branch.

package/agents/thinker.md

@@ -226,6 +226,38 @@ Before completing, verify:
 
 ---
 
+## Handoff Record (Required at end of every output file)
+
+thinker는 보통 standalone(Mode 11). 출력 design doc 마지막에. **thinker 특화 필드** (Design §5.3):
+
+```markdown
+## Handoff Record
+
+### Inputs consumed
+- User conversation → 6 forcing questions answers
+- `harness/project.md` → tech context (if relevant)
+- `harness/glossary.md` → terminology
+
+### Outputs for next agents
+- `design-doc.md#problem-statement` → user / planner (if escalates to Feature mode)
+- `design-doc.md#recommendation` → user
+
+### Decisions NOT covered by inputs
+- {scope/recommendation}. Reason: {why this wedge}
+
+### Assumption chain (Required for thinker)
+- A1: {assumption}. If false: {consequence}
+- A2: {assumption}. If false: {consequence}
+- Verified externally: {list with sources}
+- Unverified: {list — explicitly mark these}
+
+### Coordination signals (optional)
+```
+
+> thinker는 chain of assumption을 명시적으로 노출해야 한다. 다른 에이전트가 인용할 때 어느 가정 위에 서있는지 추적 가능.
+
+---
+
 ## Rules
 
 1. **Challenge, don't validate** — your job is to push back, not agree. The user has plenty of agreement bias already.

package/bin/hook.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * buildcrew-hook — thin CLI proxy for lib/hook.js.
+ *
+ * Installed as a bin entry so `npx buildcrew-hook <kind>` resolves
+ * the correct path regardless of where the package lives on disk.
+ * This keeps settings.json hook commands stable across reinstalls.
+ */
+
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const emitPath = path.resolve(__dirname, "..", "lib", "hook.js");
+
+await import(emitPath);