@zigrivers/scaffold 2.28.1 → 2.38.1

package/knowledge/execution/worktree-management.md

@@ -0,0 +1,205 @@
+---
+name: worktree-management
+description: Git worktree patterns for parallel multi-agent execution
+topics: [git, worktrees, multi-agent, branching]
+---
+
+# Worktree Management
+
+Expert knowledge for managing git worktrees to enable parallel multi-agent execution. Covers setup, branching conventions, inter-task cleanup, and safe teardown procedures.
+
+## Summary
+
+### Setup
+
+Use `scripts/setup-agent-worktree.sh <agent-name>` to create a worktree at `../<project>-<agent-name>/`. Each agent gets its own isolated working directory and workspace branch.
+
+### Branching Conventions
+
+- Each agent operates on a workspace branch (e.g., `agent-1-workspace`)
+- Feature branches are created from `origin/main` — never from local `main`
+- Never run `git checkout main` inside a worktree — it will fail because `main` is checked out in the primary repo
+
+### Cleanup
+
+After all agents finish, remove worktrees and prune stale references. Delete merged feature branches in batch to keep the repository clean.
+
+## Deep Guidance
+
+### Setup — Extended
+
+**Creating a worktree:**
+
+```bash
+# From the main repository
+scripts/setup-agent-worktree.sh agent-1
+
+# This creates:
+#   ../<project>-agent-1/     (working directory)
+#   Branch: agent-1-workspace  (workspace branch)
+```
+
+**What the setup script does:**
+1. Creates a new worktree directory adjacent to the main repo
+2. Creates a workspace branch for the agent
+3. Sets up the working directory with a clean state
+4. Installs dependencies if a package manager is detected
+
+**Multiple agents:**
+
+```bash
+scripts/setup-agent-worktree.sh agent-1
+scripts/setup-agent-worktree.sh agent-2
+scripts/setup-agent-worktree.sh agent-3
+```
+
+Each agent has a completely isolated working directory. They share the same `.git` object store but have separate working trees, index files, and HEAD pointers.
+
+### Workspace Branch Conventions
+
+Each agent gets a persistent workspace branch that serves as its "home base":
+
+- `agent-1-workspace`, `agent-2-workspace`, etc.
+- The workspace branch is where the agent returns between tasks
+- Feature branches for individual tasks are created from `origin/main`, not from the workspace branch
+
+**Why workspace branches exist:**
+- A worktree requires a branch that isn't checked out elsewhere
+- The workspace branch prevents conflicts with `main` (which is checked out in the primary repo)
+- It provides a stable base for the agent to return to between tasks
+
+### Branching — Extended
+
+**Creating a feature branch for a task:**
+
+```bash
+# Inside the agent's worktree
+git fetch origin
+git checkout -b bd-42/add-user-endpoint origin/main
+```
+
+**Critical rules:**
+- Always branch from `origin/main` — never from local `main` (it may be stale) and never from the workspace branch
+- Branch naming: `bd-<id>/<short-desc>` when using Beads, or `feat/<task-id>-<slug>` otherwise
+- One branch per task — never combine multiple tasks on a single branch
+
+**Never run `git checkout main` in a worktree:**
+- The `main` branch is checked out in the primary repo
+- Git does not allow the same branch to be checked out in multiple worktrees
+- This command will fail with an error; if you need main's content, use `origin/main`
+
+### Between Tasks
+
+After completing a task (PR created and CI passing), prepare for the next one:
+
+```bash
+# Fetch latest state from remote
+git fetch origin --prune
+
+# Switch back to workspace branch
+git checkout agent-1-workspace
+
+# Clean up untracked files and directories
+git clean -fd
+
+# Reinstall dependencies (important if package files changed on main)
+# npm install / pip install -r requirements.txt / etc.
+```
+
+**Why this matters:**
+- `git fetch --prune` ensures you see newly merged branches and removed remote branches
+- `git clean -fd` removes artifacts from the previous task
+- Dependency reinstallation catches changes merged by other agents
+
+### Rebase Strategy
+
+Before creating a PR, rebase your feature branch onto the latest `origin/main`:
+
+```bash
+git fetch origin
+git rebase origin/main
+```
+
+**Why rebase instead of merge:**
+- Produces a linear history on the feature branch
+- Makes the PR diff cleaner (only your changes, no merge commits)
+- Squash-merge to main produces a single clean commit
+
+**If rebase conflicts arise:**
+1. Read the conflict carefully — understand which agent's changes conflict with yours
+2. If the conflict is in files you modified, resolve it preserving both changes where possible
+3. If the conflict is in files you didn't modify, investigate — you may have an undetected dependency on another task
+4. After resolving, run the full test suite to verify nothing broke
+5. If the conflict is too complex, ask for help rather than guessing
+
+### Conflict Resolution
+
+**Common conflict scenarios in multi-agent work:**
+
+| Scenario | Resolution |
+|----------|------------|
+| Two agents add to the same file (e.g., new exports) | Merge both additions |
+| Two agents modify the same function | Deeper analysis needed — may indicate a missing dependency |
+| Schema migration conflicts | Renumber the later migration |
+| Lock file conflicts | Delete lock file, reinstall, commit new lock file |
+
+### Cleanup — Extended
+
+**Removing a single worktree:**
+
+```bash
+# From the main repository (not from inside the worktree)
+git worktree remove ../<project>-agent-1
+```
+
+**Pruning stale worktree references:**
+
+```bash
+git worktree prune
+```
+
+Run this after removing worktrees or if a worktree directory was deleted manually.
+
+**Batch cleanup of merged feature branches:**
+
+```bash
+git fetch origin --prune
+git branch --merged origin/main | grep "bd-" | xargs -r git branch -d
+```
+
+This deletes all local branches that have been merged to `origin/main` and match the `bd-` prefix. Safe because `--merged` ensures only fully-merged branches are deleted, and `-d` (not `-D`) refuses to delete unmerged branches.
+
+**Cleanup of workspace branches:**
+
+After all agents are done and their worktrees are removed:
+
+```bash
+git branch | grep "workspace" | xargs -r git branch -D
+```
+
+Use `-D` here because workspace branches are not merged — they're disposable.
+
+### BD_ACTOR Environment Variable
+
+When using Beads for task tracking, set `BD_ACTOR` per agent for attribution:
+
+```bash
+export BD_ACTOR="agent-1"
+```
+
+This ensures that task claims, completions, and other Beads operations are attributed to the correct agent. Set it in the agent's shell environment before starting work.
+
+### Listing Active Worktrees
+
+To see all active worktrees and their branches:
+
+```bash
+git worktree list
+```
+
+Output shows the path, HEAD commit, and branch for each worktree. Use this to verify agent setup and identify stale worktrees.
+
+## See Also
+
+- [git-workflow-patterns](../core/git-workflow-patterns.md) — Branching strategy, commit conventions, PR workflow
+- [task-claiming-strategy](./task-claiming-strategy.md) — Task selection and multi-agent coordination

