knowzcode 0.3.1 → 0.3.6

package/commands/work.md

@@ -66,11 +66,15 @@ If `knowzcode/knowzcode_orchestration.md` exists, parse its YAML blocks:
 2. `SCOUT_MODE` = `scout_mode` value (default: "full")
 3. `DEFAULT_SPECIALISTS` = `default_specialists` value (default: [])
 4. `MCP_AGENTS_ENABLED` = `mcp_agents_enabled` value (default: true)
+5. `CODEBASE_SCANNER_ENABLED` = `codebase_scanner_enabled` value (default: true)
+6. `PARALLEL_SPEC_THRESHOLD` = `parallel_spec_threshold` value (default: 3, clamp to 2-10)
 
 Apply flag overrides (flags win over config):
 - `--max-builders=N` in `$ARGUMENTS` → override `MAX_BUILDERS`
 - `--no-scouts` in `$ARGUMENTS` → override `SCOUT_MODE = "none"`
 - `--no-mcp` in `$ARGUMENTS` → override `MCP_AGENTS_ENABLED = false`
+- `--no-scanners` in `$ARGUMENTS` → override `CODEBASE_SCANNER_ENABLED = false`
+- `--no-parallel-specs` in `$ARGUMENTS` → override `PARALLEL_SPEC_THRESHOLD = 999` (effectively disabled)
 
 If the file doesn't exist, use hardcoded defaults (current behavior).
 
@@ -354,7 +358,13 @@ When Parallel Teams mode is active, follow these 4 stages instead of spawning on
    - If `SCOUT_MODE = "none"`: spawn analyst + architect only (2 agents). Analyst and architect scan the codebase independently without pre-loaded scout context.
    - Always:
      - `TaskCreate("Phase 1A: Impact analysis for {goal}")` → `TaskUpdate(owner: "analyst")`
-     - `TaskCreate("Pre-load architecture context")` → `TaskUpdate(owner: "architect")`
+     - `TaskCreate("Pre-load architecture context and speculative research")` → `TaskUpdate(owner: "architect")`
+   - If `CODEBASE_SCANNER_ENABLED = true` (default):
+     - Derive two search focuses from the goal:
+       - **Scanner-Direct**: source code search — grep for goal keywords, read affected code paths
+       - **Scanner-Tests**: test discovery — search test directories for tests covering the goal area
+     - `TaskCreate("Scanner: direct codebase scan for {goal}")` → `TaskUpdate(owner: "scanner-direct")`
+     - `TaskCreate("Scanner: test coverage scan for {goal}")` → `TaskUpdate(owner: "scanner-tests")`
    Spawn all Group A agents with their `{task-id}` in the spawn prompt (use spawn prompts from Phase Prompt Reference below).
 5. **Spawn Group B** (MCP agents — same turn as Group A): If `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`:
    Create tasks first, pre-assign, then spawn with task IDs:
@@ -369,16 +379,17 @@ When Parallel Teams mode is active, follow these 4 stages instead of spawning on
    - If `project-advisor` in list: `TaskCreate("Project advisor: backlog context")` → `TaskUpdate(owner: "project-advisor")`
    Spawn each enabled specialist with its `{task-id}` in the spawn prompt (use spawn prompts from Specialist Spawn Prompts section below).
    If `SPECIALISTS_ENABLED` is empty, skip Group C.
-7. **Roster confirmation** — lead lists every spawned agent by name to the user. Include Group C specialists if active. If `VAULTS_CONFIGURED` was true but knowz-scout or knowz-scribe is missing from the roster, STOP and re-spawn the missing agent(s) before continuing.
-8. All spawned agents work immediately in parallel (context scouts are cheap Sonnet read-only agents; knowz-scribe is a cheap Haiku agent; specialists are Sonnet read-only agents). Agent count depends on orchestration config: 2-10 agents at Stage 0.
+7. **Roster confirmation** — lead lists every spawned agent by name to the user. Include scanners and Group C specialists if active. If `VAULTS_CONFIGURED` was true but knowz-scout or knowz-scribe is missing from the roster, STOP and re-spawn the missing agent(s) before continuing.
+8. All spawned agents work immediately in parallel (context scouts are cheap Sonnet read-only agents; scanners are lightweight general-purpose agents; knowz-scribe is a cheap Haiku agent; specialists are Sonnet read-only agents). Agent count depends on orchestration config: 2-12 agents at Stage 0.
 9. Scouts broadcast findings → analyst and architect consume as messages. Specialists work independently on their Stage 0 tasks.
 
-**Key**: The analyst does NOT wait for scouts or specialists to finish. It starts scanning the codebase immediately. Scout findings arrive as messages and enrich the analyst's work as they arrive. Specialist findings are consumed by the lead at gates.
+**Key**: The analyst does NOT wait for scouts, scanners, or specialists to finish. It starts scanning the codebase immediately. Scout and scanner findings arrive as messages and enrich the analyst's work as they arrive. The analyst also streams `[PRELIMINARY]` NodeID findings to the architect as it discovers them (see Preliminary Findings Protocol). Specialist findings are consumed by the lead at gates.
 
 ### Stage 1: Analysis + Specification
 
 1. Analyst completes Change Set (includes dependency map — see `agents/analyst.md`)
 2. Lead reads analyst's task summary
