takt 0.40.0 → 0.42.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,45 @@ 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 |
 |----------|-------------|
 | [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

@@ -74,6 +74,8 @@ language: en        # UI language: en | ja
 # provider_options:
 #   codex:
 #     network_access: true
+#   opencode:
+#     variant: high
 #   claude:
 #     sandbox:
 #       allow_unsandboxed_commands: true

package/builtins/en/facets/instructions/_system/fallback-notice.md

@@ -0,0 +1,16 @@
+## Notice: This Step Is A Fallback Execution
+
+The previous step execution was interrupted by an external condition ({{fallback_reason}}) and is being retried in a new session.
+The previous session context is not carried into this session.
+
+- Interrupted step: {{step_name}}
+- Original iteration: {{original_iteration}}
+- Interruption reason: {{fallback_reason_detail}}
+- Previous provider/model: {{previous_provider}} / {{previous_model}}
+- Current provider/model: {{current_provider}} / {{current_model}}
+
+Previous work that remains on disk as files or reports is available, but chat context is not. Rebuild context as needed:
+
+1. Inspect existing reports under {{report_dir}}
+2. Inspect the latest commit or working tree diff
+3. If context is still missing, execute from the step instruction

package/builtins/en/facets/instructions/ai-antipattern-fix.md

@@ -1,16 +1,9 @@
 **This is AI Review iteration #{step_iteration}.**
-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.
-
-From the 2nd iteration onward, it means the previous fixes were not actually applied.
-**Your belief that they were "already fixed" is incorrect.**
 
-**First, acknowledge the following:**
-- The files you thought were "fixed" are actually not fixed
-- Your understanding of the previous work is wrong
-- You need to rethink from scratch
+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.
 
 **Required actions:**
-1. Open all flagged files with the Read tool (discard assumptions and verify the facts)
+1. Open all flagged files with the Read tool
 2. Search for the problem areas with grep to confirm they exist
 3. Fix the confirmed issues with the Edit tool
 4. Run tests to verify
@@ -20,11 +13,6 @@ From the 2nd iteration onward, it means the previous fixes were not actually app
 - NG: "It has already been fixed"
 - OK: "After checking file X at L123, I found issue Y and fixed it to Z"
 
-**Strictly prohibited:**
-- Reporting "already fixed" without opening the file
-- Making judgments based on assumptions
-- Leaving issues that the AI Reviewer REJECTed unresolved
-
 **Handling "no fix needed" (required)**
 - Do not judge "no fix needed" unless you can show verification results for the target file for each AI Review finding
 - If the finding relates to "generated output" or "spec synchronization", output the tag corresponding to "unable to determine" unless you can verify the source/spec

package/builtins/en/facets/instructions/ai-antipattern-review.md

@@ -3,15 +3,9 @@
 On the first iteration, review comprehensively and report all issues that need to be flagged.
 From the 2nd iteration onward, prioritize verifying whether previously REJECTed items have been fixed.
 
-Review the code for AI-specific issues:
-- Verification of assumptions
-- Plausible but incorrect patterns
-- Compatibility with the existing codebase
-- Scope creep detection
-- Scope shrinkage detection (missing task requirements)
+Review the diff for AI-specific issues.
 
-## Judgment Procedure
-
-1. Review the change diff and detect issues based on the AI-specific criteria above
-2. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
-3. If there is even one blocking issue, judge as REJECT
+Procedure:
+1. Open the Knowledge and Policy Source paths with the Read tool and obtain the full content
+2. List every `##` section in each of them (do not cherry-pick)
+3. Match the criteria in each listed section against the diff and detect any issues

package/builtins/en/facets/instructions/implement-after-tests.md

@@ -42,13 +42,12 @@ Small / Medium / Large
 ```
 
 **Pre-completion self-check (required):**
-Before running build and tests, verify the following:
-- If new parameters/fields were added, grep to confirm they are actually passed from call sites
-- For any `??`, `||`, `= defaultValue` usage, confirm fallback is truly necessary
-- Verify no replaced code/exports remain after refactoring
-- Verify no features outside the task specification were added
-- Verify no if/else blocks call the same function with only argument differences
-- Verify new code matches existing implementation patterns (API call style, type definition style, etc.)
+
+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
 
 **Required output (include headings)**
 ## Work results

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

@@ -41,13 +41,12 @@ Small / Medium / Large
 ```
 
 **Pre-completion self-check (required):**
-Before running build and tests, verify the following:
-- If new parameters/fields were added, grep to confirm they are actually passed from call sites
-- For any `??`, `||`, `= defaultValue` usage, confirm fallback is truly necessary
-- Verify no replaced code/exports remain after refactoring
-- Verify no features outside the task specification were added
-- Verify no if/else blocks call the same function with only argument differences
-- Verify new code matches existing implementation patterns (API call style, type definition style, etc.)
+
+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
 
 **Required output (include headings)**
 ## Work results

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

@@ -1,39 +1,7 @@
 Focus on reviewing **architecture and design**.
 Do not review AI-specific issues (already covered by the ai-antipattern-review-1st step).
 
-**Review criteria:**
-- Structural and design validity
-- Modularization (high cohesion, low coupling, no circular dependencies)
-- Functionalization (single responsibility per function, operation discoverability, consistent abstraction level)
-- Code quality
-- Appropriateness of change scope
-- Test coverage
-- Dead code
-- Call chain verification
-- Scattered hardcoding of contract strings (file names, config key names)
-
-
-**Design decisions reference:**
-Review {report:coder-decisions.md} to understand the recorded design decisions.
-- Do not flag intentionally documented decisions as FP
-- However, also evaluate whether the design decisions themselves are sound, and flag any problems
-
-**Previous finding tracking (required):**
-- First, inspect the review result previously produced by this step and its timestamped history in the Report Directory, treating the unversioned file as the latest result and the most recent timestamped file as the previous result
-- If "Previous Response" is available, use it only as supporting context; use report history as the source of truth for finding state transitions
-- 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)
-- Do not drop open findings from the prior report when producing the current report
-
-## Judgment Procedure
-
-1. First, extract previous open findings and preliminarily classify as `new / persists / resolved / reopened`
-2. Review the change diff and detect issues based on the architecture and design criteria above
-   - Cross-check changes against REJECT criteria tables defined in knowledge
-   - If you find a DRY violation, require it to be fixed
-   - Before proposing a fix, verify that the consolidation target fits existing responsibility boundaries, contracts, and public API shape
-   - If you require a new wrapper, helper, or public API, explain why that abstraction target is the natural one
-   - If the proposed abstraction goes beyond the task spec or plan, state why the additional scope is necessary and justified
-   - When citing build, test, or functional verification as evidence, record the verified target, what was checked, and the observed result in the report
-3. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
-4. If there is even one blocking issue (`new`, `persists`, or `reopened`), judge as REJECT
+Procedure:
+1. Open the Knowledge and Policy Source paths with the Read tool and obtain the full content
+2. List every `##` section in each of them (do not cherry-pick)
+3. Match the criteria in each listed section against the diff and detect any issues