package/knowledge/finalization/apply-fixes-and-freeze.md

@@ -8,6 +8,18 @@ topics: [finalization, fixes, freeze, validation, documentation-quality]
 
 The apply-fixes-and-freeze step is the last gate before implementation begins. Its purpose is to resolve all actionable validation findings, verify the fixes don't introduce new issues, and mark the documentation as frozen. After this step, documents change only if implementation reveals a genuine gap.
 
+## Summary
+
+- **Fix prioritization**: P0 (blocking, must fix), P1 (significant gap, should fix), P2 (improvement, defer with rationale). Decision rule: would an agent produce incorrect code? (P0), have to guess? (P1), neither? (P2).
+- **Fix process**: Build fix plan (deduplicate, group by document, order by priority), apply minimal targeted fixes, re-validate affected checks, loop until zero new findings.
+- **Fix execution rules**: One finding per commit, fix forward not around, preserve document structure, cross-document fixes must be atomic.
+- **Re-validation**: Re-run the specific validation passes that flagged each fix. Spot-check adjacent sections. Verify counts and cross-references. Grep for old terms after renames.
+- **Documentation freeze**: All P0 and P1 resolved, re-validation clean. Add `<!-- FROZEN -->` marker to each artifact. No further content changes unless implementation reveals a genuine gap.
+- **Post-freeze rules**: Typo fixes allowed. Implementation-discovered gaps go through P0/P1 prioritization. No scope additions. No "nice to have" improvements.
+- **Common pitfalls**: Fixing symptoms instead of root causes, introducing new inconsistencies, over-fixing beyond implementation readiness, skipping re-validation, premature freeze.
+
+## Deep Guidance
+
 ## Fix Prioritization
 
 Validation phases produce findings at three priority levels. Address them in strict order:

package/knowledge/finalization/developer-onboarding.md

@@ -10,6 +10,8 @@ A developer onboarding guide is the first document a new developer (human or AI
 
 This document covers what an effective onboarding guide should contain, how to structure it, and what to avoid.
 
+## Summary
+
 ## Guide Structure
 
 The onboarding guide follows a deliberate progression from purpose to productivity:
@@ -54,6 +56,8 @@ data automatically and highlights discrepancies for review.
 - Business metrics or revenue goals (irrelevant to contributors)
 - History of the project (unless it explains current technical decisions)
 
+## Deep Guidance
+
 ## 2. Architecture Overview
 
 ### What to Include

package/knowledge/finalization/implementation-playbook.md

@@ -10,6 +10,8 @@ The implementation playbook is the definitive reference for AI agents executing
 
 This is the most critical finalization document. If the onboarding guide tells agents "what this project is," the playbook tells them "how to do the work."
 
+## Summary
+
 ## Task Execution Protocol
 
 ### How Agents Pick Work
@@ -63,6 +65,21 @@ Read before starting:
 
 If a task does not have a context brief, the agent should create one from the specification artifacts before starting.
 
+### Minimum Context by Task Type
+
+When a per-task context block is incomplete, agents should consult this taxonomy to ensure they have sufficient context:
+
+| Task Type | Required Docs | Additional Context |
+|-----------|--------------|-------------------|
+| Backend API | `docs/api-contracts.md`, `docs/database-schema.md`, `docs/domain-models/`, `docs/coding-standards.md`, `docs/tdd-standards.md` | Relevant ADR for API style choices |
+| Frontend UI | `docs/ux-spec.md`, `docs/design-system.md`, `docs/api-contracts.md`, `docs/coding-standards.md`, `docs/tdd-standards.md` | Component patterns from design system |
+| Database migration | `docs/database-schema.md`, `docs/domain-models/`, `docs/operations-runbook.md` | Rollback strategy from ops runbook |
+| Infrastructure/CI | `docs/dev-setup.md`, `docs/git-workflow.md`, `docs/operations-runbook.md` | Deployment pipeline stages |
+| Bug fix | Relevant source code, `docs/tdd-standards.md`, `docs/coding-standards.md` | Related test files, reproduction steps |
+| Security hardening | `docs/security-review.md`, `docs/api-contracts.md`, `docs/coding-standards.md` | OWASP checklist items from security review |
+
+## Deep Guidance
+
 ## Coding Standards
 
 Coding standards ensure consistency across agents. Every agent must follow these conventions without exception. Inconsistency between agents produces a codebase that feels like it was written by different teams — because it was.
@@ -288,8 +305,8 @@ Before a task is considered complete, all quality gates must pass.
 ### Gate 1: Tests Pass
 
 ```bash
-npm test                     # All tests pass
-npm run test:coverage        # Coverage meets threshold
+make test                    # All tests pass
+make test-coverage           # Coverage meets threshold
 ```
 
 Every task must include tests for the code it adds or modifies:
@@ -301,8 +318,8 @@ Every task must include tests for the code it adds or modifies:
 ### Gate 2: Lint and Type Check
 
 ```bash
-npm run lint                 # No lint errors (warnings are allowed but discouraged)
-npm run typecheck            # No type errors
+make lint                    # No lint errors (warnings are allowed but discouraged)
+make typecheck               # No type errors
 ```
 
 Do not disable lint rules with `eslint-disable` unless the rule is genuinely wrong for that specific case, and add a comment explaining why.
@@ -310,9 +327,11 @@ Do not disable lint rules with `eslint-disable` unless the rule is genuinely wro
 ### Gate 3: Build Succeeds
 
 ```bash
-npm run build                # Production build succeeds
+make build                   # Production build succeeds
 ```
 
+> Commands shown here are examples. Use the actual commands from your project's CLAUDE.md Key Commands table.
+
 If the build fails with warnings, investigate. Warnings often become errors in stricter environments.
 
 ### Gate 4: Manual Verification
@@ -325,6 +344,12 @@ Automated tests are necessary but not sufficient. Always verify the feature work
 
 Run the full test suite, not just the tests for the changed code. New code can break existing features through unexpected interactions.
 
+### Gate 6: Evals
+
+**Gate: Evals** — Run `make eval` (or project-equivalent from CLAUDE.md Key Commands). All eval checks must pass. If a specific eval fails, consult `docs/eval-standards.md` for category descriptions and resolution guidance.
+
+Evals run collectively via `make eval`. If a specific eval category fails, consult `docs/eval-standards.md` for the category description and resolution approach.
+
 ## Inter-Agent Handoff
 
 When one agent completes a task and another agent will build on it, the completing agent must communicate:
@@ -402,3 +427,56 @@ The playbook is a living document. Update it when:
 - Agent coordination issues arise (add to parallel work rules)
 
 The playbook should be the first document agents read before their first task, and the document they reference throughout implementation. If an agent asks a question that the playbook should answer, the answer goes in the playbook.
+
+### Error Recovery
+
+> The depth and specificity of error recovery guidance in CLAUDE.md depends on the `workflow-audit` step's methodology depth. At MVP depth, error recovery may be minimal.
+
+When quality gates fail during implementation:
+
+**Test failures:**
+1. Read the failing test to understand the expected behavior
+2. Check if the test is testing your change or pre-existing functionality
+3. If your change broke the test: fix the implementation, not the test
+4. If the test is wrong: document why and update the test with the fix
+5. Re-run the full test suite, not just the failing test
+
+**CI failures:**
+1. Pull latest main and rebase your branch
+2. Run `make check` locally to reproduce the failure
+3. If the failure is environment-specific: check dev-setup.md for requirements
+4. If the failure is a flaky test: document the flakiness and retry once
+
+### Eval Failure Recovery
+
+When `make eval` fails during implementation:
+
+1. **Read the failing test name** — eval category names indicate what's wrong (e.g., `adherence` = coding standard violation, `consistency` = cross-document mismatch)
+2. **Check `docs/eval-standards.md`** (if it exists) for category-specific guidance
+3. **Common eval failures**:
+   - **Adherence evals**: Code doesn't match coding-standards.md patterns. Fix: read the specific standard and adjust code.
+   - **Consistency evals**: Document references are stale or contradictory. Fix: update the reference to match current state.
+   - **Structure evals**: File/directory doesn't match project-structure.md. Fix: move files to correct location.
+   - **Security evals**: Missing input validation or auth check. Fix: add the missing security control per security-review.md.
+4. **If eval seems wrong**: Check if the eval itself is outdated. Flag for upstream review rather than working around it.
+
+**Spec gap discovered during implementation:**
+1. Document the gap with specific details (what's missing, what's needed)
+2. Check if an ADR or architecture decision covers the case
+3. If the gap is small: make a judgment call, document it in the commit message
+4. If the gap is significant: pause the task and flag it for upstream resolution
+
+**Agent produces incorrect output:**
+1. Review the task description and acceptance criteria
+2. Diff the output against the expected behavior
+3. If the task description was ambiguous: improve it for future agents
+4. Roll back the incorrect changes and retry with clearer context
+
+### Dependency Failure
+
+When a task's upstream dependency hasn't merged or has failed:
+
+1. **Check the dependency task status** in docs/implementation-plan.md
+2. **If in-progress**: Wait for it to merge. Do not start work that depends on uncommitted changes.
+3. **If failed/blocked**: Flag for human review. The task may need to be reworked, reordered, or its dependency removed.
+4. **If the dependency is in a different agent's worktree**: Coordinate via AGENTS.md or the task tracking system. Never duplicate work.

package/knowledge/product/gap-analysis.md

@@ -6,7 +6,11 @@ topics: [gap-analysis, requirements, completeness, ambiguity, edge-cases]
 
 # Gap Analysis
 
-Gap analysis is the systematic process of finding what is missing from a set of requirements or specifications. A gap is anything that an implementing team would need to know but that the document does not tell them. Gaps are not errors (things stated incorrectly) — they are omissions (things not stated at all).
+## Summary
+
+Gap analysis is the systematic process of finding what is missing from a set of requirements or specifications. A gap is anything that an implementing team would need to know but that the document does not tell them. Gaps are not errors (things stated incorrectly) — they are omissions (things not stated at all). The process uses section-by-section review, cross-reference checking, edge case enumeration, ambiguity detection, and contradiction detection to surface omissions before they become expensive implementation surprises.
+
+## Deep Guidance
 
 ## Systematic Analysis Approaches
 

package/knowledge/product/prd-innovation.md

@@ -10,6 +10,18 @@ This knowledge covers feature-level innovation — discovering new capabilities,
 
 This is distinct from user story innovation (`user-story-innovation.md`), which covers UX-level enhancements to existing features. If an idea doesn't require a new PRD section or feature entry, it belongs in user story innovation, not here.
 
+## Summary
+
+- **Scope**: Feature-level innovation (new capabilities, competitive gaps, defensive improvements). UX polish on existing features belongs in user story innovation.
+- **Competitive analysis**: Research direct competitors, adjacent products, and emerging patterns. Classify findings as table-stakes (must-have), differentiator (evaluate), or copied-feature (skip).
+- **UX gap analysis**: Evaluate first-60-seconds experience, flow friction points, and missing flows that force workarounds.
+- **Missing expected features**: Search/discovery, data management (bulk import/export, undo), communication (notifications), and personalization (settings, saved views).
+- **AI-native opportunities**: Natural language interfaces, auto-categorization, predictive behavior, and content generation. Must pass the "magic vs. gimmick" test.
+- **Defensive product thinking**: Write plausible 1-star reviews to identify gaps; analyze abandonment barriers (complexity, performance, trust, value, integration).
+- **Evaluation framework**: Cost (trivial/moderate/significant) x Impact (nice-to-have/noticeable/differentiator). Must-have v1 = differentiator at any cost up to moderate, or noticeable at trivial cost.
+
+## Deep Guidance
+
 ## Scope Boundary
 
 **In scope:**

package/knowledge/product/vision-craft.md

@@ -0,0 +1,213 @@
+---
+name: vision-craft
+description: What makes a good product vision — strategic framing, audience definition, competitive positioning, guiding principles
+topics: [vision, strategy, product, positioning, competitive-analysis]
+---
+
+# Vision Craft
+
+A product vision document is the strategic North Star that guides all downstream product decisions. It answers "why does this product exist?" and "what positive change does it create in the world?" — questions that are upstream of the PRD's "what should we build?" Everything in the pipeline flows from the vision. A weak vision produces a PRD without strategic grounding, which produces features without coherent purpose.
+
+## Summary
+
+### Vision Document Structure
+
+A complete product vision document includes these sections:
+1. **Vision Statement** — One inspiring sentence describing the positive change the product creates. Not a feature description. Concise enough to remember and repeat.
+2. **Elevator Pitch** — Geoffrey Moore template: For [target customer] who [need], [product] is a [category] that [key benefit]. Unlike [alternative], our product [differentiation].
+3. **Problem Space** — The pain in vivid detail: who feels it, how they cope, why existing solutions fail.
+4. **Target Audience** — Personas defined by behaviors and motivations, not demographics. Primary and secondary audiences with context of use.
+5. **Value Proposition** — Unique value framed as outcomes, not features. Why someone would choose this over alternatives.
+6. **Competitive Landscape** — Direct competitors, indirect alternatives, "do nothing" option. Honest about strengths and weaknesses.
+7. **Guiding Principles** — 3-5 design tenets framed as prioritization tradeoffs ("We choose X over Y").
+8. **Anti-Vision** — What the product is NOT. Traps to avoid. Directions that would dilute the vision.
+9. **Business Model Intuition** — Revenue model, unit economics assumptions, go-to-market direction.
+10. **Success Criteria** — Leading indicators, year 1 milestones, year 3 aspirations, what failure looks like.
+11. **Strategic Risks & Assumptions** — Key bets, what could invalidate them, severity and mitigation.
+12. **Open Questions** — Unresolved strategic questions for future consideration.
+
+### Quality Criteria
+
+- Vision statement describes positive change, not a product feature
+- Vision statement is concise enough to remember after hearing once
+- Guiding principles create real tradeoffs (if nobody would disagree, it's not a principle)
+- Competitive analysis is honest about the product's weaknesses, not just strengths
+- Target audience describes behaviors and motivations, not demographics
+- Business model section addresses sustainability without being a full business plan
+- Anti-vision prevents real traps, not just vague disclaimers
+
+## Deep Guidance
+
+### Vision Statement
+
+The vision statement is the foundation. If it fails, the entire document lacks a North Star.
+
+#### What Makes a Good Vision Statement
+
+A good vision statement is **inspiring**, **concise**, **enduring**, and **customer-centric**. It describes the positive change the product creates in the world — not a feature, not a business metric.
+
+**Good examples:**
+- "Accelerate the world's transition to sustainable energy" (Tesla)
+- "Belong anywhere" (Airbnb)
+- "Create economic opportunity for every member of the global workforce" (LinkedIn)
+- "Every book ever printed, in any language, all available in 60 seconds" (Kindle)
+- "Make work life simpler, more pleasant, and more productive" (Slack)
+- "Increase the GDP of the internet" (Stripe)
+
+**Bad examples:**
+- "Be the #1 project management tool in the enterprise market" (business metric, not positive change)
+- "Build an AI-powered platform for data analytics" (solution description, not vision)
+- "Provide a seamless user experience for managing tasks" (vague, feature-level)
+- "Disrupt the healthcare industry" (aspirational buzzword, says nothing specific)
+
+#### Roman Pichler's Vision Quality Checklist
+
+- **Inspiring** — Describes a positive change that motivates people
+- **Shared** — Co-created with the team, not handed down from above
+- **Ethical** — Does not cause harm to people or the planet
+- **Concise** — Easy to understand, remember, and repeat
+- **Ambitious** — A big, audacious goal (BHAG) that stretches beyond the comfortable
+- **Enduring** — Guides for 5-10 years; free from solution-specific assumptions
+
+### Geoffrey Moore's Elevator Pitch Template
+
+From *Crossing the Chasm* — the most widely used single-statement framework for articulating product positioning:
+
+```
+For [target customer]
+Who [statement of need or opportunity],
+The [product name] is a [product category]
+That [key benefit, reason to buy].
+Unlike [primary competitive alternative],
+Our product [statement of primary differentiation].
+```
+
+**When to use:** As a structured exercise to force clarity about target customer, need, category, and differentiation. The output should feel like a natural sentence, not a fill-in-the-blank template.
+
+### Guiding Principles
+
+Guiding principles are design tenets that constrain decisions. They are NOT platitudes.
+
+#### The Test
+
+If nobody would disagree with a principle, it's not a principle — it's a platitude. "We value quality" is not a principle. "We choose correctness over speed" is a principle because it implies a real tradeoff (some teams would choose the opposite).
+
+**Good principles (create real tradeoffs):**
+- "We choose simplicity over power" (implies some features won't exist)
+- "We choose transparency over control" (implies users see everything, even messy internals)
+- "We choose speed of iteration over perfection" (implies shipping rough work)
+- "We choose privacy over personalization" (implies less-tailored experiences)
+
+**Bad principles (platitudes):**
+- "We value user experience" (who wouldn't?)
+- "We build reliable software" (this is table stakes, not a principle)
+- "We care about security" (no one would say they don't)
+
+### Anti-Vision
+
+The anti-vision explicitly names what the product is NOT. This is critical for preventing scope creep and maintaining strategic focus.
+
+#### What to Include
+
+- Features the team will be tempted to build but shouldn't
+- Common traps in this product space that catch every competitor
+- Directions that would dilute the core value proposition
+- "If we find ourselves doing X, we've lost the plot"
+
+#### Why It Matters
+
+Without an anti-vision, the team defaults to "yes" for every reasonable-sounding feature request. The anti-vision gives explicit permission to say "no."
+
+### Competitive Landscape
+
+#### Honest Competitive Analysis
+
+The competitive landscape section must be honest — acknowledge what competitors do well, not just where they fall short. A dishonest competitive analysis ("all competitors are terrible") undermines credibility and leads to blind spots in product strategy.
+
+**Structure:**
+- **Direct competitors** — Products solving the same problem for the same users
+- **Indirect alternatives** — Different approaches to the same underlying need
+- **"Do nothing" option** — The status quo. Often the strongest competitor.
+
+For each: what they do well, where they fall short, and why users would choose your product over them.
+
+### Common Anti-Patterns
+
+1. **Confusing Vision with Strategy** — The vision says what the world looks like when the product succeeds. The strategy says how you get there. Keep them separate.
+2. **Tying Vision to a Solution** — "Build the best X" references a specific product form. "Enable Y for Z people" survives pivots.
+3. **Failing to Inspire** — Corporate boilerplate doesn't motivate teams. Co-create the vision; don't hand it down.
+4. **Changing the Vision Frequently** — A vision should endure for years. If it changes quarterly, it's not a vision — it's a roadmap item.
+5. **Overly Broad Target Audience** — "Everyone" is not a target audience. Specificity enables focus.
+6. **Features as Needs** — Listing features (solution space) instead of needs (problem space) limits the team's design freedom.
+7. **Decorative Wall Statement** — A vision that hangs on the wall but never guides actual decisions is worse than no vision at all.
+
+### The Product Development Hierarchy
+
+Vision sits at the top of this hierarchy:
+
+```
+Company Mission / Purpose
+    ↓
+Company Vision
+    ↓
+Product Vision          ← THIS DOCUMENT
+    ↓
+Product Strategy
+    ↓
+Product Requirements    ← PRD (docs/plan.md)
+    ↓
+Implementation
+```
+
+The vision document should inform the PRD, not the other way around. When the PRD and vision conflict, revisit the vision first.
+
+### Success Criteria & Measurement
+
+Success criteria in a vision document are directional — they define what "winning" looks like without the precision of a PRD's success metrics.
+
+#### Levels of Success Measurement
+
+- **Leading indicators** — Early signals that validate the vision direction. These are behavioral: are users doing the thing you expected? Are they coming back? Example: "Users who complete onboarding return within 48 hours."
+- **Year 1 milestones** — Concrete, time-bound achievements that demonstrate market fit. Example: "1,000 active users creating at least one project per week."
+- **Year 3 aspirations** — Ambitious but grounded targets that show the vision is being realized. These should feel like a stretch but not fantasy.
+- **Failure indicators** — What would make this a failure even if it ships on time and works correctly? Example: "If users create an account but never return after day 1, the core value proposition is wrong."
+
+#### Common Mistakes in Success Criteria
+
+- Vanity metrics ("1 million downloads") instead of engagement metrics ("daily active usage")
+- Unmeasurable aspirations ("users love the product") instead of observable behavior
+- Missing the "failure despite shipping" scenario — the most dangerous blind spot
+- Setting criteria so low they're guaranteed, removing the diagnostic value
+
+### Business Model Intuition
+
+The vision document captures directional thinking about sustainability, not a financial model.
+
+#### What to Include
+
+- **Revenue model** — How does this make money? Subscription, freemium, marketplace commission, enterprise licensing, usage-based? Pick one primary model and explain why.
+- **Unit economics direction** — What are the key cost drivers? What does a "unit" of value look like? Does the economics improve with scale?
+- **Go-to-market intuition** — How do users discover this product? Product-led growth, sales-led, community-driven, partnership channels? The answer shapes everything from pricing to features.
+
+#### What NOT to Include
+
+- Detailed financial projections (that's a business plan)
+- Multi-year revenue forecasts (that's a pitch deck)
+- Competitive pricing analysis (that's market research — do it, but don't put it in the vision)
+
+### Vision-to-PRD Handoff
+
+The vision document's primary downstream consumer is the PRD. A well-written vision makes PRD creation straightforward; a vague vision forces the PRD author to make strategic decisions that should have been settled upstream.
+
+#### Handoff Checklist
+
+Before declaring the vision ready for PRD creation, verify:
+
+1. **Problem Space** maps cleanly to PRD's Problem Statement
+2. **Target Audience** personas are specific enough for user stories
+3. **Guiding Principles** are concrete enough to resolve "should we build X?" questions
+4. **Competitive Landscape** provides enough context to differentiate features
+5. **Anti-Vision** is clear enough to reject out-of-scope feature requests
+6. **Open Questions** do not include anything that would block product definition
+
+If any of these fail, the vision needs another pass before the PRD can begin.

package/knowledge/review/review-adr.md

@@ -10,6 +10,18 @@ ADRs encode the "why" behind the architecture. They must be complete (every sign
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — Decision Coverage**: Every significant architectural decision has an ADR; technology choices, pattern selections, and constraint trade-offs all recorded.
+- **Pass 2 — Rationale Quality**: Alternatives are genuinely viable (not straw-manned); consequences are honest with both positives and negatives.
+- **Pass 3 — Contradiction Detection**: No two ADRs make conflicting decisions without explicit acknowledgment; supersession relationships documented.
+- **Pass 4 — Implied Decision Mining**: Decisions visible in artifacts but never formally recorded as ADRs are identified and flagged.
+- **Pass 5 — Status Hygiene**: ADR statuses reflect reality; no stale "proposed" ADRs; supersession chains are clean.
+- **Pass 6 — Cross-Reference Integrity**: Cross-references between ADRs are correct and bidirectional; no broken or circular reference chains.
+- **Pass 7 — Downstream Readiness**: Technology and pattern decisions are finalized in "accepted" status so architecture can proceed without ambiguity.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: Decision Coverage

package/knowledge/review/review-api-design.md

@@ -10,6 +10,19 @@ API contracts define the system's external and internal interfaces. They must co
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — Operation Coverage**: Every domain operation crossing a component boundary has a corresponding API endpoint; no missing CRUD or query operations.
+- **Pass 2 — Error Contract Completeness**: Every endpoint has explicit error responses with status codes, body structure, and triggering conditions.
+- **Pass 3 — Auth/AuthZ Coverage**: Every endpoint specifies authentication and authorization requirements; no ambiguous access control.
+- **Pass 4 — Versioning Consistency**: API versioning strategy is consistent across all endpoints and aligns with the ADR.
+- **Pass 5 — Payload Shape vs Domain Entities**: Request/response payloads align with domain model entities in naming, types, and structure.
+- **Pass 6 — Idempotency**: Mutating operations document idempotency behavior; operations with side effects specify the mechanism.
+- **Pass 7 — Pagination/Filtering**: List endpoints have pagination, filter, and sort parameters documented with response metadata.
+- **Pass 8 — Downstream Readiness**: API provides everything needed for UX spec (screen data, error states) and implementation tasks (complexity, dependencies).
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: Operation Coverage