takt 0.41.0 → 0.43.0

package/README.md

@@ -2,35 +2,53 @@
 
 🇯🇵 [日本語ドキュメント](./docs/README.ja.md) | 💬 [Discord Community](https://discord.gg/R2Xz3uYWxD)
 
-**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.
+**T**AKT **A**gent **K**oordination **T**opology — Orchestrate multiple AI agents with structured review loops, managed prompts, and guardrails.
 
-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.
+Talk to AI to define what you want, queue it as a task, and run it with `takt run`. Planning, implementation, review, and fix loops are defined in YAML workflow files, so the process is not left to the agent's discretion. TAKT coordinates Claude Code, Codex, OpenCode, Cursor, and GitHub Copilot CLI as agents with different roles, permissions, and context.
+
+TAKT is built primarily for AI coding workflows, but the same model applies beyond coding: any task where multiple AI agents need to coordinate, or where review, judgment, and feedback loops can improve task quality.
 
 TAKT is built with TAKT itself (dogfooding).
 
 ## Why TAKT
 
-**Batteries included** — Architecture, security, and AI antipattern review criteria are built in. Ship code that meets a quality bar from day one.
+AI coding agents are powerful, but they do not automatically create a stable development process. In long-running work, they forget instructions, accumulate polluted context, blur implementation and review responsibilities, and often force humans to repeat the same feedback again and again. That wears people down.
+
+Adding more rules to prompts, `CLAUDE.md`, or skills can help, but it cannot enforce the process. Whether the rules are followed is still left to the agent's behavior.
+
+TAKT treats AI agents as something to be controlled from the outside, not simply trusted.
 
-**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.
+Workflows define the phases, and each step receives its own persona, policy, knowledge, instruction, and output contract. TAKT manages implementation, review, fix, and re-review flows declaratively. By separating responsibilities, knowledge, and constraints, then giving each agent only what it needs for the current step, TAKT improves task quality without bloating context.
 
-**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.
+Reviews cannot be silently skipped. Findings route work back to fix steps, and human judgment can be requested when needed. Tasks run in isolated worktrees, and each step leaves logs and reports so the path from task to PR remains traceable.
 
-**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)).
+At its core, TAKT runs reusable agent processes built from roles, phases, judgments, and feedback loops.
+
+The goal is simple: make development processes reusable, reviewable, and reproducible without depending on constant human intervention.
 
 ## Requirements
 
-Choose one:
+The provider you choose determines whether you need to install an external CLI or can run on Node.js alone via a TypeScript SDK.
+
+These providers run via SDK (no CLI required, Node.js only):
+
+- `claude-sdk` — `@anthropic-ai/claude-agent-sdk`
+- `codex` — `@openai/codex-sdk`
+- `opencode` — `@opencode-ai/sdk`
 