package/builtins/en/facets/instructions/review-cqrs-es.md

@@ -1,25 +1,9 @@
-Review the changes from the perspective of CQRS (Command Query Responsibility Segregation) and Event Sourcing.
-AI-specific issue review is not needed (already covered by the ai-antipattern-review-1st step).
+Focus on reviewing **CQRS (Command Query Responsibility Segregation) and Event Sourcing**.
+Do not review AI-specific issues (already covered by the ai-antipattern-review-1st step).
 
-**Review criteria:**
-- Aggregate design validity
-- Event design (granularity, naming, schema)
-- Command/Query separation
-- Projection design
-- Eventual consistency considerations
+Procedure:
+1. Open the Knowledge and Policy Source paths with the Read tool and obtain the full content
+2. List every `##` section in each of them (do not cherry-pick)
+3. Match the criteria in each listed section against the diff and detect any issues
 
-**Note**: If this project does not use the CQRS+ES pattern,
-review from a general domain design perspective instead.
-
-
-**Design decisions reference:**
-Review {report:coder-decisions.md} to understand the recorded design decisions.
-- Do not flag intentionally documented decisions as FP
-- However, also evaluate whether the design decisions themselves are sound, and flag any problems
-
-## Judgment Procedure
-
-1. Review the change diff and detect issues based on the CQRS and Event Sourcing criteria above
-   - Cross-check changes against REJECT criteria tables defined in knowledge
-2. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
-3. If there is even one blocking issue, judge as REJECT
+**Note:** If this project does not use the CQRS+ES pattern, review from a general domain design perspective instead.

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

@@ -1,34 +1,8 @@
-Review the changes from a frontend development perspective.
+Focus on reviewing **frontend development**.
 
-**Review criteria:**
-- Design fidelity (top priority when a design reference is provided)
-- Component design (separation of concerns, granularity)
-- State management (local vs. global decisions)
-- Performance (re-renders, memoization)
-- Accessibility (keyboard navigation, ARIA)
-- Data fetching patterns
-- Reachability wiring for user-facing features (routes, entry paths, launch conditions)
-- TypeScript type safety
+Procedure:
+1. Open the Knowledge and Policy Source paths with the Read tool and obtain the full content
+2. List every `##` section in each of them (do not cherry-pick)
+3. Match the criteria in each listed section against the diff and detect any issues
 
