takt 0.33.2 → 0.34.0

package/README.md

@@ -4,7 +4,7 @@
 
 **T**AKT **A**gent **K**oordination **T**opology — Give your AI coding agents structured review loops, managed prompts, and guardrails — so they deliver quality code, not just code.
 
-TAKT runs AI agents (Claude Code, Codex, OpenCode, Cursor, GitHub Copilot CLI) through YAML-defined workflows with built-in review cycles. You talk to AI to define what you want, queue tasks, and let TAKT handle the execution — planning, implementation, multi-stage review, and fix loops — all governed by declarative piece files.
+TAKT runs AI agents (Claude Code, Codex, OpenCode, Cursor, GitHub Copilot CLI) through YAML-defined workflows with built-in review cycles. You talk to AI to define what you want, queue tasks, and let TAKT handle the execution — planning, implementation, multi-stage review, and fix loops — all governed by declarative workflow files.
 
 TAKT is built with TAKT itself (dogfooding).
 
@@ -14,7 +14,7 @@ TAKT is built with TAKT itself (dogfooding).
 
 **Practical** — A tool for daily development, not demos. Talk to AI to refine requirements, queue tasks, and run them. Worktree isolation on task execution, PR creation, and retry on failure.
 
-**Reproducible** — Execution paths are declared in YAML, keeping results consistent. Pieces are shareable — a workflow built by one team member can be used by anyone else to run the same quality process. Every step is logged in NDJSON for full traceability from task to PR.
+**Reproducible** — Execution paths are declared in YAML, keeping results consistent. Workflows are shareable — a workflow built by one team member can be used by anyone else to run the same quality process. Every step is logged in NDJSON for full traceability from task to PR.
 
 **Multi-agent** — Orchestrate multiple agents with different personas, permissions, and review criteria. Run parallel reviewers, route failures back to implementers, aggregate results with declarative rules. Prompts are managed as independent facets (persona, policy, knowledge, instruction) that compose freely across workflows ([Faceted Prompting](./docs/faceted-prompting.md)).
 
@@ -45,7 +45,7 @@ npm install -g takt
 ```
 $ takt
 
-Select piece:
+Select workflow:
   ❯ 🎼 default (current)
     📁 🚀 Quick Start/
     📁 🎨 Frontend/
@@ -67,7 +67,7 @@ What would you like to do?
     Continue conversation
 ```
 
-Choosing "Queue as task" saves the task to `.takt/tasks/`. Run `takt run` to execute — TAKT creates an isolated worktree, runs the piece (plan → implement → review → fix loop), and offers to create a PR when done.
+Choosing "Queue as task" saves the task to `.takt/tasks/`. Run `takt run` to execute — TAKT creates an isolated worktree, runs the workflow (plan → implement → review → fix loop), and offers to create a PR when done.
 
 ```bash
 # Execute queued tasks
@@ -81,7 +81,7 @@ takt add #12
 takt run
 ```
 
-> **"Execute now"** runs the piece directly in your current directory without worktree isolation. Useful for quick experiments, but note that changes go straight into your working tree.
+> **"Execute now"** runs the workflow directly in your current directory without worktree isolation. Useful for quick experiments, but note that changes go straight into your working tree.
 
 ### Manage results
 
@@ -92,16 +92,16 @@ takt list
 
 ## How It Works
 
-TAKT uses a music metaphor — the name itself comes from the German word for "beat" or "baton stroke," used in conducting to keep an orchestra in time. In TAKT, a **piece** is a workflow and a **movement** is a step within it, just as a musical piece is composed of movements.
+TAKT uses a music metaphor — the name itself comes from the German word for "beat" or "baton stroke," used in conducting to keep an orchestra in time. User-facing terminology uses **workflow** and **step**, while the internal canonical names remain **piece** and **movement** for backward compatibility.
 