+3. Shut down scanners (scanner-direct, scanner-tests) if they were spawned — no longer needed after analysis
 3. **Specialist Change Set reviews** (if `SPECIALISTS_ENABLED` non-empty): Create review tasks blocked on analysis:
    - If `security-officer` active: `TaskCreate("Security officer: Change Set review", addBlockedBy: [analysis-task-id])` → `TaskUpdate(owner: "security-officer")`. DM security-officer: `"**New Task**: #{task-id} — Review Change Set for security risk. Rate each NodeID."`
    - If `test-advisor` active: `TaskCreate("Test advisor: Change Set test strategy", addBlockedBy: [analysis-task-id])` → `TaskUpdate(owner: "test-advisor")`. DM test-advisor: `"**New Task**: #{task-id} — Recommend test types per NodeID."`
@@ -389,12 +400,29 @@ When Parallel Teams mode is active, follow these 4 stages instead of spawning on
    - Specialist Reports (if active — see gate template below)
 5. User approves (or rejects → re-run analyst with feedback)
 6. Lead sends DM to architect with the approved Change Set
-7. Lead creates spec-drafting tasks for architect (1 task per NodeID, `addBlockedBy: [analysis-task-id]`):
-   - `TaskCreate("Spec: NodeID-X")` → `TaskUpdate(taskId, owner: "architect")`
-   - DM architect with task IDs: `"**New Tasks**: #{id-1} Spec: NodeID-A, #{id-2} Spec: NodeID-B. Approved Change Set: {summary}"`
-   - Architect is already warm (pre-loaded during Stage 0) → specs drafted FAST
+7. **Spec Drafting** — choose path based on NodeID count and `PARALLEL_SPEC_THRESHOLD`:
+
+   **Path A: Standard (fewer than PARALLEL_SPEC_THRESHOLD NodeIDs)**
+   - Lead creates spec-drafting tasks for architect (1 task per NodeID, `addBlockedBy: [analysis-task-id]`):
+     - `TaskCreate("Spec: NodeID-X")` → `TaskUpdate(taskId, owner: "architect")`
+     - DM architect with task IDs: `"**New Tasks**: #{id-1} Spec: NodeID-A, #{id-2} Spec: NodeID-B. Approved Change Set: {summary}"`
+   - Architect is already warm (pre-loaded + speculative research during Stage 0) → specs drafted FAST
    - If Gate #1 rejected: shut down architect, re-run analyst with feedback, re-spawn architect after
-8. Architect completes specs
+
+   **Path B: Parallel Spec Drafting (PARALLEL_SPEC_THRESHOLD or more NodeIDs)**
+   - Lead DMs architect the full approved Change Set and asks for a partition plan (see `agents/architect.md` — Parallel Spec Coordination)
+   - Architect proposes NodeID partitions (1-2 NodeIDs each, max 3 partitions, respecting same-spec and interface constraints)
+   - Lead spawns spec-drafter agents — one per partition:
+     - Spec-drafters use the `architect` agent definition with a scoped spawn prompt
+     - Each drafter gets: its NodeID partition, architect's research findings, cross-NodeID interface constraints, consolidation instructions
+     - `TaskCreate("Spec draft: NodeID-A, NodeID-B")` → `TaskUpdate(owner: "spec-drafter-1")`
+     - Max 3 spec-drafters: `ceil(NodeID_count / 2)`, capped at 3
+   - Spec-drafters draft specs in parallel
+   - After all spec-drafters complete: architect runs consistency review (cross-spec alignment, naming, VERIFY coverage)
+   - Shut down spec-drafters after consistency review
+   - If Gate #1 rejected: shut down architect and any spec-drafters, re-run analyst with feedback, re-spawn architect after
+
+8. Architect completes specs (Path A) or architect completes consistency review (Path B)
 9. **Test-advisor spec review** (if `test-advisor` in `SPECIALISTS_ENABLED`): After specs drafted, create spec testability review task:
    - `TaskCreate("Test advisor: spec testability review", addBlockedBy: [spec-task-id])` → `TaskUpdate(owner: "test-advisor")`
    - DM test-advisor: `"**New Task**: #{task-id} — Review specs for testability. Check VERIFY criteria are automatable."`
@@ -508,11 +536,16 @@ When Parallel Teams mode is active, follow these 4 stages instead of spawning on
    - Write ARC-Completion log entry
    - Review architecture docs for discrepancies
    - Schedule REFACTOR tasks for tech debt
-   - Send learnings to knowz-scribe (if active): `"Capture Phase 3: {wgid}"`. Knowz-scout remains available for vault queries during finalization.
+   - Create capture task for knowz-scribe (if active): `TaskCreate("Scribe: Capture Phase 3")` → `TaskUpdate(owner: "knowz-scribe")`, then send DM with task ID: `"Capture Phase 3: {wgid}. Your task: #{task-id}"`. Knowz-scout remains available for vault queries during finalization.
    - Create final atomic commit
 4. Lead presents completion summary
