@zigrivers/scaffold 2.1.2 → 2.38.0

package/knowledge/execution/tdd-execution-loop.md

@@ -0,0 +1,172 @@
+---
+name: tdd-execution-loop
+description: Red-green-refactor execution cycle for AI agents
+topics: [tdd, execution, testing, workflow]
+---
+
+# TDD Execution Loop
+
+Expert knowledge for the core TDD execution loop that AI agents follow during implementation. This defines the disciplined red-green-refactor cycle, commit timing, and test-first practices that ensure every change is verified before it ships.
+
+## Summary
+
+### Red-Green-Refactor Cycle
+
+```
+  RED         GREEN        REFACTOR
+  Write a  →  Write the  →  Clean up
+  failing     minimal       without
+  test        code to       changing
+              pass it       behavior
+```
+
+Each cycle produces one small, verified increment of functionality.
+
+### Commit Timing
+
+- **Commit after green** — every passing test is a safe checkpoint
+- **Commit after refactor** — clean code locked in before the next feature
+- **Never commit red** — a failing test in history breaks bisect and reverts
+
+### Test-First Discipline
+
+- Always write the test before the implementation
+- Verify the test actually fails (red) before writing production code
+- A test that never failed might not be testing anything meaningful
+
+## Deep Guidance
+
+### Red-Green-Refactor Cycle — Extended
+
+#### Red Phase: Write a Failing Test
+
+Write a test that describes the next small piece of behavior you want to add. Run it and confirm it fails. The failure message should clearly indicate what is missing.
+
+**Key rules:**
+- The test must fail for the right reason (missing function, wrong return value — not a syntax error or import failure)
+- Write only one test at a time — don't batch multiple behaviors into a single red phase
+- The test name should describe the expected behavior: `returns 404 when user not found`, not `test user endpoint`
+
+#### Green Phase: Minimal Implementation
+
+Write the smallest amount of production code that makes the failing test pass. Do not add logic for future tests, handle edge cases you haven't tested yet, or optimize.
+
+**Key rules:**
+- If you can make the test pass by returning a hard-coded value, that's valid — the next test will force generalization
+- Don't refactor during the green phase — just make it pass
+- Run the full relevant test suite (not just the new test) to confirm you haven't broken anything
+
+#### Refactor Phase: Clean Up
+
+With all tests green, improve the code's structure, readability, and design without changing its behavior. The tests are your safety net.
+
+**Common refactors:**
+- Extract duplicate code into helper functions
+- Rename variables and functions for clarity
+- Simplify conditionals
+- Move code to better locations (closer to where it's used)
+
+**Key rules:**
+- All tests must remain green throughout refactoring
+- If a refactor breaks a test, undo and take a smaller step
+- Commit after a successful refactor before starting the next red phase
+
+### When to Commit
+
+| Event | Commit? | Why |
+|-------|---------|-----|
+| Test goes green | Yes | Safe checkpoint with verified behavior |
+| Refactor complete, tests still green | Yes | Lock in clean code |
+| Test is red (failing) | No | Broken state in history breaks bisect |
+| Mid-implementation, nothing passes yet | No | Partial work has no verified value |
+| Multiple tests green at once | Yes | But prefer smaller commits |
+
+Ideal commit cadence: every 5-15 minutes during active TDD. If you haven't committed in 30 minutes, you're taking too large a step.
+
+### PR Creation Patterns
+
+- **One PR per task** — a PR should map to a single task, story, or unit of work
+- **Descriptive titles** — `feat(auth): add password reset flow` not `auth changes`
+- **Test evidence in description** — include which tests were added, what they cover, and that they pass
+- **Link to task ID** — reference the task, story, or issue that motivated the work
+- **Small PRs** — prefer 50-200 lines changed; split larger work into sequential PRs
+
+### Test-First Discipline — Extended
+
+**Why test-first matters:**
+- Forces you to think about the interface before the implementation
+- Prevents writing untestable code (if you can't test it first, the design needs work)
+- Creates a failing test that proves your test actually exercises the code path
+- Produces a test suite where every test has been observed to fail — higher confidence
+
+**Common violations to avoid:**
+- Writing implementation first, then adding tests after (tests may not cover the actual behavior)
+- Writing a test that passes immediately (it might be testing the wrong thing)
+- Skipping the red step "because you know the implementation is correct" (hubris)
+
+### Handling Flaky Tests
+
+Flaky tests — tests that pass sometimes and fail other times — are bugs. Treat them with urgency.
+
+**Investigation steps:**
+1. Run the test in isolation 10 times to confirm flakiness
+2. Check for common causes: time-dependent logic, race conditions, shared mutable state, network calls, random data
+3. Fix the root cause, don't add retries
+
+**Never:**
+- Add `retry(3)` to make a flaky test pass — this hides the bug
+- Mark as `skip` without filing a tracking issue
+- Ignore flaky tests in CI — they erode trust in the entire suite
+
+### Slow Test Suites
+
+When the full test suite takes too long for rapid TDD:
+
+**During development:**
+- Run only the focused subset (tests for the module you're changing)
+- Use test runner watch mode to re-run on file change
+- Tag tests by level (unit, integration, e2e) and run only unit during red-green-refactor
+
+**Before PR creation:**
+- Run the full test suite locally
+- Confirm CI will run the complete suite
+- Don't submit a PR if you haven't verified the full suite passes
+
+**Reducing suite time:**
+- Move logic tests from integration/e2e to unit level
+- Parallelize test execution
+- Use transaction rollback instead of database recreation
+- Profile the slowest tests and optimize or split them
+
+### Test Isolation
+
+Each test must be independent — it should pass or fail regardless of what other tests run before it, after it, or alongside it.
+
+**Rules:**
+- No shared mutable state between tests (global variables, class-level state, database rows from a previous test)
+- Each test sets up its own preconditions and cleans up after itself
+- Tests should pass when run individually, in any order, or in parallel
+- Use `beforeEach`/`setUp` for common setup, not test-to-test data flow
+- Avoid `beforeAll`/`setUpClass` unless the shared resource is truly read-only
+
+**Detecting isolation violations:**
+- Run tests in random order — if they fail, they have hidden dependencies
+- Run a single test in isolation — if it fails only when run alone, it depends on setup from another test
+
+### When to Stop and Ask
+
+TDD assumes clear requirements. When requirements are unclear, continuing to write tests is wasteful. Stop and ask when:
+
+- **Unclear requirements** — the acceptance criteria are ambiguous or contradictory
+- **Architectural ambiguity** — you're unsure which module should own the behavior
+- **Conflicting documentation** — the PRD says one thing, the user stories say another
+- **Scope creep** — the task is growing beyond what was originally planned
+- **Blocked by another task** — you need output from a task that hasn't been completed yet
+- **Unfamiliar domain** — you don't understand the business rules well enough to write a meaningful test
+
+Document what you know, what you don't, and what decision you need — then ask.
+
+## See Also
+
+- [testing-strategy](../core/testing-strategy.md) — Test pyramid, coverage strategy, quality gates
+- [task-claiming-strategy](./task-claiming-strategy.md) — Task selection and dependency awareness

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:
@@ -30,44 +42,148 @@ Minor polish, documentation gaps that don't affect implementation correctness, a
 
 **Examples**: Missing UX specs for secondary flows, incomplete examples in knowledge base entries, editorial inconsistencies in prose.
 
+### Categorization Methodology
+
+When collecting findings from multiple validation reports, assign each finding to exactly one category using these decision rules:
+
+1. **Would an agent produce incorrect code if this is not fixed?** -> P0
+2. **Would an agent have to guess or make assumptions?** -> P1
+3. **Is the issue real but unlikely to affect implementation correctness?** -> P2
+
+When a finding spans multiple categories (e.g., a stale count that is also ambiguous), assign it to the highest applicable priority. Do not duplicate findings across priority levels.
+
 ## Fix Application Process
 
 ### Step 1: Build the Fix Plan
 
 1. Collect all findings from validation phase outputs (cross-phase-consistency, traceability-matrix, decision-completeness, critical-path-walkthrough, implementability-dry-run, dependency-graph-validation, scope-creep-check).
-2. Deduplicate — the same root cause often appears in multiple validation reports.
+2. Deduplicate — the same root cause often appears in multiple validation reports. When a single root cause appears in 3+ reports, mark it as a **systemic issue** and track it separately.
 3. Group by affected document — batch fixes to minimize file churn.
 4. Order by priority (P0 first), then by document (reduce context switching).
+5. Estimate impact radius for each fix — how many other documents does this fix touch?
+
+#### Fix Plan Output Format
+
+The fix plan is a working document that guides fix execution. Structure it as follows:
+
+```markdown
+## Fix Plan
+
+### Systemic Issues (multi-document root causes)
+| ID | Root Cause | Affected Documents | Priority | Est. Impact |
+|----|------------|-------------------|----------|-------------|
+| SYS-1 | Pipeline expanded from 32→36 steps, counts not propagated | architecture, state-schema, cli-contract, 12 others | P0 | 15 files |
+
+### Individual Fixes
+| ID | Finding Source | Finding | Priority | Target Document | Dependencies |
+|----|--------------|---------|----------|-----------------|--------------|
+| FIX-1 | CPC-007 | Terminology drift: "prompts" vs "steps" | P0 | state-json-schema.md | FIX-2 |
+| FIX-2 | CPC-007 | Terminology drift: "prompts" vs "steps" | P0 | cli-contract.md | — |
+```
 
 ### Step 2: Apply Fixes
 
 For each fix:
 1. Read the finding and the affected document section.
-2. Make the minimal change that resolves the finding.
-3. Check whether the fix affects other documents (e.g., changing a field name in the schema requires updating API contracts and state documentation).
+2. Make the minimal change that resolves the finding. Do not refactor, improve prose, or add features — fix only what the finding identifies.
+3. Check whether the fix affects other documents (e.g., changing a field name in the schema requires updating API contracts and state documentation). Use project-wide search to find all references before changing any term.
 4. Log the fix in `docs/validation/fix-log.md` with: finding ID, affected files, what changed, why.
+5. For systemic issues, fix the source of truth first, then sweep all downstream references in a single pass.
+
+#### Fix Execution Rules
+
+- **One finding per commit** (or one systemic issue per commit). This makes rollback possible if a fix introduces a regression.
+- **Fix forward, not around.** If a finding reveals a design mistake, fix the design — do not patch the symptom.
+- **Preserve document structure.** Fixes should not reorganize sections, add new headings, or change formatting conventions. Content changes only.
+- **Cross-document fixes must be atomic.** If a terminology change spans 5 files, update all 5 in the same commit. A half-applied rename is worse than the original inconsistency.
+
+### Step 3: Re-validation
 
-### Step 3: Verify No Regressions
+After all fixes are applied, re-validate to confirm fixes resolved the findings without introducing new issues:
 
-After all fixes are applied:
-1. Re-run cross-phase consistency checks on modified documents.
-2. Verify traceability links still resolve (no broken references introduced by renames).
-3. Spot-check that counts, terminology, and cross-references are internally consistent.
-4. If a fix introduced a new issue, treat it as a P0 and resolve before proceeding.
+1. **Re-run affected validation checks.** For each fix, identify which validation pass originally flagged it and re-run that specific check against the modified document(s). At minimum, re-run:
+   - Cross-phase consistency checks on all modified documents
+   - Traceability link resolution (no broken references introduced by renames)
+   - Scope-creep check (fixes did not add new requirements)
+2. **Spot-check adjacent sections.** When a fix modifies a section, read the surrounding sections in the same document to verify internal consistency was not broken.
+3. **Verify counts and cross-references.** Any fix that changes a quantity (step count, story count, task count) requires verifying every other document that cites that quantity.
+4. **Regression test systemic fixes.** For systemic issues that touched many files, grep for the old term/value across the entire docs directory to confirm no instances were missed.
+5. **If re-validation finds new issues**, treat them as P0 findings and loop back to Step 2. The fix→revalidate cycle continues until re-validation produces zero new findings.
+
+#### Re-validation Output
+
+Record re-validation results alongside the fix log:
+
+```markdown
+## Re-validation Results
+
+| Fix ID | Re-validation Check | Result | Notes |
+|--------|-------------------|--------|-------|
+| FIX-1 | CPC re-run | PASS | All "step" references consistent |
+| FIX-3 | Traceability links | FAIL | New broken ref in tasks.md line 47 |
+```
 
 ## Documentation Freeze
 
-Once all P0 and P1 findings are resolved:
+Once all P0 and P1 findings are resolved and re-validation produces zero new findings:
 
 1. Add a freeze marker (tracking comment) to each phase artifact indicating the document is implementation-ready.
 2. Record the freeze timestamp and the validation findings that were addressed.
 3. P2 deferrals are logged in the fix log with rationale — these become backlog items for post-implementation polish.
 
+### Freeze Criteria Checklist
+
+Before declaring freeze, verify all of the following:
+
+- [ ] All P0 findings resolved and re-validated
+- [ ] All P1 findings resolved (or explicitly risk-accepted with documented rationale)
+- [ ] Re-validation produced zero new findings on the final pass
+- [ ] Fix log is complete with all changes documented
+- [ ] P2 deferrals are logged with rationale
+- [ ] Cross-document counts are internally consistent (final count sweep)
+- [ ] All traceability links resolve (no dangling references)
+- [ ] Terminology is consistent across all documents (final terminology sweep)
+
 ### What Freeze Means
 
 - **No further content changes** unless implementation reveals a genuine gap (not a preference).
 - **Formatting and typo fixes** are allowed — they don't affect implementation.
 - **If a gap is found during implementation**, the fix goes through the same prioritization process: update the document, log the change, re-verify consistency.
+- **Freeze does NOT mean the documents are perfect.** P2 deferrals exist. The standard is implementation readiness — an implementing agent can produce correct code from these documents without guessing.
+
+### What Is Allowed After Freeze
+
+| Change Type | Allowed? | Process |
+|------------|----------|---------|
+| Typo fixes, formatting | Yes | Direct edit, no re-validation needed |
+| Gap discovered during implementation | Yes | Prioritize as P0/P1, apply fix, re-validate affected section, log in fix log |
+| "Nice to have" improvements | No | Log as P2 deferral for post-implementation |
+| Scope additions | No | Out of scope — must go through PRD amendment process |
+| Terminology alignment (missed in freeze) | Yes | Treat as P0 fix, apply and re-validate |
+
+### Freeze Marker Format
+
+Add the following marker to the top of each frozen document, immediately after the frontmatter:
+
+```markdown
+<!-- FROZEN: Implementation-ready as of YYYY-MM-DD. Changes require fix-log entry. -->
+```
+
+### Frozen Artifact Set
+
+The complete set of frozen artifacts should be documented in the fix log as a manifest:
+
+```markdown
+## Frozen Artifact Manifest
+
+| Document | Freeze Date | P0 Fixes | P1 Fixes | P2 Deferred |
+|----------|------------|----------|----------|-------------|
+| docs/plan.md | 2025-01-15 | 0 | 2 | 1 |
+| docs/system-architecture.md | 2025-01-15 | 3 | 4 | 2 |
+| docs/api-contracts.md | 2025-01-15 | 1 | 1 | 0 |
+| docs/database-schema.md | 2025-01-15 | 2 | 3 | 1 |
+| ... | ... | ... | ... | ... |
+```
 
 ## Fix Log Format
 
@@ -85,9 +201,56 @@ Once all P0 and P1 findings are resolved:
 | 1 | IR-012: Missing adopt-flow UX spec | Low implementation impact; adopt is secondary flow |
 ```
 
+## The Fix-Revalidate-Freeze Cycle
+
+The full process follows a strict cycle:
+
+```
+Collect findings
+    │
+    ▼
+Build fix plan (categorize, prioritize, estimate impact)
+    │
+    ▼
+┌─> Apply fixes (one finding or systemic issue per commit)
+│       │
+│       ▼
+│   Re-validate (re-run affected checks, spot-check adjacent sections)
+│       │
+│       ▼
+│   New findings? ──Yes──┐
+│       │                │
+│       No               │
+│       │                │
+│       ▼                │
+│   Freeze criteria met? │
+│       │                │
+│       No               │
+│       │                │
+└───────┘ ◄──────────────┘
+        │
+        Yes
+        │
+        ▼
+   Declare freeze (add markers, create manifest, log deferrals)
+```
+
+Each iteration through the cycle should produce strictly fewer findings than the previous iteration. If the count of findings is not decreasing, stop and investigate — you may be fixing symptoms while the root cause persists.
+
 ## Common Pitfalls
 
-1. **Fixing symptoms instead of root causes.** If the same stale count appears in 15 files, the root cause is a single pipeline change that wasn't propagated. Fix the source and sweep all references.
-2. **Introducing new inconsistencies.** Renaming a field in one document but missing it in another. Always search for all references before changing a term.
-3. **Over-fixing.** The goal is implementation readiness, not perfection. If a P2 finding doesn't affect an implementing agent's ability to produce correct code, defer it.
-4. **Skipping verification.** A fix that breaks a cross-reference is worse than the original finding. Always re-verify after applying fixes.
+1. **Fixing symptoms instead of root causes.** If the same stale count appears in 15 files, the root cause is a single pipeline change that wasn't propagated. Fix the source and sweep all references. A good diagnostic: if your fix plan has 10+ individual fixes that all trace to the same upstream change, consolidate them into one systemic fix.
+
+2. **Introducing new inconsistencies.** Renaming a field in one document but missing it in another. Always search for all references before changing a term. Run a project-wide grep for the old term after every rename.
+
+3. **Over-fixing.** The goal is implementation readiness, not perfection. If a P2 finding doesn't affect an implementing agent's ability to produce correct code, defer it. A common trap: improving prose clarity during the fix phase. This is not fixing — it is editing, and it risks introducing new inconsistencies.
+
+4. **Skipping re-validation.** A fix that breaks a cross-reference is worse than the original finding. Always re-validate after applying fixes. The most dangerous fixes are the ones that "obviously" don't need re-validation — those are the ones that introduce silent regressions.
+
+5. **Premature freeze.** Declaring freeze before all P0 and P1 findings are resolved because of time pressure. A premature freeze sends agents into implementation with known issues, guaranteeing rework. If time is short, reduce scope (defer entire features) rather than freezing with known P0 issues.
+
+6. **Scope creep during the fix phase.** A finding says "the error format is unspecified" and the fix adds a complete error taxonomy, error codes, error localization strategy, and retry semantics. The fix should specify the minimum error format needed for implementation. Everything else is new scope.
+
+7. **Infinite fix loops.** Each fix introduces a new finding, which requires another fix, which introduces another finding. This happens when fixes are too broad (changing things beyond what the finding requires) or when the underlying documents have systemic structural problems. Break the loop by: (a) making smaller, more targeted fixes, or (b) stepping back to identify the structural issue and fixing that instead.
+
+8. **Incomplete fix log.** Applying fixes without logging them. The fix log is not bureaucracy — it is the audit trail that proves the freeze is valid. If an implementation agent later questions a design choice, the fix log explains why the document says what it says.

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