-**Design fidelity check (when a design reference exists):**
-1. Identify the design reference from the task order's referenced materials
-2. Compare design elements (layout, wording, colors, spacing) against implementation element by element
-3. For any discrepancy, check the decisions log to determine if it was intentional
-4. Report unintentional discrepancies as blocking issues
-
-**Note**: If this project does not include a frontend,
-proceed as no issues found.
-
-
-**Design decisions reference:**
-Review {report:coder-decisions.md} to understand the recorded design decisions.
-- Do not flag intentionally documented decisions as FP
-- However, also evaluate whether the design decisions themselves are sound, and flag any problems
-
-## Judgment Procedure
-
-1. Review the change diff and detect issues based on the frontend development criteria above
-   - Cross-check changes against REJECT criteria tables defined in knowledge
-   - When new screens or user-facing features are added, verify that entry points and caller wiring were updated as well
-2. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
-3. If there is even one blocking issue, judge as REJECT
+**Note:** If this project does not include a frontend, proceed as no issues found.

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

@@ -1,32 +1,6 @@
-Review the changes from a quality assurance perspective.
+Focus on reviewing **quality assurance (test strategy, coverage, error handling, maintainability)**.
 
-**Review criteria:**
-- Test coverage and quality
-- Test strategy (unit/integration/E2E)
-- Error handling
-- Logging and monitoring
-- Maintainability
-
-
-**Design decisions reference:**
-Review {report:coder-decisions.md} to understand the recorded design decisions.
-- Do not flag intentionally documented decisions as FP
-- However, also evaluate whether the design decisions themselves are sound, and flag any problems
-
-**Previous finding tracking (required):**
-- First, inspect the review result previously produced by this step and its timestamped history in the Report Directory, treating the unversioned file as the latest result and the most recent timestamped file as the previous result
-- If "Previous Response" is available, use it only as supporting context; use report history as the source of truth for finding state transitions
-- 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)
-- Do not drop open findings from the prior report when producing the current report
-
-## Judgment Procedure
-
-1. First, extract previous open findings and preliminarily classify as `new / persists / resolved / reopened`
-2. Review the change diff and detect issues based on the quality assurance criteria above
-   - Cross-check changes against REJECT criteria tables defined in knowledge
-   - Even if tests pass, verify whether any additional change outside the task or plan is justified
-   - If review-driven follow-up changes expand the design, evaluate whether that extra change is actually necessary
-   - When citing build, test, or functional verification as evidence, record the verified target, what was checked, and the observed result in the report
-3. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
-4. If there is even one blocking issue (`new`, `persists`, or `reopened`), judge as REJECT
+Procedure:
+1. Open the Knowledge and Policy Source paths with the Read tool and obtain the full content
+2. List every `##` section in each of them (do not cherry-pick)
+3. Match the criteria in each listed section against the diff and detect any issues

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

@@ -1,25 +1,11 @@
-Review the changes from a requirements fulfillment perspective.
+Focus on reviewing **requirements fulfillment**.
 
-**Review criteria:**
-- Whether each requested requirement has been implemented
-- Whether implicit requirements (naturally expected behaviors) are satisfied
-- Whether changes outside the scope (scope creep) have crept in
-- Whether there are any partial or missing implementations
+Procedure:
+1. Open the Knowledge and Policy Source paths with the Read tool and obtain the full content
+2. List every `##` section in each of them (do not cherry-pick)
+3. Match the criteria in each listed section against the diff and detect any issues
 
-
-**Design decisions reference:**
-Review {report:coder-decisions.md} to understand the recorded design decisions.
-- Do not flag intentionally documented decisions as FP
-- However, also evaluate whether the design decisions themselves are sound, and flag any problems
-
-**Previous finding tracking (required):**
-- First, inspect the review result previously produced by this step and its timestamped history in the Report Directory, treating the unversioned file as the latest result and the most recent timestamped file as the previous result
-- If "Previous Response" is available, use it only as supporting context; use report history as the source of truth for finding state transitions
-- 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)
-- Do not drop open findings from the prior report when producing the current report
-
-## Judgment Procedure
+## Step-Specific Additional Procedure
 
 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
@@ -29,7 +15,3 @@ Review {report:coder-decisions.md} to understand the recorded design decisions.
    - 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. When citing build, test, or functional verification as evidence, record the verified target, what was checked, and the observed result in the report
-8. For each detected issue, classify it as blocking/non-blocking based on the Policy's scope table and judgment rules
-9. If there is even one blocking issue in `new`, `persists`, or `reopened`, judge as REJECT

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