-A piece defines a sequence of movements. Each movement specifies a persona (who), permissions (what's allowed), and rules (what happens next). Here's a minimal example:
+A workflow is defined by a sequence of steps. Public YAML examples use `steps` and `initial_step`, while legacy `movements` and `initial_movement` are still accepted as compatibility aliases. Each step specifies a persona (who), permissions (what's allowed), and rules (what happens next). Here's a minimal example:
 
 ```yaml
 name: plan-implement-review
-initial_movement: plan
+initial_step: plan
 max_movements: 10
 
-movements:
+steps:
   - name: plan
     persona: planner
     edit: false
@@ -127,18 +127,22 @@ movements:
         next: implement    # ← fix loop
 ```
 
-Rules determine the next movement. `COMPLETE` ends the piece successfully, `ABORT` ends with failure. See the [Piece Guide](./docs/pieces.md) for the full schema, parallel movements, and rule condition types.
+Rules determine the next step. `COMPLETE` ends the workflow successfully, `ABORT` ends with failure. See the [Workflow Guide](./docs/pieces.md) for the full schema, parallel steps, and rule condition types.
 
-## Recommended Pieces
+Workflow files live in `workflows/` as the official directory name. TAKT still accepts legacy `pieces/` directories and `--piece` / legacy YAML keys as compatibility input, but normal docs and UI use `workflow` / `step`.
 
-| Piece | Use Case |
+When the same workflow name exists in multiple locations, TAKT resolves in this order: `.takt/workflows/` → `.takt/pieces/` → `~/.takt/workflows/` → `~/.takt/pieces/` → builtins.
+
+## Recommended Workflows
+
+| Workflow | Use Case |
 |-------|----------|
 | `default` | Standard development. Test-first with AI antipattern review and parallel review (architecture + supervisor). |
 | `frontend-mini` | Frontend-focused mini configuration. |
 | `backend-mini` | Backend-focused mini configuration. |
 | `dual-mini` | Frontend + backend mini configuration. |
 
-See the [Builtin Catalog](./docs/builtin-catalog.md) for all pieces and personas.
+See the [Builtin Catalog](./docs/builtin-catalog.md) for all workflows and personas.
 
 ## Key Commands
 
@@ -148,7 +152,7 @@ See the [Builtin Catalog](./docs/builtin-catalog.md) for all pieces and personas
 | `takt run` | Execute all pending tasks |
 | `takt list` | Manage task branches (merge, retry, instruct, delete) |
 | `takt #N` | Execute GitHub Issue as task |
-| `takt eject` | Copy builtin pieces/facets for customization |
+| `takt eject` | Copy builtin workflows/facets for customization |
 | `takt repertoire add` | Install a repertoire package from GitHub |
 
 See the [CLI Reference](./docs/cli-reference.md) for all commands and options.
@@ -177,10 +181,10 @@ See the [Configuration Guide](./docs/configuration.md) for all options, provider
 
 ## Customization
 
-### Custom pieces
+### Custom workflows
 
 ```bash
-takt eject default    # Copy builtin to ~/.takt/pieces/ and edit
+takt eject default    # Copy builtin workflow to ~/.takt/workflows/ and edit
 ```
 
 ### Custom personas
@@ -192,9 +196,9 @@ Create a Markdown file in `~/.takt/personas/`:
 You are a code reviewer specialized in security.
 ```
 
-Reference it in your piece: `persona: my-reviewer`
+Reference it in your workflow: `persona: my-reviewer`
 
-See the [Piece Guide](./docs/pieces.md) and [Agent Guide](./docs/agents.md) for details.
+See the [Workflow Guide](./docs/pieces.md) and [Agent Guide](./docs/agents.md) for details.
 
 ## CI/CD
 
@@ -220,25 +224,28 @@ See the [CI/CD Guide](./docs/ci-cd.md) for full setup instructions.
 ```
 ~/.takt/                    # Global config
 ├── config.yaml             # Provider, model, language, etc.
-├── pieces/                 # User piece definitions
+├── workflows/              # User workflow definitions
 ├── facets/                 # User facets (personas, policies, knowledge, etc.)
 └── repertoire/             # Installed repertoire packages
 
 .takt/                      # Project-level
 ├── config.yaml             # Project config
+├── workflows/              # Project workflow overrides
 ├── facets/                 # Project facets
 ├── tasks.yaml              # Pending tasks
 ├── tasks/                  # Task specifications
 └── runs/                   # Execution reports, logs, context
 ```
 
+Legacy `pieces/` directories are still read for compatibility, but `workflows/` is the canonical name in current docs and CLI output.
+
 ## API Usage
 
 ```typescript
 import { PieceEngine, loadPiece } from 'takt';
 
 const config = loadPiece('default');
-if (!config) throw new Error('Piece not found');
+if (!config) throw new Error('Workflow not found');
 
 const engine = new PieceEngine(config, process.cwd(), 'My task');
 engine.on('movement:complete', (movement, response) => {
@@ -254,9 +261,9 @@ await engine.run();
 |----------|-------------|
 | [CLI Reference](./docs/cli-reference.md) | All commands and options |
 | [Configuration](./docs/configuration.md) | Global and project settings |
-| [Piece Guide](./docs/pieces.md) | Creating and customizing pieces |
+| [Workflow Guide](./docs/pieces.md) | Creating and customizing workflows |
 | [Agent Guide](./docs/agents.md) | Custom agent configuration |
-| [Builtin Catalog](./docs/builtin-catalog.md) | All builtin pieces and personas |
+| [Builtin Catalog](./docs/builtin-catalog.md) | All builtin workflows and personas |
 | [Faceted Prompting](./docs/faceted-prompting.md) | Prompt design methodology |
 | [Repertoire Packages](./docs/repertoire.md) | Installing and sharing packages |
 | [Task Management](./docs/task-management.md) | Task queuing, execution, isolation |

package/builtins/en/config.yaml

@@ -34,8 +34,8 @@ language: en        # UI language: en | ja
 # notification_sound: true         # Master switch for sounds
 # notification_sound_events:       # Per-event sound toggle (unset means true)
 #   iteration_limit: true
-#   piece_complete: true
-#   piece_abort: true
+#   workflow_complete: true
+#   workflow_abort: true
 #   run_complete: true
 #   run_abort: true
 # logging:
@@ -82,12 +82,12 @@ language: en        # UI language: en | ja
 # runtime:
 #   prepare: [node, gradle, ./custom-script.sh]
 
-# Piece-level overrides
-# piece_overrides:
+# Workflow-level overrides
+# workflow_overrides:
 #   quality_gates:
 #     - "All tests pass"
 #   quality_gates_edit_only: true
-#   movements:
+#   steps:
 #     review:
 #       quality_gates:
 #         - "No security vulnerabilities"
@@ -116,8 +116,8 @@ language: en        # UI language: en | ja
 # Misc
 # bookmarks_file: ~/.takt/preferences/bookmarks.yaml  # Bookmark file location
 
-# Piece list / categories
-# enable_builtin_pieces: true                             # Enable built-in pieces from builtins/{lang}/pieces
+# Workflow list / categories
+# enable_builtin_workflows: true                          # Enable built-in workflows from builtins/{lang}/workflows
 # disabled_builtins:
 #   - magi                                                # Built-in piece names to disable
-# piece_categories_file: ~/.takt/preferences/piece-categories.yaml  # Category definition file
+# workflow_categories_file: ~/.takt/preferences/workflow-categories.yaml  # Category definition file

package/builtins/en/facets/instructions/dual-team-leader-implement.md

@@ -10,6 +10,8 @@ Analyze the implementation task and, if decomposition is appropriate, split into
    - If few files are involved, or the task is a rename/refactoring, implement in a single part
 
 2. If decomposing: prioritize splitting along frontend and backend boundaries
+   - **If design references exist and backend changes are not explicitly required, do not decompose.** Visual structure, copy, spacing, and styling are tightly coupled, and splitting them increases design drift risk
+   - **If design references exist, keep all UI components of the same screen in the same part.** Do not split headers, filters, cards, banners, and modals of one screen across different parts
    - Splitting between frontend (UI, components, styles) and backend (API, logic, data layer) is the most natural decomposition axis
    - When API contracts (request/response types) are defined, parallel implementation works well
    - When API contracts are undecided, implement backend first in one part and defer frontend
@@ -24,9 +26,13 @@ Analyze the implementation task and, if decomposition is appropriate, split into
      - **Reference-only files** (read-only, modification prohibited)
      - **Implementation task** (what and how to implement)
      - **Completion criteria** (implementation of responsible files is complete)
+   - When design references exist, each part instruction must also include:
+     - **Design references** (which files are the primary source of truth)
+     - **Elements to verify** (layout, copy, color, spacing, and navigation flow)
    - If tests are already written, instruct parts to implement so existing tests pass
-   - Do not include build checks (all parts complete first, then build is verified together)
+   - Refer to Quality Gates and plan any required verification as a dedicated single verification part
+   - Do not make parallel implementation parts run duplicate full-build or full-test checks
 
 **Constraints:**
-- Parts do not run tests (handled by subsequent movements)
+- If tests or build verification are needed, run them as a dedicated single verification part after dependent implementation parts are complete
 - Do not modify files outside your responsibility (causes conflicts)

package/builtins/en/facets/instructions/plan.md

@@ -14,6 +14,9 @@ For small tasks, skip the design sections in the report.
 1. Understand the task requirements
    - **When reference material points to an external implementation, determine whether it is a "bug fix clue" or a "design approach to adopt". If narrowing scope beyond the reference material's intent, include the rationale in the plan report**
    - **For each requirement, determine "change needed / not needed". If "not needed", cite the relevant code (file:line) as evidence. Claiming "already correct" without evidence is prohibited**
+   - **Limit requirements to explicit requirements and implicit requirements that follow directly from them. Do not turn general best practices or future extensions into requirements**
+   - **When decomposing requirements, split only as far as needed to make them independently verifiable. Do not jump from decomposition into new requirements**
+   - **When adding an implicit requirement, state which explicit requirement it is derived from in the plan report**
 2. Investigate code to resolve unknowns
 3. Identify the impact area
 4. Determine file structure and design patterns (if needed)

package/builtins/en/facets/instructions/review-requirements.md

@@ -14,14 +14,19 @@ Review {report:coder-decisions.md} to understand the recorded design decisions.
 
 **Previous finding tracking (required):**
 - First, extract open findings from "Previous Response"
-- Assign `finding_id` to each finding and classify current status as `new / persists / resolved`
+- Assign `finding_id` to each finding and classify current status as `new / persists / resolved / reopened`
 - If status is `persists`, provide concrete unresolved evidence (file/line)
 
 ## Judgment Procedure
 
-1. Extract requirements one by one from the review target report and task
-2. For each requirement, identify the implementing code (file:line)
-3. Confirm that the code satisfies the requirement
-4. Check for any changes not covered by the requirements
-5. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
-6. If there is even one blocking issue (`new` or `persists`), judge as REJECT
+1. Read `order.md`, the task body, `plan.md`, and `coder-decisions.md`, then extract the requirements one by one
+2. If a sentence contains multiple conditions or paths, split it into the smallest independently verifiable units
+   - Do not keep `A/B`, `global/project`, `JSON/leaf`, `allow/deny`, or `read/write` in a single row
+3. For each requirement, identify the implementing code (file:line)
+4. Classify each requirement as `satisfied / unmet / unverified`
+   - Do not mark a row `satisfied` without concrete code evidence
+   - Do not mark a row `satisfied` when only part of the cases is covered
+5. List out-of-scope changes and judge whether they are justified or unnecessary
+6. Reclassify prior findings into `new / persists / resolved / reopened`
+7. For each detected issue, classify it as blocking/non-blocking based on the Policy's scope table and judgment rules
+8. If there is even one blocking issue in `new`, `persists`, or `reopened`, judge as REJECT

package/builtins/en/facets/instructions/supervise.md

@@ -10,7 +10,7 @@ Verify existing evidence for tests, builds, and functional checks, then perform
    - Read `order.md` and extract required behavior and prohibitions
    - Read `plan.md` and confirm intended approach and scope
    - Read `coder-decisions.md` and confirm why the implementation moved in that direction
-   - Do not treat prior review conclusions as authoritative unless they align with all three and the code
+   - Do not treat prior review conclusions or requirements-review conclusions as authoritative unless they align with all three and the code
 3. Whether each task spec requirement has been achieved
    - Extract requirements one by one from the task spec
    - If a single sentence contains multiple conditions or paths, split it into the smallest independently verifiable units
@@ -31,7 +31,7 @@ Verify existing evidence for tests, builds, and functional checks, then perform
 5. Handling tests, builds, and functional checks
    - Do not assume this movement will rerun commands
    - Use only evidence available in this run, such as execution logs, reports, or CI results
-   - If evidence is missing, mark the item as unverified
+   - If evidence is missing, mark the item as unverified rather than successful
    - If report text conflicts with execution evidence, call out the inconsistency explicitly
 
 **Report verification:** Read all reports in the Report Directory and
@@ -54,6 +54,7 @@ Extract requirements from the task spec and verify each one individually against
 
 - If any ❌ exists, REJECT is mandatory
 - ✅ without evidence is invalid (must verify against actual code)
+- Do not mark a row as ✅ when only part of the cases is verified
 - Do not rely on plan report's judgment; independently verify each requirement
 
 ## Re-evaluation of Prior Findings
@@ -63,6 +64,7 @@ Extract requirements from the task spec and verify each one individually against
 
 - If final judgment differs from prior review conclusions, explain why with evidence
 - If marking `false_positive` or `overreach`, state whether it conflicts with the task objective, the plan, or both
+- If overturning a requirements-review conclusion, explain why with concrete evidence
 
 ## Verification Summary
 | Item | Status | Verification method |

package/builtins/en/facets/instructions/team-leader-implement.md

@@ -22,8 +22,9 @@ Analyze the implementation task and, if decomposition is appropriate, split into
      - **Implementation task** (what and how to implement)
      - **Completion criteria** (implementation of responsible files is complete)
    - If tests are already written, instruct parts to implement so existing tests pass
-   - Do not include build checks (all parts complete first, then build is verified together)
+   - Refer to Quality Gates and plan any required verification as a dedicated single verification part
+   - Do not make parallel implementation parts run duplicate full-build or full-test checks
 
 **Constraints:**
-- Parts do not run tests (handled by subsequent movements)
+- If tests or build verification are needed, run them as a dedicated single verification part after dependent implementation parts are complete
 - Do not modify files outside your responsibility (causes conflicts)

package/builtins/en/facets/knowledge/architecture.md

@@ -104,6 +104,99 @@ Prohibited patterns:
 - Error handling centralized (no try-catch scattered everywhere)
 - Business logic not leaking into Controller/View
 
+## Resolve at the Boundary
+
+Values such as config, options, providers, permissions, and paths should be resolved at the boundary before entering the core flow. Main processing should assume values are already resolved and should not keep asking config sources.
+
+| Criteria | Judgment |
+|----------|----------|
+| Create a resolved object such as `ExecutionContext` or `ResolvedOptions` at the entry point | OK |
+| Orchestration layers handle only resolved values | OK |
+| Lower layers reload global/project/env and resolve the same value again | REJECT |
+| Separate resolution functions exist for display and execution | REJECT |
+| Unresolved options are passed deep and later fixed with `??` | REJECT |
+
+```typescript
+// REJECT - Execution layer knows config sources directly
+async function executePiece(options) {
+  const engine = new PieceEngine({
+    provider: options.provider ?? globalConfig.provider,
+  });
+}
+
+class AgentRunner {
+  run(step, options) {
+    const provider = options.provider ?? resolveProviderFromConfig();
+    return getProvider(provider).call();
+  }
+}
+
+// OK - Resolve at the boundary, use resolved values internally
+async function executePiece(options) {
+  const context = resolveExecutionContext(options);
+  const engine = new PieceEngine(context);
+}
+
+class AgentRunner {
+  run(step, options) {
+    return getProvider(options.resolvedProvider).call();
+  }
+}
+```
+
+### Tell, Don't Ask
+
+Do not make lower layers inspect config sources and decide for themselves. Upper layers should tell them what to use by passing resolved values. Separate value selection from execution.
+
+| Pattern | Judgment |
+|---------|----------|
+| Upper layer passes a value such as `resolvedProvider` | OK |
+| Lower layer inspects `options` and resolves on its own | REJECT |
+| Execution object exposes only `run()` after `setup(config)` | OK |
+| Runtime branches call `getGlobalConfig()` during execution | REJECT |
+
+### Anti-Corruption Layer
+
+Precedence resolution and external config formats belong in a dedicated boundary layer. Pass only normalized internal values into the core model.
+
+| Pattern | Judgment |
+|---------|----------|
+| Encapsulate YAML/env/CLI differences in a resolver/adapter | OK |
+| Domain layer directly handles env var names or config key strings | REJECT |
+| Conversion from external form to internal form is centralized in one place | OK |
+| Same normalization logic is copied in multiple places | REJECT |
+
+### Phase Separation
+
+Separate input, interpretation, execution, and output into distinct stages. Iterative processing should, as much as possible, receive already interpreted input in bulk and then repeat only execution.
+
+| Criteria | Judgment |
+|----------|----------|
+| Convert raw input into a `Resolved*` type at the boundary before entering the core flow | OK |
+| Loop body handles only execution on resolved data | OK |
+| Config/env/options are interpreted inside every iteration | REJECT |
+| Each iteration packs `input -> interpret -> execute -> output` into one function | REJECT |
+| Even when optimization requires incremental handling, interpretation is isolated in a dedicated method | OK |
+
+```typescript
+// REJECT - Each iteration also interprets input
+for (const item of items) {
+  const resolved = resolveItem(item, rawOptions, config);
+  const result = execute(resolved);
+  output(result);
+}
+
+// OK - Interpret first, iterations only execute
+const resolvedItems = items.map((item) => resolveItem(item, rawOptions, config));
+
+for (const item of resolvedItems) {
+  const result = execute(item);
+  output(result);
+}
+```
+
+Even when interpretation must happen incrementally, keep `nextRawInput()`, `resolveInput()`, and `executeResolved()` as separate responsibilities. Performance constraints may compress phases, but must not mix responsibilities.
+
 ## Code Quality Detection
 
 **Explanatory Comment (What/How) Detection Criteria:**

package/builtins/en/facets/knowledge/cqrs-es.md

@@ -117,7 +117,20 @@ Good Projection:
 
 ## Query Side Design
 
-Controller uses QueryGateway. Does not use Repository directly.
+Query side operates on an event-driven PubSub model. Projections update Read Models via EventHandler, and queries read from Read Models.
+
+Event distribution uses PubSub (via message broker) to deliver events to all instances. Do not use mechanisms that assume delivery to the same instance.
+
+- **Subscription Query** (e.g., Axon's `subscriptionQuery()`): delivers change notifications back to the subscribing instance, but in distributed environments or when using third-party event store plugins, the subscribing instance and the notified instance may differ, making it impossible to return the response on the same machine. When synchronous response is needed, use reactive polling to wait for Read Model updates.
+- **Subscribing event processor** (e.g., Axon's `SubscribingEventProcessor`): relies on local event bus subscription, so only the instance that emitted the event receives it. In distributed environments, other instances' Projections are not updated. Use PubSub to distribute events to all instances.
+
+| Criteria | Judgment |
+|----------|----------|
+| Using Subscription Query (e.g., Axon's `subscriptionQuery()`) | REJECT. Does not work in distributed environments. Use reactive polling |
+| Using Subscribing event processor (e.g., Axon's `SubscribingEventProcessor`) | REJECT. Local delivery only. Other instances not updated in distributed environments |
+| Controller directly referencing Repository | REJECT. Must go through UseCase layer |
+| Query side referencing Command Model | REJECT |
+| QueryHandler issuing commands | REJECT |
 
 Types between layers:
 - `application/query/` - Query result types (e.g., `OrderDetail`)
@@ -146,7 +159,7 @@ fun handle(query: GetOrderDetailQuery): OrderDetail? {
     return OrderDetail(...)
 }
 
-// Controller - converts to adapter layer type
+// Controller - synchronous return is fine for simple reads
 @GetMapping("/{id}")
 fun getById(@PathVariable id: String): ResponseEntity<OrderDetailResponse> {
     val detail = queryGateway.query(
@@ -163,16 +176,62 @@ Structure:
 Controller (adapter) → QueryGateway → QueryHandler (application) → Repository
      ↓                                      ↓
 Response.from(detail)                  OrderDetail
+
+Event flow (PubSub):
+Aggregate → Event Bus → Projection(@EventHandler) → Repository(Read Model)
+                                                          ↑
+                                          QueryHandler reads from here
 ```
 
 ## Eventual Consistency
 
-| Situation | Response |
-|-----------|----------|
-| UI expects immediate updates | Redesign or polling/WebSocket |
+When synchronous response is needed after command dispatch, use reactive polling to wait for Projection updates.
+
+| Criteria | Judgment |
+|----------|----------|
+| Using Subscription Query to wait for Projection updates | REJECT. Does not work in distributed environments. Use reactive polling |
+| UI expects immediate updates | Polling or WebSocket |
 | Consistency delay exceeds tolerance | Reconsider architecture |
 | Compensating transactions undefined | Request failure scenario review |
 
+### Reactive Polling
+
+Pattern: dispatch command → poll for Projection update completion.
+
+```kotlin
+// UseCase: send command → poll for completion
+fun execute(input: PlaceOrderInput): Mono<PlaceOrderOutput> {
+    val orderId = UUID.randomUUID().toString()
+    return Mono.fromCallable { validatePreConditions(input) }
+        .subscribeOn(Schedulers.boundedElastic())
+        .flatMap {
+            Mono.fromFuture(commandGateway.send<Any>(
+                PlaceOrderCommand(orderId, input.customerId, input.items)
+            ))
+        }
+        .then(pollForCompletion(orderId))
+        .thenReturn(PlaceOrderOutput(orderId))
+}
+
+// Polling: wait for Projection update
+private fun pollForCompletion(orderId: String): Mono<Void> {
+    return ReactivePolling.waitFor(
+        supplier = { orderRepository.findById(orderId).orElse(null) },
+        condition = { it.sagaCompleted || it.status == OrderStatus.CONFIRMED },
+        timeout = Duration.ofSeconds(60),
+        maxAttempts = 300
+    )
+}
+```
+
+When polling is appropriate:
+- Need to wait for Saga completion before returning response
+- Need to return created resource ID after command dispatch
+
+When polling is not needed:
+- Simple operations that complete with just command dispatch (no result waiting)
+- UI does not require real-time updates
+
 ## Saga vs EventHandler
 
 Saga is used only for "operations between multiple aggregates where contention occurs".

package/builtins/en/facets/output-contracts/plan.md

@@ -9,6 +9,14 @@
 ### Objective
 {What needs to be achieved}
 
+### Decomposed Requirements
+| # | Requirement | Type | Notes |
+|---|-------------|------|-------|
+| 1 | {requirement 1} | Explicit / Implicit | {Notes when a composite requirement was split} |
+
+- If a sentence contains multiple conditions, split it into the smallest independently verifiable rows
+- Put parallel expressions such as `A/B`, `global/project`, `JSON/leaf`, `allow/deny`, and `read/write` on separate rows
+
 ### Reference Material Findings (when reference material exists)
 {Overview of reference implementation's approach and key differences from current implementation}
 

package/builtins/en/facets/output-contracts/requirements-review.md

@@ -7,17 +7,19 @@
 {Summarize the result in 1-2 sentences}
 
 ## Requirements Cross-Reference
-| # | Requirement (from task) | Satisfied | Evidence (file:line) |
-|---|----------------------|-----------|----------------------|
-| 1 | {requirement 1} | ✅/❌ | `src/file.ts:42` |
+| # | Requirement (from task) | Status | Evidence (file:line) | Comment |
+|---|-------------------------|--------|----------------------|---------|
+| 1 | {requirement 1} | Satisfied / Unmet / Unverified | `src/file.ts:42` | {Notes} |
 
-- If even one ❌ exists, REJECT is mandatory
-- A ✅ without evidence is invalid (must be verified in actual code)
+- If a sentence contains multiple conditions, split it into multiple independently verifiable rows
+- If even one `Unmet` row exists, REJECT is mandatory
+- `Satisfied` without evidence is invalid (must be verified in actual code)
+- Do not mark a row `Satisfied` when only part of the cases is covered
 
 ## Scope Check
-| # | Out-of-scope Change | File | Justification |
-|---|---------------------|------|---------------|
-| 1 | {change not in requirements} | `src/file.ts` | Justified/Unnecessary |
+| # | Out-of-scope Change | File | Justification | Comment |
+|---|---------------------|------|---------------|---------|
+| 1 | {change not in requirements} | `src/file.ts` | Justified / Needs review / Unnecessary | {Reason} |
 
 ## Current Iteration Findings (new)
 | # | finding_id | family_tag | Category | Location | Issue | Fix Suggestion |

package/builtins/en/facets/output-contracts/supervisor-validation.md

@@ -19,6 +19,14 @@ Extract requirements from the task spec and verify each one individually against
 - Do not mark a row as ✅ when the evidence covers only part of the cases
 - Do not rely on plan report's judgment; independently verify each requirement
 
+## Re-evaluation of Prior Findings
+| finding_id | Prior Status | Re-evaluation | Evidence |
+|------------|--------------|---------------|----------|
+| {id} | new / persists / resolved | valid / false_positive / overreach | `src/file.ts:42`, `reports/plan.md` |
+
+- If final judgment differs from prior review conclusions, explain why with evidence
+- If marking `false_positive` or `overreach`, state whether it conflicts with the task objective, the plan, or both
+
 ## Validation Summary
 | Item | Status | Verification Method |
 |------|--------|-------------------|

package/builtins/en/facets/personas/planner.md

@@ -118,8 +118,15 @@ Do not over-interpret the task order. Plan only what is written.
 - Don't plan to leave TODO comments. Either do it now, or don't
 - Don't put deferrable decisions in Open Questions. If you can resolve it by reading code, investigate and decide. Only include items that genuinely require user input
 
+**Requirement decomposition discipline:**
+- Limit requirements to explicit requirements and implicit requirements that follow directly from them
+- When adding an implicit requirement, be able to state which explicit requirement it comes from
+- Do not turn general best practices, future possibilities, or personal preferences into requirements
+- Decompose requirements only to make them independently verifiable, not to invent new work
+
 **Important:**
 **Investigate before planning.** Don't plan without reading existing code.
 **Design simply.** No excessive abstractions or future-proofing. Provide enough direction for implementation without hesitation.
+**Do not jump when decomposing requirements.** Split only as far as needed for verification.
 **Ask all clarification questions at once.** Do not ask follow-up questions in multiple rounds.
 **Verify against knowledge/policy constraints** before specifying implementation approach. Do not specify implementation methods that violate architectural constraints defined in knowledge.

package/builtins/en/facets/personas/requirements-reviewer.md

@@ -20,7 +20,14 @@ You are a requirements fulfillment verifier. You verify that changes satisfy the
 ## Behavioral Principles
 
 - Verify requirements one by one. Never say "broadly satisfied" in aggregate
+- If a sentence contains multiple conditions, split it into the smallest independently verifiable units before judging
+- Do not treat parallel expressions such as `A/B`, `global/project`, `JSON/leaf`, `allow/deny`, or `read/write` as a single requirement
 - Verify in actual code. Do not take "implemented" claims at face value
+- Do not mark a composite requirement satisfied based on only one side of the cases
+- Never write "satisfied" without concrete file:line evidence
+- If evidence is missing, mark it as unverified rather than unimplemented
 - Guard the scope. Question any change not covered by the requirements
+- For out-of-scope changes, judge not only whether they exist but whether they are justified
 - Do not tolerate ambiguity. Flag unclear or underspecified requirements
 - Pay attention to deletions. Confirm that file or code removals are justified by the requirements
+- `plan.md` and `coder-decisions.md` are references, not final evidence; always ground the judgment in actual code and diffs