-5. Shut down knowz-scout, knowz-scribe (after Phase 3 capture completes), closer, and all remaining agents
-6. Delete team
+5. **Wait for scribe Phase 3 capture** (if knowz-scribe is active):
+   - Check scribe capture task via `TaskGet(task-id)` — wait until status is `completed`
+   - Also wait for scribe's Phase 3 confirmation DM
+   - **Timeout**: If >2 minutes after closer completes and scribe task still not complete → DM scribe: `"Status check: Phase 3 capture for {wgid}?"`
+   - **Hard timeout**: If another minute passes with no completion → proceed with shutdown and log `WARNING: Scribe Phase 3 capture did not complete for {wgid}. Vault writes may be incomplete.`
+6. Shutdown order: knowz-scout, knowz-scribe, closer, remaining agents
+7. Delete team
 
 ### WorkGroup File Format (Parallel Mode)
 
@@ -544,14 +577,17 @@ When creating tasks, model the dependency chain with `addBlockedBy` and pre-assi
 | Scout: backlog context | (none) | context-scout-backlog |
 | Knowz-scout: vault queries | (none — persistent) | knowz-scout |
 | Knowz-scribe: listen | (none — persistent) | knowz-scribe |
-| Phase 1A analysis | (none — scouts enrich via broadcast) | analyst |
-| Architect pre-load | (none) | architect |
+| Scanner: direct codebase scan | (none) | scanner-direct |
+| Scanner: test coverage scan | (none) | scanner-tests |
+| Phase 1A analysis | (none — scouts + scanners enrich via broadcast) | analyst |
+| Architect pre-load + speculative research | (none — receives [PRELIMINARY] DMs from analyst) | architect |
 | Security officer: initial threat scan | (none — Group C) | security-officer |
 | Test advisor: coverage baseline | (none — Group C) | test-advisor |
 | Project advisor: backlog context | (none — Group C) | project-advisor |
 | Security officer: Change Set review | Phase 1A analysis | security-officer |
 | Test advisor: Change Set test strategy | Phase 1A analysis | test-advisor |
-| Spec: NodeID-X | Phase 1A (gate approval) | architect |
+| Spec: NodeID-X | Phase 1A (gate approval) | architect (Path A) or spec-drafter-N (Path B) |
+| Spec consistency review | All spec drafts complete (Path B only) | architect |
 | Test advisor: spec testability review | Spec: NodeID-X | test-advisor |
 | Implement: NodeID-X | Spec: NodeID-X | builder-N |
 | Audit: NodeID-X | Implement: NodeID-X | reviewer-N |
@@ -561,6 +597,10 @@ When creating tasks, model the dependency chain with `addBlockedBy` and pre-assi
 | Fix gaps: NodeID-X round N | Audit: NodeID-X (or re-audit N-1) | builder-N |
 | Re-audit: NodeID-X round N | Fix gaps round N | reviewer-N |
 | Phase 3 finalization | All audits approved | closer |
+| Scribe: Capture Phase 1A | Phase 1A (gate approval) | knowz-scribe |
+| Scribe: Capture Phase 2A | Implement: NodeID-X | knowz-scribe |
+| Scribe: Capture Phase 2B | All audits approved | knowz-scribe |
+| Scribe: Capture Phase 3 | Phase 3 finalization | knowz-scribe |
 
 ---
 
@@ -631,6 +671,51 @@ Three instances of the same agent, each focused on a different local folder grou
 
 ---
 
+## Stage 0: Codebase Scanners (2 instances — conditional)
+
+**Agent**: `general-purpose` (x2) | Lightweight codebase searchers (no agent definition file)
+
+Two temporary agents that scan the codebase in parallel with the analyst, broadcasting findings to accelerate impact analysis. Only spawned when `CODEBASE_SCANNER_ENABLED = true` (default).
+
+**scanner-direct spawn prompt**:
+> You are `scanner-direct` for WorkGroup `{wgid}`.
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Goal**: {goal}
+> **Focus**: Search source code for goal-related keywords and patterns.
+>
+> **Steps**:
+> 1. Grep for goal keywords across source files (exclude node_modules, dist, build, .git)
+> 2. Read the top 5-8 matching files to understand affected code paths
+> 3. Identify module boundaries and cross-module dependencies
+> 4. Note public APIs and interfaces that may need changes
+>
+> **READ-ONLY.** Do NOT modify any files.
+> **Deliverable**: Broadcast findings to all teammates — affected files, code paths, module boundaries, and interface patterns.
+> **Budget**: Complete within ~12 turns. Focus on breadth over depth.
+
+**scanner-tests spawn prompt**:
+> You are `scanner-tests` for WorkGroup `{wgid}`.
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Goal**: {goal}
+> **Focus**: Discover tests covering the goal area to understand test patterns and coverage shape.
+>
+> **Steps**:
+> 1. Glob for test files: `**/*.test.*`, `**/*.spec.*`, `**/test_*`, `**/tests/**`
+> 2. Grep test files for goal-related keywords
+> 3. Read 3-5 matching test files to understand testing patterns (test framework, mocking strategy, fixture patterns)
+> 4. Check for integration/e2e tests related to the goal area
+>
+> **READ-ONLY.** Do NOT modify any files.
+> **Deliverable**: Broadcast findings to all teammates — test file locations, testing patterns, coverage gaps, and fixture/mock patterns.
+> **Budget**: Complete within ~12 turns. Focus on breadth over depth.
+
+**Dispatch**:
+- *Parallel Teams*: Spawned at Stage 0 if `CODEBASE_SCANNER_ENABLED = true`. Use `subagent_type: "general-purpose"`, `maxTurns: 12`. Shut down after Stage 1 (analyst completes Change Set).
+- *Sequential Teams*: Not applicable (scanners are Parallel Teams only).
+- *Subagent*: `Task(subagent_type="general-purpose", description="Scan codebase for {focus}", maxTurns=12, prompt=<above>)` if `CODEBASE_SCANNER_ENABLED = true`.
+
+---
+
 ## Stage 0: Knowz Scout
 
 **Agent**: `knowz-scout` | MCP vault researcher and knowledge agent