@@ -1,39 +1,16 @@
-Review the changes from a security perspective. Check for the following vulnerabilities:
-- Injection attacks (SQL, command, XSS)
-- Authentication and authorization flaws
-- Data exposure risks
-- Cryptographic weaknesses
+Focus on reviewing **security**.
 
-**Primary sources to review:**
-- Review `order.md` to understand requirements and prohibitions.
-- Review `plan.md` to understand intended scope and design direction.
-- Review {report:coder-decisions.md} to understand the recorded design decisions.
-- Do not dismiss documented decisions as FP by default. Re-evaluate them against `order.md`, `plan.md`, and the actual code.
+Procedure:
+1. Open the Knowledge and Policy Source paths with the Read tool and obtain the full content
+2. List every `##` section in each of them (do not cherry-pick)
+3. Match the criteria in each listed section against the diff and detect any issues
 
-**Previous finding tracking (required):**
-- First, inspect the review result previously produced by this step and its timestamped history in the Report Directory, treating the unversioned file as the latest result and the most recent timestamped file as the previous result
-- If "Previous Response" is available, use it only as supporting context; use report history as the source of truth for finding state transitions
-- 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)
-- Do not drop open findings from the prior report when producing the current report
+## Step-Specific Notes
 
-**Important:**
-- Do not treat documented precedence rules, extension points, or configuration override behavior as vulnerabilities by themselves.
-- Do not assume that removing an interactive confirmation or warning automatically means a security boundary regression.
-- To issue a blocking finding, make the exploit path concrete: who controls what input, and what newly becomes possible.
-
-## Judgment Procedure
-
-1. Cross-check `order.md`, `plan.md`, `coder-decisions.md`, and the actual code to determine whether the behavior is intentional product behavior
-2. Review the change diff and extract issue candidates by cross-checking changes against REJECT criteria in knowledge
-3. For each candidate, verify the concrete exploit path
-   - Which actor controls the input or configuration
-   - Whether the change enables new privilege, data access, code execution, or prompt modification
-   - Whether the impact exceeds the existing documented precedence or extension model
-4. When configuration precedence, local/global shadowing, or non-interactive selection is involved, additionally verify:
-   - Whether the behavior is intended by `order.md` or `plan.md`
-   - Whether explicit selectors or arguments already make the user's intent clear
-   - Whether there is an actual trust-boundary break or new attack capability, rather than merely an override relationship
-5. When citing build, test, or functional verification as evidence, record the verified target, what was checked, and the observed result in the report
-6. For each detected issue, classify it as blocking or non-blocking based on the Policy scope table and judgment rules
-7. If there is even one blocking issue, judge as REJECT
+- Do not treat documented precedence rules, extension points, or configuration override behavior as vulnerabilities by themselves
+- Do not assume that removing an interactive confirmation or warning automatically means a security boundary regression
+- To issue a blocking finding, make the exploit path concrete: which actor controls what input, and what newly becomes possible
+- When configuration precedence, local/global shadowing, or non-interactive selection is involved, additionally verify:
+  - Whether the behavior is intended by `order.md` or `plan.md`
+  - Whether explicit selectors or arguments already make the user's intent clear
+  - Whether there is an actual trust-boundary break or new attack capability, rather than merely an override relationship

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

@@ -1,31 +1,7 @@
 Focus on reviewing **Terraform convention compliance**.
 Do not review AI-specific issues (already covered by the ai-antipattern-review-1st step).
 
-**Review criteria:**
-- Variable declaration compliance (type, description, sensitive)
-- Resource naming consistency (name_prefix pattern)
-- File organization compliance (one file per concern)
-- Security configurations (IMDSv2, encryption, access control, IAM least privilege)
-- Tag management (default_tags, no duplication)
-- Lifecycle rule appropriateness
-- Cost trade-off documentation
-- Unused variables / outputs / data sources
-
-
-**Design decisions reference:**
-Review {report:coder-decisions.md} to understand the recorded design decisions.
-- Do not flag intentionally documented decisions as FP
-- However, also evaluate whether the design decisions themselves are sound, and flag any problems
-
-**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`
-- If status is `persists`, provide concrete unresolved evidence (file/line)
-
-## Judgment Procedure
-
-1. First, extract previous open findings and preliminarily classify as `new / persists / resolved`
-2. Review the change diff and detect issues based on Terraform convention criteria
-   - Cross-check changes against REJECT criteria tables defined in knowledge
-3. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
-4. If there is even one blocking issue (`new` or `persists`), judge as REJECT
+Procedure:
+1. Open the Knowledge and Policy Source paths with the Read tool and obtain the full content
+2. List every `##` section in each of them (do not cherry-pick)
+3. Match the criteria in each listed section against the diff and detect any issues