feat: add DDD scan, sync, and update commands for document indexing

- Implemented `/ddd:scan` command to analyze existing codebases and generate document indices without specifications. This includes phases for project structure analysis, component discovery, feature inference, and requirement extraction. - Introduced `/ddd:sync` command for post-task synchronization, updating document indices, generating action logs, and refreshing feature/component documentation after development tasks. - Added `/ddd:update` command for lightweight incremental updates to the document index, allowing for quick impact checks during development and pre-commit validation. - Created `execute.md` for the coordinator role in the team lifecycle, detailing the spawning of executor team-workers for IMPL tasks. - Added `useHasHydrated` hook to determine if the Zustand workflow store has been rehydrated from localStorage, improving state management reliability.
2026-03-07 16:41:06 +08:00 · 2026-03-07 00:00:18 +08:00
parent a9469a5e3b
commit 7ee9b579fa
18 changed files with 2739 additions and 155 deletions
--- a/.claude/commands/ddd/execute.md
+++ b/.claude/commands/ddd/execute.md
@@ -0,0 +1,405 @@
+---
+name: execute
+description: Document-aware execution engine — executes plan.json + TASK-*.json with doc-index context enrichment, per-batch impact verification, and post-completion doc sync.
+argument-hint: "[-y|--yes] [--skip-sync] [--skip-verify] [--plan <path>] [--in-memory] \"optional task description\""
+allowed-tools: TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*), mcp__ace-tool__search_context(*)
+---
+
+## Auto Mode
+
+When `--yes` or `-y`: Auto-confirm all decisions, auto-sync after completion.
+
+# DDD Execute Command (/ddd:execute)
+
+## Purpose
+
+Same execution engine model as lite-execute, but each step is **doc-index-aware**:
+- Tasks are enriched with feature context, component docs, and architecture constraints
+- Per-batch impact verification ensures changes stay within planned scope
+- Post-completion automatically syncs the document index
+
+### Core Differentiator
+Unlike generic execution engines, ddd:execute leverages the document architecture:
+- Feature-maps provide business context for each task
+- Tech-registry provides implementation patterns to follow
+- ADRs surface as hard constraints during execution
+- Requirement acceptance criteria inform convergence verification
+
+## Prerequisite
+
+- `plan.json` + `.task/TASK-*.json` files from `/ddd:plan`
+- `doc-index.json` at `.workflow/.doc-index/doc-index.json`
+- If `--in-memory`: receives executionContext from `/ddd:plan` handoff
+
+---
+
+## Step 1: Initialize & Load Context
+
+### 1.1 Locate Plan
+
+```
+IF --in-memory:
+  Load executionContext from ddd:plan handoff
+  plan_path = executionContext.plan_path
+  task_dir = executionContext.task_dir
+ELIF --plan <path>:
+  plan_path = <path>
+  task_dir = {dirname(path)}/.task/
+ELSE:
+  Scan .workflow/.doc-index/planning/ for most recent session
+  plan_path = {latest_session}/plan.json
+  task_dir = {latest_session}/.task/
+```
+
+### 1.2 Load Plan & Tasks
+
+- Read `plan.json` — validate against plan-overview-base-schema
+- Read all `TASK-*.json` from `.task/` directory — validate against task-schema
+- Read `doc-index.json` from `.workflow/.doc-index/`
+
+### 1.3 Pre-Load Doc Context
+
+For each task with `doc_context`:
+- Load referenced `feature_docs` (feature-maps/{slug}.md)
+- Load referenced `component_docs` (tech-registry/{slug}.md)
+- Load ADR excerpts from doc-index `architectureDecisions[]`
+- Extract requirement acceptance criteria from doc-index `requirements[]`
+
+### 1.4 Echo Strategy
+
+Display execution summary:
+
+```
+DDD Execute: {plan.summary}
+Complexity: {plan.complexity}
+Tasks: {plan.task_count}
+
+Doc-Index Impact:
+  Features: {doc_context.affected_features}
+  Requirements: {doc_context.affected_requirements}
+  Components: {doc_context.affected_components}
+  Constraints: {doc_context.architecture_constraints}
+
+Execution plan: {batch count} batches, {parallel tasks} parallel where possible
+```
+
+---
+
+## Step 2: Task Grouping & Batch Creation
+
+### 2.1 Extract Dependencies
+
+From each `TASK-*.json`, read `depends_on[]` to build dependency graph.
+
+### 2.2 Group into Batches
+
+```
+Batch 1: Tasks with no dependencies (depends_on: [])
+Batch 2: Tasks depending only on Batch 1 tasks
+Batch 3: Tasks depending on Batch 1 + 2 tasks
+...
+```
+
+Within each batch, tasks with the same `parallel_group` can run concurrently.
+
+### 2.3 Assign Executor per Task
+
+| Signal | Executor |
+|--------|----------|
+| `meta.execution_config.method == "cli"` | CLI tool (gemini/codex/qwen) |
+| `meta.execution_config.method == "agent"` | Agent (code-developer/universal-executor) |
+| Default | Agent (code-developer) |
+
+---
+
+## Step 3: Doc-Enriched Execution
+
+For each task in batch order, build an enriched prompt:
+
+### 3.1 Task Prompt Template
+
+```markdown
+## Goal
+${plan.summary} — specifically: ${task.title}
+
+## Document Context
+
+### Feature: ${feature.name} (${feature.id})
+${feature-map content excerpt — overview + requirements section}
+
+### Components
+${for each component in task.doc_context.component_ids:
+  tech-registry excerpt — responsibility + code locations + key patterns}
+
+### Architecture Constraints
+${for each ADR in task.doc_context.adr_ids:
+  ADR title + decision + rationale from doc-index}
+
+### Requirement Acceptance Criteria
+${for each requirement in task.doc_context.requirement_ids:
+  requirement title + priority + success criteria from doc-index}
+
+## Task Details
+${task.description}
+
+### Files to Modify
+${task.files[] — path, action, changes}
+
+### Implementation Steps
+${task.implementation[] — step-by-step guide}
+
+## Done When
+${task.convergence.criteria[]}
+${task.convergence.verification}
+```
+
+### 3.2 Execute Task
+
+**Agent execution**:
+```
+Agent(subagent_type="code-developer", prompt="{enriched prompt}")
+```
+
+**CLI execution**:
+```bash
+ccw cli -p "{enriched prompt}" --tool {cli_tool} --mode write
+```
+
+### 3.3 Record & Persist Result
+
+After each task completes:
+- Update `TASK-*.json` with `status`, `executed_at`, `result`
+- Track `result.files_modified` for impact verification
+- **Persist** result to `TASK-{id}.result.json` alongside the task file:
+
+```json
+{
+  "task_id": "TASK-001",
+  "status": "completed|failed",
+  "executed_at": "ISO8601",
+  "executor": "code-developer|gemini|codex",
+  "files_modified": [
+    { "path": "src/services/auth.ts", "action": "modified", "symbols_changed": ["AuthService.validate"] },
+    { "path": "src/routes/login.ts", "action": "created", "symbols_changed": ["loginRoute"] }
+  ],
+  "convergence_result": {
+    "criteria_met": ["Rate limiter middleware exists"],
+    "criteria_unmet": [],
+    "verification_output": "test output snippet..."
+  },
+  "error": null
+}
+```
+
+This file serves as the durable handoff between execute and sync — survives process interruptions.
+
+---
+
+## Step 4: Per-Batch Impact Verification
+
+After each batch completes (unless `--skip-verify`):
+
+### 4.1 Trace Changed Files
+
+For each file modified in the batch:
+```
+changed_file → match to doc-index.technicalComponents[].codeLocations[].path
+  → component_ids → featureIds → requirementIds
+```
+
+### 4.2 Scope Verification
+
+Compare actual impact to planned impact:
+
+```
+Planned scope:
+  Features: [feat-auth]
+  Components: [tech-auth-service, tech-user-model]
+
+Actual impact:
+  Features: [feat-auth]              ← OK, within scope
+  Components: [tech-auth-service, tech-user-model, tech-email-service]
+                                     ← WARNING: tech-email-service not in plan
+```
+
+### 4.3 Flag Unexpected Impact
+
+If changes affect features/components NOT in `plan.doc_context`:
+- **Warning**: Display unexpected impact
+- **No -y**: Ask user to confirm continuation
+- **With -y**: Log warning, continue execution
+
+### 4.4 Skip Conditions
+
+Skip verification when:
+- `--skip-verify` flag is set
+- Only 1 batch (no intermediate verification needed for simple plans)
+
+---
+
+## Step 4.5: Post-Execution Verify Gate
+
+After all batches complete, before doc sync (unless `--skip-verify`):
+
+### 4.5.1 Convergence Verification
+
+For each completed task with `convergence.verification`:
+```
+Execute: {task.convergence.verification}
+  → e.g., "npm test -- --grep rate-limit"
+Record: pass/fail → update TASK-{id}.result.json.convergence_result
+```
+
+### 4.5.2 Build & Lint Check
+
+```
+Run project build command (if configured):
+  → npm run build / tsc --noEmit / etc.
+Run project lint command (if configured):
+  → npm run lint / eslint src/ / etc.
+```
+
+If build or lint fails:
+- **No -y**: Display errors, ask user: fix now / continue anyway / abort
+- **With -y**: Log warning, continue (non-blocking)
+
+### 4.5.3 Regression Test
+
+```
+Run project test suite:
+  → npm test / pytest / etc.
+Compare: test results before execution (baseline) vs after
+```
+
+If tests fail:
+- **No -y**: Display failures, ask user: fix now / skip sync / abort
+- **With -y**: Log failures as warning in execution results, continue
+
+### 4.5.4 Verify Summary
+
+```
+Verify Gate Results:
+  Convergence: {passed}/{total} tasks verified
+  Build: pass|fail|skipped
+  Lint: pass|fail|skipped
+  Tests: {passed}/{total} ({new_failures} regressions)
+
+  Gate: PASS / WARN (continue with warnings) / FAIL (blocked)
+```
+
+### 4.5.5 Persist Verify Manifest
+
+Write `execution-manifest.json` to session folder:
+
+```json
+{
+  "session_id": "{session-id}",
+  "plan_path": "planning/{slug}/plan.json",
+  "completed_at": "ISO8601",
+  "tasks": [
+    {
+      "task_id": "TASK-001",
+      "status": "completed",
+      "result_file": ".task/TASK-001.result.json"
+    }
+  ],
+  "files_modified": [
+    { "path": "src/services/auth.ts", "action": "modified", "task_id": "TASK-001" },
+    { "path": "src/routes/login.ts", "action": "created", "task_id": "TASK-001" }
+  ],
+  "verify": {
+    "convergence": { "passed": 2, "total": 2 },
+    "build": "pass",
+    "lint": "pass",
+    "tests": { "passed": 42, "total": 42, "regressions": 0 },
+    "gate": "PASS"
+  }
+}
+```
+
+This manifest is the **single source of truth** consumed by `ddd:sync --from-manifest`.
+
+---
+
+## Step 5: Post-Completion Doc Sync
+
+After all batches complete (unless `--skip-sync`):
+
+### 5.1 Auto-Trigger ddd:sync
+
+```
+Invoke /ddd:sync [-y] --task-id {session-id} --from-manifest {session}/execution-manifest.json "{plan.summary}"
+```
+
+Note: `/ddd:sync` automatically creates a backup of `doc-index.json` before modifications.
+
+When `--from-manifest` is provided, sync uses the **execution manifest** as its primary data source instead of git diff. This ensures:
+- Precise file-level and symbol-level change tracking (from TASK-*.result.json)
+- Task-to-file attribution (which task modified which file)
+- Convergence verification results carried forward
+- Survives process interruptions (manifest is persisted to disk)
+
+Fallback: If manifest is unavailable (e.g., manual mode), sync falls back to git diff discovery.
+
+### 5.2 Generate Action Log
+
+Create action entry with:
+- All tasks executed and their results
+- Files modified across all batches
+- Features and requirements addressed
+
+### 5.3 Update Feature Status
+
+Based on execution results:
+- Requirements with verified convergence → update status
+- Features with all requirements met → `status: "implemented"`
+
+---
+
+## Step 6: Summary & Follow-up
+
+### 6.1 Execution Results
+
+```
+DDD Execute Complete
+
+Tasks: {completed}/{total} ({failed} failed)
+Files modified: {count}
+Batches: {batch_count}
+
+Doc-Index Changes:
+  Features updated: {list}
+  Components updated: {list}
+  New components registered: {list}
+  Requirements addressed: {list}
+
+Convergence:
+  {for each task: task.id — criteria met: X/Y}
+```
+
+### 6.2 Follow-up Suggestions
+
+Based on execution results, suggest:
+- **New issues**: If unexpected scope expansion was detected
+- **Additional tests**: If convergence criteria only partially met
+- **Documentation gaps**: If new components were created without docs
+- **Next tasks**: If plan had tasks marked as future/deferred
+
+---
+
+## Flags
+
+| Flag | Effect |
+|------|--------|
+| `-y, --yes` | Auto-confirm, auto-sync |
+| `--skip-sync` | Skip post-completion ddd:sync (Step 5) |
+| `--skip-verify` | Skip per-batch impact verification (Step 4) AND post-execution verify gate (Step 4.5) |
+| `--plan <path>` | Explicit plan.json path |
+| `--in-memory` | Accept executionContext from ddd:plan handoff |
+
+## Integration Points
+
+- **Input from**: `/ddd:plan` output (plan.json + TASK-*.json), `doc-index.json`
+- **Output to**: Updated `doc-index.json` (via ddd:sync), `TASK-*.result.json` (per-task), `execution-manifest.json` (session-level)
+- **Schemas**: `plan-overview-ddd-schema.json` (input), `task-schema.json` + `task-ddd-extension-schema.json` (input), `doc-index.json` (enrichment)
+- **Delegates to**: `/ddd:sync` for post-completion synchronization