@@ -740,10 +825,12 @@ The spawn prompts below are used when `SPECIALISTS_ENABLED` is non-empty. Specia
 >
 > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
 > **Conventions**: Update WorkGroup file with results (prefix entries with `KnowzCode:`). If blocked, report blocker and notify lead.
+> **Codebase scanners**: Scanner agents are running in parallel — their findings will arrive as broadcast messages. Incorporate them into your analysis but do NOT wait for them.
+> **Preliminary Findings Protocol**: As you discover high-confidence NodeIDs, DM the architect with `[PRELIMINARY]` messages (max 3 — see `agents/analyst.md` for format). This lets the architect start speculative research early.
 > **Deliverable**: Change Set proposal written to the WorkGroup file. Include NodeIDs, descriptions, affected files, risk assessment, and dependency map (for Parallel Teams mode).
 
 **Dispatch**:
-- *Parallel Teams*: Spawned at Stage 0 alongside scouts and architect. Starts immediately (no blockedBy).
+- *Parallel Teams*: Spawned at Stage 0 alongside scouts, scanners, and architect. Starts immediately (no blockedBy).
 - *Sequential Teams*: Spawn teammate `analyst`, create task `Phase 1A: Impact analysis for "{goal}"`, wait for completion.
 - *Subagent*: `Task(subagent_type="analyst", description="Phase 1A impact analysis", prompt=<above>)`
 
@@ -777,17 +864,41 @@ If `AUTONOMOUS_MODE = false`: If rejected — re-run analyst with user feedback.
 ### MCP Learning Capture (Optional)
 
 If MCP is configured and knowz-scribe is active, after Change Set approval:
-- Send message to **knowz-scribe**: `"Capture Phase 1A: {wgid}"` — the scribe reads the WorkGroup file, extracts scope/risk/decision data, and writes to the appropriate vault
+- Create capture task: `TaskCreate("Scribe: Capture Phase 1A")` → `TaskUpdate(owner: "knowz-scribe")`
+- Send message to **knowz-scribe** with task ID: `"Capture Phase 1A: {wgid}. Your task: #{task-id}"` — the scribe reads the WorkGroup file, extracts scope/risk/decision data, and writes to the appropriate vault
 - `search_knowledge({resolved_domain_vault_id}, "patterns for {domain}")` — pull relevant past learnings to inform specification
 - Share any relevant findings with the architect in the Phase 1B prompt
 
 ---
 
+## Stage 0: Architect Pre-load (Parallel Teams)
+
+**Agent**: `architect` | Spawned at Stage 0 for context pre-loading and speculative research
+
+In Parallel Teams mode, the architect is spawned at Stage 0 (not at Phase 1B). It pre-loads architecture context and performs speculative research on `[PRELIMINARY]` NodeIDs from the analyst.
+
+**Stage 0 spawn prompt** (Parallel Teams only):
+> You are the **architect** for WorkGroup `{wgid}`.
+> Read `agents/architect.md` for your full role definition.
+>
+> **Goal**: {goal}
+> **Context files**: Read sections 1-2 and 3.2 of `knowzcode/knowzcode_loop.md` (skip other phases), `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`
+> **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
+> **Specs directory**: `knowzcode/specs/`
+>
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Stage 0 Role**: Pre-load architecture context, then perform speculative research on any `[PRELIMINARY]` NodeID messages from the analyst (see Speculative Research Protocol in `agents/architect.md`). READ-ONLY research — do NOT write specs yet.
+> **Lifecycle**: You persist through the entire workflow. After Gate #1, you will receive spec-drafting tasks via DM. After Gate #2, you shift to consultative role for builders.
+
+After Gate #1, the lead sends the approved Change Set via DM and creates spec-drafting tasks. For spec-drafting prompts, see Phase 1B below.
+
+---
+
 ## Phase 1B: Specification
 
 **Agent**: `architect` | **Loop.md**: Section 3.2
 
-**Spawn prompt**:
+**Spec-drafting prompt** (sent via DM to already-warm architect in Parallel Teams, or as spawn prompt in Sequential/Subagent):
 > You are the **architect** for WorkGroup `{wgid}`.
 > Read `agents/architect.md` for your full role definition.
 >
@@ -801,12 +912,29 @@ If MCP is configured and knowz-scribe is active, after Change Set approval:
 > **Conventions**: Update WorkGroup file with results (prefix entries with `KnowzCode:`). If blocked, report blocker and notify lead.
 > **Deliverable**: Finalized specs for all NodeIDs written to `knowzcode/specs/`.
 