-- **Provider CLIs**: [Claude Code](https://claude.ai/code) (default `claude` provider), [Codex](https://github.com/openai/codex), [OpenCode](https://opencode.ai), [Cursor Agent](https://docs.cursor.com/), or [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) installed
-- **Direct API**: OpenAI / OpenCode API Key (no CLI required)
+These providers require an external CLI:
+
+- `claude` — [Claude Code](https://claude.ai/code)
+- `claude-terminal` — [Claude Code](https://claude.ai/code) driven in an interactive terminal session (also requires [`tmux`](https://github.com/tmux/tmux))
+- `copilot` — [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli)
+- `cursor` — [Cursor Agent](https://docs.cursor.com/)
 
 Optional:
 
 - [GitHub CLI](https://cli.github.com/) (`gh`) — for `takt #N` (GitHub Issue tasks)
 - [GitLab CLI](https://gitlab.com/gitlab-org/cli) (`glab`) — for GitLab Issue/MR integration (auto-detected from remote URL)
 
-> **OAuth and API key usage:** Whether OAuth or API key access is permitted varies by provider and use case. Check each provider's terms of service before using TAKT.
+> **OAuth usage:** Whether OAuth is permitted varies by provider and use case. Check each provider's terms of service before using TAKT.
 
 ## Quick Start
 
@@ -92,7 +110,7 @@ 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. TAKT uses **workflow** and **step** consistently in both user-facing and implementation-facing terminology.
+The name TAKT comes from the German word for "beat" or "baton stroke," used in conducting to keep an orchestra in time. TAKT uses **workflow** and **step** consistently in both user-facing and implementation-facing terminology.
 
 A workflow is defined by a sequence of steps. Use `steps`, `initial_step`, and `max_steps`. Each step specifies a persona (who), permissions (what's allowed), and rules (what happens next). Here's a minimal example:
 
@@ -137,10 +155,12 @@ When the same workflow name exists in multiple locations, TAKT resolves in this
 
 | 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. |
+| `default` | Standard development workflow. Test-first with AI antipattern review and parallel review (architecture + supervisor). |
+| `frontend` | Frontend development workflow. |
+| `backend` | Backend development workflow. |
+| `dual` | Combined frontend + backend workflow. |
+| `takt-default` | The workflow used to develop TAKT itself. Directly applicable to other CLI tool development. |
+| `*-mini` series | Lightweight variants of each workflow (`default-mini` / `frontend-mini` / `backend-mini` / `dual-mini`). Omits `write_tests`. |
 
 See the [Builtin Catalog](./docs/builtin-catalog.md) for all workflows and personas.
 
@@ -164,7 +184,7 @@ See the [CLI Reference](./docs/cli-reference.md) for all commands and options.
 Minimal `~/.takt/config.yaml`:
 
 ```yaml
-provider: claude    # claude, claude-sdk, codex, opencode, cursor, or copilot
+provider: claude    # claude, claude-sdk, claude-terminal, codex, opencode, cursor, or copilot
 model: sonnet       # passed directly to provider
 language: en        # en or ja
 ```
@@ -202,7 +222,7 @@ You are a code reviewer specialized in security.
 
 Reference it in your workflow: `persona: my-reviewer`
 
-See the [Workflow Guide](./docs/workflows.md) and [Agent Guide](./docs/agents.md) for details.
+See the [Workflow Guide](./docs/workflows.md) for details. The list of builtin personas is in the [Builtin Catalog](./docs/builtin-catalog.md).
 
 ## CI/CD
 
@@ -243,35 +263,46 @@ See the [CI/CD Guide](./docs/ci-cd.md) for full setup instructions.
 
 Workflow definitions are stored under `workflows/`.
 
-## API Usage
+## Adopting Spec-Driven Development
 
-```typescript
-import { WorkflowEngine, loadWorkflow } from 'takt';
+TAKT enforces phase transitions declaratively as a YAML state machine, formalizes the artifact of each phase with output contracts, and routes deviations back via parallel review and fix loops. This structure is particularly well-suited for users who follow Spec-Driven Development (SDD) and keep the spec at the center of the process. Once the spec is well-defined, the AI cannot silently skip a phase, drop an acceptance criterion, or claim "done" without passing the verification gate.
 
-const config = loadWorkflow('default', process.cwd());
-if (!config) throw new Error('Workflow not found');
+For users who want to adopt SDD, the community provides [j5ik2o/takt-sdd](https://github.com/j5ik2o/takt-sdd) as a ready-made implementation. It ships pieces for Requirements → Gap Analysis → Design → Tasks → Implementation → Validation, plus an OpenSpec-style change-proposal flow. Install in one command:
 
-const engine = new WorkflowEngine(config, process.cwd(), 'My task');
-await engine.run();
+```bash
+npx create-takt-sdd
 ```
 
+See [External Integrations](./docs/external-integrations.md) for other community integrations.
+
 ## Documentation
 
 | Document | Description |
 |----------|-------------|
+| [Tutorial](./docs/tutorial.md) | Improve one example over three phases while queuing, running, and inspecting tasks |
 | [CLI Reference](./docs/cli-reference.md) | All commands and options |
 | [Configuration](./docs/configuration.md) | Global and project settings |
+| [Design Philosophy](./docs/design-philosophy.md) | Why TAKT is built around workflows, facets, feedback loops, and traceability |
 | [Workflow Guide](./docs/workflows.md) | Creating and customizing workflows |
-| [Agent Guide](./docs/agents.md) | Custom agent configuration |
 | [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 |
-| [Data Flow](./docs/data-flow.md) | Internal data flow and architecture diagrams |
 | [CI/CD Integration](./docs/ci-cd.md) | GitHub Actions and pipeline mode |
-| [Provider Sandbox & Permissions](./docs/provider-sandbox.md) | Sandbox, permission modes, and network access for Codex / OpenCode / Claude |
+| [External Integrations](./docs/external-integrations.md) | Community examples that extend TAKT without modifying core (audit trails, etc.) |
 | [Changelog](./CHANGELOG.md) ([日本語](./docs/CHANGELOG.ja.md)) | Version history |
-| [Security Policy](./SECURITY.md) | Vulnerability reporting |
+
+## Sponsors
+
+TAKT is supported by [CodeRabbit](https://coderabbit.link/nrslib) through its Open Source Support Program.
+
+<a href="https://coderabbit.link/nrslib">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://victorious-bubble-f69a016683.media.strapiapp.com/White_Typemark_79b9189d19.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://victorious-bubble-f69a016683.media.strapiapp.com/Orange_Typemark_43bf516c9d.svg">
+    <img alt="CodeRabbit" src="https://victorious-bubble-f69a016683.media.strapiapp.com/Orange_Typemark_43bf516c9d.svg" height="40">
+  </picture>
+</a>
 
 ## Community
 

package/builtins/en/config.yaml

@@ -91,10 +91,18 @@ language: en        # UI language: en | ja
 # runtime:
 #   prepare: [node, gradle, ./custom-script.sh]
 
+# Workflow YAML command gate policy
+# workflow_command_gates:
+#   custom_scripts: false
+
 # Workflow-level overrides
 # workflow_overrides:
 #   quality_gates:
-#     - "All tests pass"
+#     - "All tests pass" # AI completion directive
+#     - type: command    # Machine-executed gate after step completion
+#       name: quality-check
+#       command: "./.takt/quality-gates/check.sh"
+#       timeout_ms: 300000
 #   quality_gates_edit_only: true
 #   steps:
 #     review:

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

@@ -6,10 +6,13 @@ Analyze the implementation task and, if decomposition is appropriate, split into
 
 1. Assess whether decomposition is appropriate
    - Identify files to change and check inter-file dependencies
-   - If cross-cutting concerns exist (shared types, IDs, events), implement in a single part
+   - First look for parallelizable responsibility boundaries
+   - If cross-cutting concerns exist (shared types, IDs, events), consider staged work: foundation part -> consuming parts -> verification part
    - If few files are involved, or the task is a rename/refactoring, implement in a single part
+   - When parts.length === 1, first consider whether verification separation or staged work is possible
+   - Avoid oversized single parts such as "implementation and verification"
 
-2. If decomposing: prioritize splitting along frontend and backend boundaries
+2. If decomposing: prioritize splitting along frontend and backend boundaries, or group files by layer/module when that split does not fit
    - **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
@@ -19,6 +22,7 @@ Analyze the implementation task and, if decomposition is appropriate, split into
    - If there are type or interface dependencies, keep both sides in the same group
    - Never assign the same file to multiple parts
    - Keep test files and implementation files in the same part
+   - Separate implementation parts from verification parts
 
 3. Assign file ownership exclusively to each part
    - Each part's instruction must clearly state:
@@ -32,6 +36,7 @@ Analyze the implementation task and, if decomposition is appropriate, split into
    - If tests are already written, instruct parts to implement so existing tests pass
    - 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
+   - Do not duplicate npm test / npm run test:e2e:mock in each implementation part
 
 **Constraints:**
 - If tests or build verification are needed, run them as a dedicated single verification part after dependent implementation parts are complete

package/builtins/en/facets/instructions/fix-maintenance.md

@@ -0,0 +1,43 @@
+Use reports in the Report Directory and fix reviewer findings with the minimum diff that preserves existing contracts.
+
+**Fix principles:**
+- When a finding includes a "suggested fix", follow it rather than inventing your own workaround
+- Fix the target code directly. Do not deflect findings by adding tests or documentation instead
+- Classify findings as must-fix, verification-only, or out-of-scope
+- Modify only must-fix findings
+- Do not mix unrelated refactoring, renames, comment deletion, or test expectation changes
+
+**Report reference policy:**
+- Use the latest review reports in the Report Directory as primary evidence.
+- Past iteration reports are saved as `{filename}.{timestamp}` in the same directory (e.g., `architect-review.md.20260304T123456Z`). For each report, run Glob with a `{report-name}.*` pattern, read up to 2 files in descending timestamp order, and understand persists / reopened trends before starting fixes.
+
+**Completion criteria (all must be satisfied):**
+- Must-fix findings in this iteration (new / reopened) have been fixed
+- Potential occurrences of the same `family_tag` have been fixed simultaneously (no partial fixes that cause recurrence)
+- At least one regression test per `family_tag` has been added (mandatory for config-contract and boundary-check findings)
+- Findings with the same `family_tag` from multiple reviewers have been merged and addressed as one fix
+- After fixing, the full diff has been inspected and changes unrelated to the findings or request have been reverted
+
+**Important**: After fixing, run the build (type check) and tests.
+
+**Required output (include headings)**
+## Work Results
+- {Summary of actions taken}
+## Finding Responses
+- {Classification and response for must-fix, verification-only, and out-of-scope findings}
+## Changes Made
+- {Summary of required and related changes}
+## Reverted Unnecessary Changes
+- {Changes reverted, or "none"}
+## Build Results
+- {Build execution results}
+## Test Results
+- {Test command executed and results}
+## Convergence gate
+| Metric | Count |
+|--------|-------|
+| new (fixed in this iteration) | {N} |
+| reopened (recurrence fixed) | {N} |
+| persists (carried over, not addressed this iteration) | {N} |
+## Evidence
+- {List key points from files checked/searches/diffs/logs}

package/builtins/en/facets/instructions/implement-maintenance.md

@@ -0,0 +1,72 @@
+Implement according to the plan with the minimum diff while preserving existing contracts.
+Refer only to files within the Report Directory shown in the Workflow Context. Do not search or reference other report directories.
+Use reports in the Report Directory as the primary source of truth. If additional context is needed, you may consult Previous Response and conversation history as secondary sources (Previous Response may be unavailable). If information conflicts, prioritize reports in the Report Directory and actual file contents.
+
+**Important**: Add unit tests alongside the implementation.
+- Add unit tests for newly created classes and functions
+- Update relevant tests when modifying existing code, but do not weaken existing expectations for implementation convenience
+- Test file placement: follow the project's conventions
+- Build verification is mandatory. After completing implementation, run the build (type check) and verify there are no type errors
+- Running tests is mandatory. After build succeeds, always run tests and verify results
+- When introducing new contract strings (file names, config key names, etc.), define them as constants in one place
+
+**Additional maintenance constraints:**
+- Before implementation, classify planned changes as required, related, or unnecessary
+- Implement only required and related changes
+- Do not use a touched file as a reason to make style improvements, renames, file moves, hook return shape changes, comment deletions, or test expectation changes
+- If the existing structure can satisfy the request, do not restructure only to match common style
+- After implementation, inspect the full diff and revert unnecessary changes
+
+**Maintenance Scope output contract (create at the start of implementation):**
+```markdown
+# Maintenance Change Scope
+
+## Task
+{One-line task summary}
+
+## Required Changes
+| File | Reason | Requirement Mapping |
+|------|--------|---------------------|
+| {File} | {Reason} | {Mapped requirement} |
+
+## Related Changes
+| File | Reason | Relation to Required Change |
+|------|--------|-----------------------------|
+| {File} | {Reason} | {Relation} |
+
+## Existing Contracts Preserved
+| Contract | Target | Preservation |
+|----------|--------|--------------|
+| {Contract type} | {Target} | {What is preserved} |
+```
+
+**Decisions output contract (at implementation completion, only if decisions were made):**
+```markdown
+# Decision Log
+
+## 1. {Decision}
+- **Context**: {Why the decision was needed}
+- **Options considered**: {List of options}
+- **Rationale**: {Reason for the choice}
+```
+
+**Pre-completion self-check (required):**
+
+Before running build and tests, audit your work against Policy with the following procedure.
+
+1. Open the Policy Source path with the Read tool and obtain the full content
+2. List every `##` section (do not cherry-pick)
+3. Match the REJECT criteria in each listed section against your implementation
+4. Inspect the full diff and check that no out-of-scope rename, move, comment deletion, UI copy change, accessible-name change, or test expectation change remains
+
+**Required output (include headings)**
+## Work Results
+- {Summary of actions taken}
+## Changes Made
+- {Summary of required and related changes}
+## Reverted Unnecessary Changes
+- {Changes reverted, or "none"}
+## Build Results
+- {Build execution results}
+## Test Results
+- {Test command executed and results}

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

@@ -0,0 +1,51 @@
+Analyze the task as maintenance work for an existing frontend feature and produce a minimum-diff implementation plan that includes necessary design decisions.
+
+**Note:** If Previous Response exists, treat it as a rework request and compare it with the current files before revising the plan.
+
+**Small-task criteria:**
+- Only 1-2 files change
+- No design decision is needed
+- No technology choice is needed
+
+For small tasks, omit the design section. In maintenance work, do not omit existing-contract and unnecessary-change checks even for small tasks.
+
+**Do:**
+1. **Read reference materials first (required)**
+   - Actually open files or directories listed in the task's reference-materials section with Read/Glob
+   - If a directory is listed, enumerate it and identify the relevant files before reading
+   - If reference materials do not exist or cannot be found, report that and do not substitute guesses
+   - **Do not use files not listed in the task as substitutes for reference materials**
+2. Understand the task requirements
+   - Compare reference materials with the current implementation to identify the delta
+   - **For each requirement, decide whether a change is needed. If no change is needed, cite the current code location (file:line). Do not say "already correct" without evidence**
+   - **Limit requirements to explicit requirements and directly implied requirements. Do not turn general best practices or future extensibility into requirements**
+   - **Break requirements down only to make them verifiable. Do not let decomposition create new requirements**
+   - **When using an implied requirement, identify the explicit requirement that supports it in the plan report**
+3. Inspect code to resolve unknowns
+4. Identify existing contracts that must be preserved
+   - Check existing structure, type names, hook return values, UI copy, accessible names, comments, and test expectations
+   - If an existing contract must change, document the reason and impact scope in the plan
+5. Classify candidate changes as required, related, or unnecessary
+   - Same file, nearby responsibility, or common style is not enough to make a change related
+   - Do not assign unnecessary changes to the Coder
+6. Decide file structure and design patterns when needed
+   - If the existing structure can satisfy the request, keep it even if it is not ideal
+7. Decide the implementation approach
+   - Check that the approach does not violate Knowledge or Policy constraints
+   - For user-facing additions or changes, fix the reachability condition, entry point, and activation path
+8. Include the following in the Coder guidance:
+   - Existing implementation patterns to follow (file:line). Always cite same-kind existing code when available
+   - Impact scope. Especially when adding a new parameter, list every call path that must be wired
+   - Relevant anti-patterns for this task, if any
+   - Existing contracts that must not change
+   - Candidate changes explicitly excluded as unnecessary
+
+**Required output (include headings)**
+## Work Results
+- {Plan summary}
+## Change Classification
+- {Required, related, and unnecessary changes}
+## Existing Contracts
+- {Existing contracts to preserve}
+## Implementation Plan
+- {Minimum-diff plan}

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

@@ -0,0 +1,8 @@
+Review the code diff.
+
+Procedure:
+1. Review the task intent, plan, diff, and execution evidence
+2. Look for implementation bugs, regressions in existing behavior, security risks, and missing tests
+3. Include only issues caused by the current diff that the user should fix
+4. For each finding, include location, impact, and fix direction
+5. Do not report unsupported speculation, preference-only changes, or unrelated pre-existing issues

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

@@ -0,0 +1,110 @@
+Review evidence from executed tests, builds, and manual verification, then make the final approval decision including whether any unnecessary maintenance diff remains.
+
+Procedure:
+1. Open the Knowledge and Policy Source paths with the Read tool and obtain the full content
+2. List every `##` section from each source (do not cherry-pick)
+3. Match the criteria from the listed sections against the diff, execution evidence, and reports
+
+## Step-specific additional procedure
+
+1. Extract each requirement from the task instructions one by one
+   - If one sentence contains multiple conditions or paths, split it into the smallest verifiable units
+   - Split parallel expressions by default
+2. For each requirement, identify the implemented code (file:line)
+3. Actually verify that the code satisfies the requirement by reading files and checking build/test evidence
+   - Do not mark a compound requirement ✅ after checking only one side
+   - Do not trust plan or requirements-review judgments without independent verification per requirement
+   - REJECT if any single requirement is unsatisfied
+4. Validate the maintenance scope
+   - Check whether required, related, and unnecessary change classifications are valid
+   - Check that comments, type names, file placement, UI copy, accessible names, and test expectations did not change out of scope
+   - REJECT if any diff remains that is justified only by general quality improvement or style cleanup
+5. Re-evaluate prior review findings
+   - If a finding does not hold in the code, record it as false_positive
+   - If a valid finding is outside the task purpose or over-generalized, record it as overreach
+   - Do not silently pass through false_positive or overreach findings
+
+## Report priority (supervise-specific)
+
+- Summary reports are not primary evidence. Primary evidence is execution-result reports, review reports with concrete checks, and actual code
+- `Build Results` / `Test Results` inside execution-result reports may be treated as primary evidence
+- In `architecture-review` / `qa-review` / `testing-review` / `security-review` / `requirements-review`, prioritize each report's verification-evidence section
+- Treat a verification-evidence item as supporting evidence only when target, check content, and result are all present. Otherwise treat it as unverified
+- When evidence conflicts, prefer `execution-result report > review report with concrete checks > summary report`
+
+**Validation output contract:**
+```markdown
+# Final Validation Result
+
+## Result: APPROVE / REJECT
+
+## Requirement Satisfaction Check
+
+Extract requirements from the task instructions and verify each requirement against actual code.
+
+| # | Requirement (from task instructions) | Satisfied | Evidence (file:line) |
+|---|--------------------------------------|-----------|----------------------|
+| 1 | {Requirement 1} | ✅/❌ | `src/file.ts:42` |
+| 2 | {Requirement 2} | ✅/❌ | `src/file.ts:55` |
+
+- Any ❌ requires REJECT
+- ✅ without evidence is invalid
+- Do not mark ✅ when only part of a compound case was checked
+- Do not trust the plan report without independent verification per requirement
+
+## Maintenance Scope Check
+
+| Check | Result | Evidence |
+|-------|--------|----------|
+| Only required changes remain | ✅/❌ | {Evidence} |
+| Related changes have clear reasons | ✅/❌ | {Evidence} |
+| No unnecessary changes remain | ✅/❌ | {Evidence} |
+| No out-of-scope comment deletion occurred | ✅/❌ | {Evidence} |
+| Type names, file placement, and public APIs did not change out of scope | ✅/❌ | {Evidence} |
+| UI copy, accessible names, and test expectations did not change out of scope | ✅/❌ | {Evidence} |
+
+## Prior Finding Re-evaluation
+
+| 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, write the reason with evidence
+- When marking false_positive / overreach, state whether it is inappropriate relative to the task or the plan
+- If overturning requirements-review, provide evidence-backed reasoning
+
+## Verification Summary
+| Item | Status | Verification Method |
+|------|--------|---------------------|
+| Tests | ✅ / ⚠️ / ❌ | {Execution log, report, CI evidence} |
+| Build | ✅ / ⚠️ / ❌ | {Execution log, report, CI evidence} |
+| Manual verification | ✅ / ⚠️ / ❌ | {Evidence checked, or state not verified} |
+
+## Artifacts
+- Created: {Created files}
+- Modified: {Modified files}
+
+## Incomplete Items (for REJECT)
+| # | Item | Reason |
+|---|------|--------|
+| 1 | {Item} | {Reason} |
+```
+
+**Summary output contract (APPROVE only):**
+```markdown
+# Task Completion Summary
+
+## Task
+{Original request in 1-2 sentences}
+
+## Result
+Complete
+
+## Changes
+| Type | File | Summary |
+|------|------|---------|
+| Created | `src/file.ts` | Summary |
+
+## Verification Evidence
+- {Test/build/manual verification evidence}
+```

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

@@ -6,14 +6,18 @@ Analyze the implementation task and, if decomposition is appropriate, split into
 
 1. Assess whether decomposition is appropriate
    - Identify files to change and check inter-file dependencies
-   - If cross-cutting concerns exist (shared types, IDs, events), implement in a single part
+   - First look for parallelizable responsibility boundaries
+   - If cross-cutting concerns exist (shared types, IDs, events), consider staged work: foundation part -> consuming parts -> verification part
    - If few files are involved, or the task is a rename/refactoring, implement in a single part
+   - When parts.length === 1, first consider whether verification separation or staged work is possible
+   - Avoid oversized single parts such as "implementation and verification"
 
 2. If decomposing: group files by layer/module
    - Create groups based on high cohesion (e.g., Domain layer / Infrastructure layer / API layer)
    - If there are type or interface dependencies, keep both sides in the same group
    - Never assign the same file to multiple parts
    - Keep test files and implementation files in the same part
+   - Separate implementation parts from verification parts
 
 3. Assign file ownership exclusively to each part
    - Each part's instruction must clearly state:
@@ -24,6 +28,7 @@ Analyze the implementation task and, if decomposition is appropriate, split into
    - If tests are already written, instruct parts to implement so existing tests pass
    - 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
+   - Do not duplicate npm test / npm run test:e2e:mock in each implementation part
 
 **Constraints:**
 - If tests or build verification are needed, run them as a dedicated single verification part after dependent implementation parts are complete

package/builtins/en/facets/instructions/write-tests-first.md

@@ -24,6 +24,11 @@ Refer only to files within the Report Directory shown in the Workflow Context. D
 - Include tests that would catch implementations that incorrectly reuse a response envelope when reading requests
 - Write tests that are expected to pass after implementation is complete (build errors and test failures are expected at this stage)
 
+**Non-executable asset constraints:**
+- Do not create tests that freeze prose, headings, or structure in explanations, guides, README files, or Markdown documentation
+- For docs-only changes, do not add tests unless an explicit executable contract exists
+- Tests are only needed when assets contain contracts tied to code behavior or machine processing, such as CLI examples, config examples, or generated artifacts
+
 **Test execution:**
 - Run tests after creating them to check results
 - Test failures and import errors are expected before implementation (including imports of not-yet-implemented modules)

package/builtins/en/facets/instructions/write-tests-maintenance.md

@@ -0,0 +1,45 @@
+Write tests based on the plan before implementing production code, while protecting existing behavior.
+Refer only to files within the Report Directory shown in the Workflow Context. Do not search or reference other report directories.
+
+**Important: Do NOT create or modify production code. Only test files may be created.**
+
+**Actions:**
+1. Review the plan report and separate behavior changed by the request from existing behavior that must not change
+2. Examine existing code and tests to learn the project's test patterns
+3. Add regression tests when existing contracts are not protected
+4. Write unit tests for the planned feature or fix
+5. Determine whether integration tests are needed and create them if so
+   - Does the data flow cross 3+ modules?
+   - Does a new status/state merge into an existing workflow?
+   - Does a new option propagate through a call chain to the endpoint?
+   - If any apply, create integration tests
+
+**Test writing guidelines:**
+- Follow the project's existing test patterns (naming conventions, directory structure, helpers)
+- Write tests in Given-When-Then structure
+- One concept per test. Do not mix multiple concerns in a single test
+- Cover happy path, error cases, boundary values, and edge cases
+- Do not weaken existing expectations for implementation convenience
+- When an external contract exists, include tests that use the contract-defined input location
+  - Example: pass request bodies using the defined root shape as-is
+  - Example: keep query / path parameters in their defined location instead of moving them into the body
+- Include tests that would catch implementations that incorrectly reuse a response envelope when reading requests
+- Write tests that are expected to pass after implementation is complete (build errors and test failures are expected at this stage)
+
+**Non-executable asset constraints:**
+- Do not create tests that freeze prose, headings, or structure in explanations, guides, README files, or Markdown documentation
+- For docs-only changes, do not add tests unless an explicit executable contract exists
+- Tests are only needed when assets contain contracts tied to code behavior or machine processing, such as CLI examples, config examples, or generated artifacts
+
+**Test execution:**
+- Run tests after creating them to check results
+- Test failures and import errors are expected before implementation (including imports of not-yet-implemented modules)
+- Fix errors that will persist after implementation, such as wrong import paths for existing modules
+
+**Required output (include headings)**
+## Work Results
+- {Summary of created or updated tests}
+## Protected Existing Contracts
+- {Existing behavior protected by tests}
+## Test Results
+- {Command and result if run, or reason if not run}