+**Spec-drafter spawn prompt** (Path B — 3+ NodeIDs, Parallel Teams only):
+> You are `spec-drafter-{N}` for WorkGroup `{wgid}`.
+> Read `agents/architect.md` for your full role definition — you follow the same Spec Philosophy, Spec Format, and Consolidation Mandate.
+>
+> **Goal**: {goal}
+> **Your NodeIDs**: {partition — 1-2 NodeIDs assigned to this drafter}
+> **Architect Research**: {research findings from architect's speculative research for these NodeIDs}
+> **Cross-NodeID Constraints**: {interface dependencies, shared specs, naming conventions from architect}
+> **Context files**: Read sections 1-2 and 3.2 of `knowzcode/knowzcode_loop.md`, `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`
+> **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
+> **Specs directory**: `knowzcode/specs/`
+>
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Deliverable**: Draft specs for your assigned NodeIDs written to `knowzcode/specs/`. The architect will review for consistency after all drafters finish.
+
 **Dispatch**:
-- *Parallel Teams*: Architect is already warm from Stage 0 pre-load. Lead sends DM with approved Change Set, then creates spec-drafting tasks. **Plan approval enabled** — add to prompt: `Present your spec design for lead review BEFORE writing final specs. Wait for approval.` If `AUTONOMOUS_MODE = true`: auto-approve `plan_approval_request` immediately. Log `[AUTO-APPROVED] Architect plan`.
+- *Parallel Teams*:
+  - **Path A** (< PARALLEL_SPEC_THRESHOLD NodeIDs): Architect is already warm from Stage 0 pre-load + speculative research. Lead sends DM with approved Change Set, then creates spec-drafting tasks. **Plan approval enabled** — add to prompt: `Present your spec design for lead review BEFORE writing final specs. Wait for approval.` If `AUTONOMOUS_MODE = true`: auto-approve `plan_approval_request` immediately. Log `[AUTO-APPROVED] Architect plan`.
+  - **Path B** (>= PARALLEL_SPEC_THRESHOLD NodeIDs): Lead asks architect for partition plan. Architect proposes partitions. Lead spawns spec-drafters (`subagent_type: "architect"`, `permissionMode: "acceptEdits"`, `maxTurns: 15`) with partition-scoped prompts. After all drafters complete, architect runs consistency review and reports to lead.
 - *Sequential Teams*: Spawn teammate `architect`, create task `Phase 1B: Draft specifications for {N} NodeIDs`. **Plan approval enabled** — add to prompt: `Present your spec design for lead review BEFORE writing final specs. Wait for approval.` Wait for `plan_approval_request`, review, respond with `plan_approval_response`. If `AUTONOMOUS_MODE = true`: auto-approve immediately. Log `[AUTO-APPROVED] Architect plan`.
 - *Subagent*: `Task(subagent_type="architect", description="Phase 1B specification drafting", prompt=<above> + "Present your spec design in your output for lead review.")`
 
-> **Note:** Plan approval (agent pauses for lead review) only works in Agent Teams mode via `permissionMode: plan`. In subagent mode, the architect presents its design in the output for post-hoc review.
+> **Note:** Plan approval (agent pauses for lead review) only works in Agent Teams mode via `permissionMode: plan`. In subagent mode, the architect presents its design in the output for post-hoc review. Spec-drafters (Path B) do NOT use plan approval — they follow the architect's partition briefing directly.
 
 ### Quality Gate #2
 
@@ -870,7 +998,8 @@ When complete, present implementation summary including files changed, tests wri
 ### MCP Learning Capture (Optional)
 
 If MCP is configured and knowz-scribe is active, after implementation completes:
-- Send message to **knowz-scribe**: `"Capture Phase 2A: {wgid}"` — the scribe reads implementation results from the WorkGroup file and captures patterns, workarounds, and performance optimizations to the `code` vault
+- Create capture task: `TaskCreate("Scribe: Capture Phase 2A")` → `TaskUpdate(owner: "knowz-scribe")`
+- Send message to **knowz-scribe** with task ID: `"Capture Phase 2A: {wgid}. Your task: #{task-id}"` — the scribe reads implementation results from the WorkGroup file and captures patterns, workarounds, and performance optimizations to the `code` vault
 
 ---
 
@@ -951,7 +1080,8 @@ If `AUTONOMOUS_MODE = false`: User decides — proceed / fix gaps / modify specs
 ### MCP Learning Capture (Optional)
 
 If MCP is configured and knowz-scribe is active, after audit approval:
-- Send message to **knowz-scribe**: `"Capture Phase 2B: {wgid}"` — the scribe reads audit results from the WorkGroup file and writes findings to the appropriate vault
+- Create capture task: `TaskCreate("Scribe: Capture Phase 2B")` → `TaskUpdate(owner: "knowz-scribe")`
+- Send message to **knowz-scribe** with task ID: `"Capture Phase 2B: {wgid}. Your task: #{task-id}"` — the scribe reads audit results from the WorkGroup file and writes findings to the appropriate vault
 
 ---
 
@@ -971,7 +1101,7 @@ If MCP is configured and knowz-scribe is active, after audit approval:
 >
 > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
 > **Conventions**: Update WorkGroup file with results (prefix entries with `KnowzCode:`). If blocked, report blocker and notify lead.
-> **Vault writes**: If knowz-scribe is active, send it `"Capture Phase 3: {wgid}"` to delegate learning capture and audit trail writes. Do NOT call `create_knowledge` directly.
+> **Vault writes**: If knowz-scribe is active, create a capture task (`TaskCreate("Scribe: Capture Phase 3")` → `TaskUpdate(owner: "knowz-scribe")`), then send `"Capture Phase 3: {wgid}. Your task: #{task-id}"` to delegate learning capture and audit trail writes. Do NOT call `create_knowledge` directly.
 > **Deliverable**: Atomic finalization — update specs to FINAL, update tracker, write log entry, update architecture if needed, delegate learning capture to knowz-scribe, and create final commit.
 
 **Dispatch**:
@@ -982,7 +1112,7 @@ If MCP is configured and knowz-scribe is active, after audit approval:
 ### Phase 3 Output
 
 When complete, if MCP is configured and knowz-scribe is active:
-- The closer sends a message to **knowz-scribe**: `"Capture Phase 3: {wgid}"` — the scribe reads the WorkGroup file, extracts learnings, decisions, and outcomes, and writes to the appropriate vaults
+- The closer creates a capture task (`TaskCreate("Scribe: Capture Phase 3")` → `TaskUpdate(owner: "knowz-scribe")`) and sends a message with the task ID: `"Capture Phase 3: {wgid}. Your task: #{task-id}"`. The lead waits for the scribe's capture task to complete before shutdown.
 
 Update workgroup to "Closed" and report:
 

package/knowzcode/claude_code_execution.md

@@ -146,7 +146,8 @@ Use mailbox messaging for coordination between teammates:
 | From | To | When |
 |------|-----|------|
 | scout | all | Initial context/vault findings (broadcast) |
-| analyst | architect | Scope clarifications, NodeID overlap with existing specs |
+| scanner | all | Codebase scan findings — affected files, test patterns (broadcast) |
+| analyst | architect | `[PRELIMINARY]` NodeID findings during Stage 0 (max 3 DMs), scope clarifications, NodeID overlap with existing specs |
 | architect | analyst | Scope adjustments needed |
 | architect | builder | Design guidance and spec intent responses |
 | builder | analyst | Affected files and dependency questions |
@@ -217,10 +218,13 @@ Agents must NOT create new tasks for work already assigned to them via task ID.
 | context-scout-specs | Stage 0 | After Gate #2 | Spec context lookups |
 | context-scout-workgroups | Stage 0 | After Gate #2 | WorkGroup history lookups |
 | context-scout-backlog | Stage 0 | After Gate #2 | Tracker/log/architecture lookups |
+| scanner-direct | Stage 0 (conditional) | After Stage 1 (analyst done) | Source code scanning — broadcasts affected files and code paths |
+| scanner-tests | Stage 0 (conditional) | After Stage 1 (analyst done) | Test discovery — broadcasts test patterns and coverage shape |
 | knowz-scout | Stage 0 | After Phase 3 capture | Vault queries (read-only) throughout workflow |
 | knowz-scribe | Stage 0 | After Phase 3 capture | Vault writes — receives capture messages, handles all `create_knowledge` calls |
 | analyst | Stage 0 | Early Stage 2 | Scope questions from builders |
-| architect | Stage 0 (pre-load) | After Gate #3 | Spec clarifications + design guidance for builders throughout Stage 2 |
+| architect | Stage 0 (pre-load + speculative research) | After Gate #3 | Pre-load → speculative research on `[PRELIMINARY]` NodeIDs → spec drafting (+ parallel coordination for 3+ NodeIDs) → design guidance for builders |
+| spec-drafter(s) | Stage 1 (Path B, 3+ NodeIDs) | After architect consistency review | Draft specs for assigned NodeID partition |
 | builder(s) | Stage 2 | After Gate #3 | Implementation + gap fixes (persistent through gap loop) |
 | reviewer(s) | Stage 2 (1 per builder partition) | After Gate #3 | Incremental audit per partition (persistent through gap loop) |
 | security-officer | Stage 0 (Group C) | After Gate #3 | Threat modeling + vulnerability scanning (officer — can block gates) |
@@ -237,8 +241,8 @@ All tasks in a workflow use `addBlockedBy` to express the dependency chain:
 
 ### Task Graph Patterns
 
-- Stage 0 tasks: scout + knowz-scribe + analysis tasks (no deps)
-- Stage 1 tasks: spec drafting tasks (blocked by gate approval — lead creates after gate)
+- Stage 0 tasks: scout + scanner + knowz-scribe + analysis tasks (no deps)
+- Stage 1 tasks: spec drafting tasks (blocked by gate approval — lead creates after gate). Path B (3+ NodeIDs): spec-drafter tasks + architect consistency review task
 - Stage 2 tasks: implementation subtasks (blocked by spec approval), audit subtasks (blocked by implementation)
 - Stage 3 tasks: finalization (blocked by audit approval)
 
@@ -252,6 +256,8 @@ Team sizing defaults are configurable via `knowzcode/knowzcode_orchestration.md`
 | `scout_mode` | full | `--no-scouts` | full (3 scouts), minimal (1 scout), none (lead reads context) |
 | `default_specialists` | [] | `--specialists`, `--no-specialists` | Project-level specialist defaults |
 | `mcp_agents_enabled` | true | `--no-mcp` | Toggle vault agents (knowz-scout, knowz-scribe) |
+| `codebase_scanner_enabled` | true | `--no-scanners` | Toggle codebase scanner agents (scanner-direct, scanner-tests) |
+| `parallel_spec_threshold` | 3 | `--no-parallel-specs` | NodeID count threshold for parallel spec drafting (Path B) |
 
 Precedence: hardcoded defaults → orchestration config → per-invocation flags.
 
@@ -284,11 +290,22 @@ During Stage 2, the architect persists as a read-only consultative resource:
 - Lead notifies architect when builders are spawned — architect sends intro message to each builder
 - Shut down with builders and reviewers after Gate #3
 
-#### Discovery Pre-loading
-During Stage 0, the architect pre-loads context in parallel with analysis:
-- Architect reads architecture docs, existing specs, project config
-- When Gate #1 is approved, architect already has context → specs drafted faster
-- If Gate #1 rejected, architect context is still useful for the revised analysis cycle
+#### Discovery Pre-loading + Speculative Research
+During Stage 0, the architect pre-loads context and conducts speculative research in parallel with analysis:
+- **Pre-load phase**: Architect reads architecture docs, existing specs, project config (3-5 turns)
+- **Speculative research phase**: After pre-load, architect receives `[PRELIMINARY]` NodeID messages from the analyst (max 3). For each, it reads affected files, checks spec consolidation, and analyzes interface patterns — all read-only, no spec writing
+- When Gate #1 is approved, architect already has context + deep research on flagged NodeIDs → specs drafted ~80% faster
+- If Gate #1 rejected, architect context and research are still useful for the revised analysis cycle
+- If no `[PRELIMINARY]` messages arrive (simple 1-NodeID change), architect finishes standard pre-load and waits
+
+#### Parallel Spec Drafting (Path B — 3+ NodeIDs)
+When the approved Change Set contains 3+ NodeIDs (configurable via `PARALLEL_SPEC_THRESHOLD`), spec drafting is parallelized:
+- Architect proposes NodeID partitions (1-2 per partition, max 3 partitions)
+- Lead spawns spec-drafter agents (using `architect` agent definition) for each partition
+- Each drafter receives: its NodeIDs, architect's speculative research findings, cross-NodeID constraints
+- After all drafters complete, architect runs a consistency review: cross-spec alignment, naming, VERIFY coverage
+- Spec-drafters shut down after consistency review, before Gate #2
+- For 1-2 NodeIDs (Path A), architect drafts all specs alone (current behavior, zero overhead)
 
 #### Specialist Agents (Group C — opt-in via `--specialists`)
 
@@ -296,11 +313,12 @@ When specialists are enabled, three additional agents spawn at Stage 0 alongside
 
 ```
 Group A (always):           3 context-scouts + analyst + architect       (5 agents)
+Group A (if scanners):      + scanner-direct + scanner-tests            (+2 agents)
 Group B (if MCP):           knowz-scout + knowz-scribe                  (2 agents)
 Group C (if --specialists): security-officer + test-advisor + project-advisor  (3 agents)
 ```
 
-Max Stage 0 concurrent: 5-10 agents depending on orchestration config (scouts, MCP agents, specialists). Scouts shut down after Gate #2, so Stage 2 peak is manageable.
+Max Stage 0 concurrent: 5-12 agents depending on orchestration config (scouts, scanners, MCP agents, specialists). Scouts shut down after Gate #2, scanners shut down after Stage 1, so Stage 2 peak is manageable.
 
 ##### Officer vs Advisor Authority
 

package/knowzcode/knowzcode_loop.md

@@ -327,6 +327,8 @@ All phases work without MCP. MCP enhances analysis depth and organizational lear
 
 ## 7. Learning Capture (Optional)
 
+> **Vault content must be detailed and self-contained.** Vault entries are retrieved via semantic search — not read directly like local files. Include full reasoning, specific technology names, code examples, and file paths. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
 During finalization, scan the WorkGroup for insight-worthy patterns:
 
 | Signal Type | Examples |
@@ -351,13 +353,21 @@ At each quality gate, send a message to the knowz-scribe with the phase identifi
 
 The knowz-scribe reads the WorkGroup file, extracts relevant data, checks for duplicates, and writes to the appropriate vault. No other agent should call `create_knowledge` when the scribe is active.
 
+**Ad-hoc captures (any agent, any time):**
+
+Any agent can send knowledge to the knowz-scribe outside phase boundaries:
+- `"Log: {description}"` — explicit capture, scribe must write it (decides vault routing)
+- `"Consider: {description}"` — soft capture, scribe evaluates whether to log and where
+
+The scribe handles routing, dedup, and formatting for both modes. If MCP is unavailable, captures are queued to `knowzcode/pending_captures.md` for later sync.
+
 **Single-agent / no scribe (direct MCP writes):**
 
 If MCP is available but no knowz-scribe, resolve vault IDs from `knowzcode/knowzcode_vaults.md` before writing:
 
-- After Phase 1A: `create_knowledge({ecosystem_vault}, title="Scope: {goal}", content="[NodeIDs] {list}\n[Risk] {assessment}", tags=["scope"])`
-- After Phase 2A: Capture implementation patterns and workarounds discovered during TDD cycles
-- After Phase 2B: `create_knowledge({ecosystem_vault}, title="Audit: {wgid} - {score}%", content="[Findings] {gaps}\n[Security] {issues}", tags=["audit"])`
+- After Phase 1A: `create_knowledge({ecosystem_vault}, title="Scope: {descriptive goal summary}", content="[CONTEXT] {problem description, what prompted this work, constraints}\n[INSIGHT] {scope decisions — what's included/excluded and why}\n[RATIONALE] {risk assessment with full reasoning, affected files, mitigation}\n[TAGS] scope, {domain}", tags=["scope", "{domain}"])`
+- After Phase 2A: Capture implementation patterns and workarounds discovered during TDD cycles — include specific file paths, code examples, and the problem each pattern solves
+- After Phase 2B: `create_knowledge({ecosystem_vault}, title="Audit: {wgid} - {score}% — {key finding summary}", content="[CONTEXT] {what was audited, scope of the review}\n[INSIGHT] {specific gaps with file paths and line references, security findings with severity reasoning}\n[RATIONALE] {gap resolution decisions — what was deferred vs fixed and why}\n[TAGS] audit, {domain}", tags=["audit", "{domain}"])`
 - After Phase 2B (enterprise): If enterprise vault configured and compliance enabled, push audit results to enterprise vault
 - After Phase 3: Capture architectural learnings and consolidation decisions (handled by closer agent)
 

package/knowzcode/knowzcode_vaults.md

@@ -124,16 +124,39 @@ On confirmation, each vault is created via the MCP `create_vault(name, descripti
 
 Each vault type defines when it accepts writes (Write Conditions) and how content should be formatted (Content Filter).
 
+### Content Detail Principle
+
+Vault entries live in a vector search index — they are chunked and retrieved via semantic search. Unlike local files (specs, workgroups, logs) which are read directly and benefit from being scannable, vault entries must be **self-contained, detailed, and keyword-rich** because they are discovered by meaning, not by file path.
+
+**Include in every vault entry:**
+- Full reasoning and context — why, not just what
+- Specific technology names, library versions, framework details
+- Code examples, file paths, error messages where relevant
+- Consequences and alternatives considered
+
+**Anti-pattern** (poor search recall, useless when retrieved):
+
+> `"[NodeIDs] AuthMiddleware\n[Risk] Medium"`
+
+**Good pattern** (rich search matches, self-contained on retrieval):
+
+> `[CONTEXT] During JWT authentication implementation for the Express API, the jsonwebtoken library's verify() method silently accepts expired tokens when clockTolerance is set above 0.`
+> `[INSIGHT] Always set clockTolerance to 0 (default) and handle TokenExpiredError explicitly. Some tutorials suggest 30s tolerance which creates a security window where revoked tokens remain valid.`
+> `[RATIONALE] A 30-second tolerance means stolen tokens stay usable after revocation. Our auth middleware in src/middleware/auth.ts now checks expiry with zero tolerance.`
+> `[TAGS] security, jwt, express, authentication`
+
+Write vault content as if the reader has no project context — they will find this entry via a search query months from now.
+
 ### code
 
 **Write Conditions**: Learning category is Pattern, Workaround, or Performance.
 
 **Content Filter**:
 ```
-[CONTEXT] {where the pattern/workaround was encountered}
-[PATTERN] {what was built or discovered}
-[EXAMPLE] {code snippet or usage example}
-[TAGS] {learning category, domain, language}
+[CONTEXT] {Where and why the pattern was encountered — include the component, framework, and problem being solved. Provide enough background for someone with no project familiarity.}
+[PATTERN] {What was built or discovered — describe the approach, the key insight, and how it differs from the obvious/naive solution.}
+[EXAMPLE] {Code snippet, usage example, or file path reference — concrete enough to be directly useful when retrieved.}
+[TAGS] {learning category, domain, language, framework — include specific technology names for search discoverability}
 ```
 
 ### ecosystem
@@ -142,10 +165,10 @@ Each vault type defines when it accepts writes (Write Conditions) and how conten
 
 **Content Filter**:
 ```
-[CONTEXT] {what prompted the decision or convention}
-[INSIGHT] {the decision, convention, security finding, or integration detail}
-[RATIONALE] {why this approach was chosen}
-[TAGS] {learning category, domain}
+[CONTEXT] {What prompted the decision — the problem, the alternatives considered, and the constraints. Include component names and file paths where relevant.}
+[INSIGHT] {The decision, convention, security finding, or integration detail — state it clearly and completely so it stands alone without context.}
+[RATIONALE] {Why this approach was chosen over alternatives — include trade-offs, risks of the rejected options, and any conditions that might change this decision.}
+[TAGS] {learning category, domain, specific technology names — be generous with tags for search discoverability}
 ```
 
 ### finalizations
@@ -154,11 +177,12 @@ Each vault type defines when it accepts writes (Write Conditions) and how conten
 
 **Content Filter**:
 ```
-[GOAL] {original goal from WorkGroup}
-[OUTCOME] {success | partial | abandoned}
-[NODES] {NodeIDs changed}
-[DURATION] {phases completed, e.g. "1A-3"}
-[TAGS] {finalization, domain, outcome}
+[GOAL] {Original goal from WorkGroup — restate fully, not just the WorkGroup slug}
+[OUTCOME] {success | partial | abandoned — include what was delivered and what was deferred}
+[NODES] {NodeIDs changed — list each with a one-line summary of what it covers}
+[DURATION] {Phases completed (e.g. "1A-3"), total iterations, any notable delays or blockers}
+[SUMMARY] {Key learnings from this WorkGroup — architectural discoveries, patterns established, gotchas encountered. This is the most valuable field for future search queries.}
+[TAGS] {finalization, domain, outcome, key technology names}
 ```
 
 ---