takt 0.35.4 → 0.36.0

package/README.md

@@ -92,14 +92,14 @@ 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. User-facing terminology uses **workflow** and **step**, while the internal canonical names remain **piece** and **movement** for backward compatibility.
+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.
 
-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:
+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:
 
 ```yaml
 name: plan-implement-review
 initial_step: plan
-max_movements: 10
+max_steps: 10
 
 steps:
   - name: plan
@@ -127,11 +127,11 @@ steps:
         next: implement    # ← fix loop
 ```
 
-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.
+Rules determine the next step. `COMPLETE` ends the workflow successfully, `ABORT` ends with failure. See the [Workflow Guide](./docs/workflows.md) for the full schema, parallel steps, and rule condition types.
 
-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`.
+Workflow files live in `workflows/` as the official directory name.
 
-When the same workflow name exists in multiple locations, TAKT resolves in this order: `.takt/workflows/` → `.takt/pieces/` → `~/.takt/workflows/` → `~/.takt/pieces/` → builtins.
+When the same workflow name exists in multiple locations, TAKT resolves in this order: `.takt/workflows/` → `~/.takt/workflows/` → builtins.
 
 ## Recommended Workflows
 
@@ -153,6 +153,8 @@ See the [Builtin Catalog](./docs/builtin-catalog.md) for all workflows and perso
 | `takt list` | Manage task branches (merge, retry, force-fail, instruct, delete) |
 | `takt #N` | Execute GitHub Issue as task |
 | `takt eject` | Copy builtin workflows/facets for customization |
+| `takt workflow init` | Create a new workflow scaffold |
+| `takt workflow doctor` | Validate workflow definitions |
 | `takt repertoire add` | Install a repertoire package from GitHub |
 
 See the [CLI Reference](./docs/cli-reference.md) for all commands and options.
@@ -184,7 +186,9 @@ See the [Configuration Guide](./docs/configuration.md) for all options, provider
 ### Custom workflows
 
 ```bash
-takt eject default    # Copy builtin workflow to ~/.takt/workflows/ and edit
+takt workflow init my-flow   # Create a new workflow scaffold
+takt workflow doctor my-flow # Validate a workflow definition
+takt eject default           # Copy builtin workflow to ~/.takt/workflows/ and edit
 ```
 
 ### Custom personas
@@ -198,7 +202,7 @@ You are a code reviewer specialized in security.
 
 Reference it in your workflow: `persona: my-reviewer`
 
-See the [Workflow Guide](./docs/pieces.md) and [Agent Guide](./docs/agents.md) for details.
+See the [Workflow Guide](./docs/workflows.md) and [Agent Guide](./docs/agents.md) for details.
 
 ## CI/CD
 
@@ -237,21 +241,17 @@ See the [CI/CD Guide](./docs/ci-cd.md) for full setup instructions.
 └── 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.
+Workflow definitions are stored under `workflows/`.
 
 ## API Usage
 
 ```typescript
-import { PieceEngine, loadPiece } from 'takt';
+import { WorkflowEngine, loadWorkflow } from 'takt';
 
-const config = loadPiece('default');
+const config = loadWorkflow('default', process.cwd());
 if (!config) throw new Error('Workflow not found');
 
-const engine = new PieceEngine(config, process.cwd(), 'My task');
-engine.on('movement:complete', (movement, response) => {
-  console.log(`${movement.name}: ${response.status}`);
-});
-
+const engine = new WorkflowEngine(config, process.cwd(), 'My task');
 await engine.run();
 ```
 
@@ -261,7 +261,7 @@ await engine.run();
 |----------|-------------|
 | [CLI Reference](./docs/cli-reference.md) | All commands and options |
 | [Configuration](./docs/configuration.md) | Global and project settings |
-| [Workflow Guide](./docs/pieces.md) | Creating and customizing workflows |
+| [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 |

package/builtins/en/config.yaml

@@ -52,7 +52,7 @@ language: en        # UI language: en | ja
 #   retention_days: 30             # Retention period for event files
 
 # Interactive mode
-# interactive_preview_movements: 3 # Number of movement previews in interactive mode (0-10)
+# interactive_preview_steps: 3 # Number of step previews in interactive mode (0-10)
 
 # Per-persona provider/model overrides
 # persona_providers:
@@ -63,7 +63,7 @@ language: en        # UI language: en | ja
 #     provider: codex
 #     model: gpt-5.2-codex
 
-# Provider-specific options (lowest priority, overridden by piece/movement)
+# Provider-specific options (lowest priority, overridden by workflow/step)
 # provider_options:
 #   codex:
 #     network_access: true
@@ -119,5 +119,5 @@ language: en        # UI language: en | ja
 # Workflow list / categories
 # enable_builtin_workflows: true                          # Enable built-in workflows from builtins/{lang}/workflows
 # disabled_builtins:
-#   - magi                                                # Built-in piece names to disable
+#   - magi                                                # Built-in workflow names to disable
 # workflow_categories_file: ~/.takt/preferences/workflow-categories.yaml  # Category definition file

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

@@ -1,4 +1,4 @@
-**This is AI Review iteration #{movement_iteration}.**
+**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.

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

@@ -1,4 +1,4 @@
-**This is AI Review iteration #{movement_iteration}.**
+**This is AI Review iteration #{step_iteration}.**
 
 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.

package/builtins/en/facets/instructions/architecture-audit-review.md

@@ -5,9 +5,14 @@ Re-audit the modules or boundaries that were judged insufficient in the previous
 - Audit report: {report:02-architecture-audit.md}
 
 **What to do:**
-1. Read the flagged modules, boundaries, and call chains in full
-2. Re-check the structural claims and identify what was previously skipped or weakly evidenced
-3. Update the audit result with concrete file evidence, explicit scope coverage, and missing-item reasons where applicable
+1. Cross-check the audit report against the plan report to identify unaudited modules and missing boundaries
+2. Read the unaudited or flagged modules, boundaries, and call chains in full
+3. Record findings with concrete file evidence, explicit scope coverage, and missing-item reasons where applicable
+
+**Output principles:**
+- Preserve all existing Findings and Audit Scope from the previous audit report, and integrate new results into a complete updated version
+- Add newly audited modules to the Audit Scope table
+- If unaudited modules remain, state the reason explicitly in Follow-up Notes
 
 **Strictly prohibited:**
 - Modifying production code

package/builtins/en/facets/instructions/architecture-audit-team-leader.md

@@ -4,9 +4,11 @@ Decompose the architecture audit, assign modules to each part, and execute in pa
 
 **What to do:**
 1. Review the module inventory and architectural risk areas from the plan report
-2. Split the audit into 3 groups by module or boundary
+2. Split ALL target modules and subprojects from the plan report into 3 groups with no gaps
 3. Assign exclusive ownership to each part so every relevant module is audited once
 
+**Important:** Verify that every module and subproject listed in the plan report is assigned to exactly one part. No module may be left unassigned.
+
 **Each part's instruction MUST include:**
 - Assigned module and file list
 - The boundaries and call chains to verify

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

@@ -5,18 +5,18 @@ Re-audit the files that were judged insufficient in the previous audit.
 - List of files flagged as insufficiently audited
 - Specific feedback
 
+**Important:** Refer to the audit report: {report:02-audit-security.md}
+
 **What to do:**
 1. **Read each flagged file in full using Read tool one by one**
 2. Review each file from a security perspective
 3. Report discovered issues with severity ratings
 
+**Output principles:**
+- Preserve all existing results from the previous audit report, and integrate new results into a complete updated version
+- Add newly audited files to the audit results
+
 **Strictly prohibited:**
 - Searching with Grep and only reviewing matching files → PROHIBITED
 - Reading only part of a file → PROHIBITED
 - Skipping a file because it "looks fine" → PROHIBITED
-
-**Required output (include headings):**
-## Re-audit Results
-- {Audit results for each file}
-## Detected Issues
-- {Issue details (severity, location, remediation)}

package/builtins/en/facets/instructions/e2e-audit-review.md

@@ -5,10 +5,17 @@ Re-audit the routes or scenarios that were judged insufficient in the previous E
 - Coverage claims lacking evidence
 - Specific feedback on issue quality or scope
 
+**Important:** Refer to the audit report: {report:02-e2e-audit.md}
+
 **What to do:**
 1. Read the flagged route-related code and corresponding E2E tests in full
 2. Re-check the coverage claims for the flagged scenarios and identify what was previously skipped or weakly evidenced
-3. Update the audit result in issue-ready form with concrete evidence, explicit scope coverage, and missing-item reasons where applicable
+3. Record findings with concrete evidence, explicit scope coverage, and missing-item reasons where applicable
+
+**Output principles:**
+- Preserve all existing results from the previous audit report, and integrate new results into a complete updated version
+- Add newly audited flows to the audit results
+- If unaudited flows remain, state the reason explicitly
 
 **Strictly prohibited:**
 - Modifying E2E tests or production code

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

@@ -1,5 +1,5 @@
 Implement according to the plan, making existing tests pass.
-Refer only to files within the Report Directory shown in the Piece Context. Do not search or reference other report directories.
+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**: Tests have already been written. Implement production code to make existing tests pass.

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

@@ -1,5 +1,5 @@
 Implement Terraform code according to the plan.
-Refer only to files within the Report Directory shown in the Piece Context. Do not search or reference other report directories.
+Refer only to files within the Report Directory shown in the Workflow Context. Do not search or reference other report directories.
 
 **Important**: After implementation, run the following validations in order:
 1. `terraform fmt -check` — fix formatting violations with `terraform fmt` if any

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

@@ -1,5 +1,5 @@
 Implement unit tests according to the test plan.
-Refer only to files within the Report Directory shown in the Piece Context. Do not search or reference other report directories.
+Refer only to files within the Report Directory shown in the Workflow Context. Do not search or reference other report directories.
 
 **Important: Do NOT modify production code. Only test files may be edited.**
 

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

@@ -1,5 +1,5 @@
 Implement according to the plan.
-Refer only to files within the Report Directory shown in the Piece Context. Do not search or reference other report directories.
+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.

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

@@ -1,5 +1,5 @@
 Focus on reviewing **architecture and design**.
-Do not review AI-specific issues (already covered by the ai_review movement).
+Do not review AI-specific issues (already covered by the ai_review step).
 
 **Review criteria:**
 - Structural and design validity
@@ -19,18 +19,21 @@ Review {report:coder-decisions.md} to understand the recorded design decisions.
 - 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`
+- 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`
+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` or `persists`), judge as REJECT
+4. If there is even one blocking issue (`new`, `persists`, or `reopened`), judge as REJECT

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

@@ -1,5 +1,5 @@
 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_review movement).
+AI-specific issue review is not needed (already covered by the ai_review step).
 
 **Review criteria:**
 - Aggregate design validity

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

@@ -14,16 +14,19 @@ Review {report:coder-decisions.md} to understand the recorded design decisions.
 - 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`
+- 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`
+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` or `persists`), judge as REJECT
+4. If there is even one blocking issue (`new`, `persists`, or `reopened`), judge as REJECT

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

@@ -13,9 +13,11 @@ Review {report:coder-decisions.md} to understand the recorded design decisions.
 - 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"
+- 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
 
@@ -28,5 +30,6 @@ Review {report:coder-decisions.md} to understand the recorded design decisions.
    - 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
+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

@@ -10,6 +10,13 @@ Review the changes from a security perspective. Check for the following vulnerab
 - 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.
 
+**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
+
 **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.
@@ -27,5 +34,6 @@ Review the changes from a security perspective. Check for the following vulnerab
    - 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. For each detected issue, classify it as blocking or non-blocking based on the Policy scope table and judgment rules
-6. If there is even one blocking issue, judge as REJECT
+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

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

@@ -1,5 +1,5 @@
 Focus on reviewing **Terraform convention compliance**.
-Do not review AI-specific issues (already covered by the ai_review movement).
+Do not review AI-specific issues (already covered by the ai_review step).
 
 **Review criteria:**
 - Variable declaration compliance (type, description, sensitive)

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

@@ -15,9 +15,18 @@ 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. Cross-reference the test plan/test scope reports in the Report Directory with the implemented tests
-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
-4. If an external contract exists and input locations (root body / query / path) are not verified, treat it as a coverage gap by default
+1. First, extract prior open findings from report history and preliminarily classify them as `new / persists / resolved / reopened`
+2. Cross-reference the test plan/test scope reports in the Report Directory with the implemented tests
+3. When citing build, test, or functional verification as evidence, record the verified target, what was checked, and the observed result in the report
+4. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
+5. If there is even one blocking issue, judge as REJECT
+6. If an external contract exists and input locations (root body / query / path) are not verified, treat it as a coverage gap by default

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

@@ -1,9 +1,9 @@
 Verify existing evidence for tests, builds, and functional checks, then perform final approval.
 
-**Overall piece verification:**
-1. Check all reports in the report directory and verify overall piece consistency
+**Overall workflow verification:**
+1. Check all reports in the report directory and verify overall workflow consistency
    - Does implementation match the plan?
-   - Were all review movement findings properly addressed?
+   - Were all review step findings properly addressed?
    - Was the original task objective achieved?
    - Are prior review findings themselves valid against the task spec, plan, and actual code?
 2. Verify the task spec, plan, and decision history as primary sources
@@ -29,11 +29,20 @@ Verify existing evidence for tests, builds, and functional checks, then perform
    - If a finding holds technically but pushes work beyond the task objective or justified scope, classify it as `overreach`
    - Do not leave `false_positive` / `overreach` reasoning implicit
 5. Handling tests, builds, and functional checks
-   - Do not assume this movement will rerun commands
+   - Do not assume this step 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 rather than successful
    - If report text conflicts with execution evidence, call out the inconsistency explicitly
 
+**How to read reports:**
+- For reports with the same base name, treat the unversioned file as the latest result and `{report}.{timestamp}` files as history
+- When re-evaluating prior findings, compare the unversioned file with the most recent timestamped history file and verify that the meaning of `new / persists / resolved / reopened` is preserved
+- Treat summary reports as summaries, not as primary evidence. Prefer reports that record execution results, reviewer reports with concrete verification details, and then actual code
+- You may treat `Build Results` / `Test Results` sections in reports that record execution results as primary evidence
+- Treat reviewer claims such as "confirmed success" as supporting evidence only when they state the verified target, what was checked, and the observed result
+- If pieces of evidence conflict, prioritize them in this order: `execution-result report > reviewer report with concrete verification details > summary report`
+- If a later report reclassifies an earlier finding as `resolved`, `false_positive`, or `overreach`, decide whether to accept that reclassification by checking it against the task, plan, and code
+
 **Report verification:** Read all reports in the Report Directory and
 check whether any blocking finding remains unresolved and whether those findings are themselves valid.
 

package/builtins/en/facets/instructions/unit-audit-review.md

@@ -5,10 +5,17 @@ Re-audit the files or behaviors that were judged insufficient in the previous un
 - Coverage claims lacking evidence
 - Specific feedback on issue quality or scope
 
+**Important:** Refer to the audit report: {report:02-unit-audit.md}
+
 **What to do:**
 1. Read the flagged production files and corresponding tests in full
 2. Re-check the coverage claims for the flagged behaviors and identify what was previously skipped or weakly evidenced
-3. Update the audit result in issue-ready form with concrete evidence, explicit scope coverage, and missing-item reasons where applicable
+3. Record findings with concrete evidence, explicit scope coverage, and missing-item reasons where applicable
+
+**Output principles:**
+- Preserve all existing results from the previous audit report, and integrate new results into a complete updated version
+- Add newly audited files and behaviors to the audit results
+- If unaudited items remain, state the reason explicitly
 
 **Strictly prohibited:**
 - Modifying tests or production code

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

@@ -1,5 +1,5 @@
 Write tests based on the plan before implementing production code.
-Refer only to files within the Report Directory shown in the Piece Context. Do not search or reference other report directories.
+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.**
 

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

@@ -118,8 +118,8 @@ Values such as config, options, providers, permissions, and paths should be reso
 
 ```typescript
 // REJECT - Execution layer knows config sources directly
-async function executePiece(options) {
-  const engine = new PieceEngine({
+async function executeWorkflow(options) {
+  const engine = new WorkflowEngine({
     provider: options.provider ?? globalConfig.provider,
   });
 }
@@ -132,9 +132,9 @@ class AgentRunner {
 }
 
 // OK - Resolve at the boundary, use resolved values internally
-async function executePiece(options) {
+async function executeWorkflow(options) {
   const context = resolveExecutionContext(options);
-  const engine = new PieceEngine(context);
+  const engine = new WorkflowEngine(context);
 }
 
 class AgentRunner {
@@ -228,7 +228,7 @@ for (const transition of step.transitions) {
 export function matchesCondition(status: Status, condition: TransitionCondition): boolean {
 
 // OK - Design decision (Why)
-// User interruption takes priority over piece-defined transitions
+// User interruption takes priority over workflow-defined transitions
 if (status === 'interrupted') {
   return ABORT_STEP;
 }
@@ -475,13 +475,13 @@ Danger patterns:
 
 ```typescript
 // Missing wiring: No route to receive projectCwd
-export async function executePiece(config, cwd, task) {
-  const engine = new PieceEngine(config, cwd, task);  // No options
+export async function executeWorkflow(config, cwd, task) {
+  const engine = new WorkflowEngine(config, cwd, task);  // No options
 }
 
 // Wired: Can pass projectCwd
-export async function executePiece(config, cwd, task, options?) {
-  const engine = new PieceEngine(config, cwd, task, options);
+export async function executeWorkflow(config, cwd, task, options?) {
+  const engine = new WorkflowEngine(config, cwd, task, options);
 }
 ```
 

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

@@ -203,16 +203,56 @@ Exceptions (component-level fetching allowed):
 | Real-time updates | WebSocket/Polling auto-updates |
 | Modal detail fetch | Fetch additional data only when opened |
 
-Decision criteria: "Is there no point in parent managing this / Does it not affect parent?"
+Widget conditions (must satisfy all):
+- Completely unrelated to parent data
+- Does not affect parent state
+- Works the same on any page
+
+If any condition is not met, fetch data at View level and pass via props.
 
 | Criteria | Judgment |
 |----------|----------|
 | Direct fetch in component | Separate to Container layer |
 | No error handling | REJECT |
 | Loading state not handled | REJECT |
-| No cancellation handling | Warning |
 | N+1 query-like fetching | REJECT |
 
+### Screen-Specific API Usage
+
+Fetch data from screen-specific API endpoints. Do not assemble screens by repurposing generic APIs. If an API doesn't exist, add a backend endpoint first rather than working around it on the frontend.
+
+| Criteria | Judgment |
+|----------|----------|
+| Reusing list API response for detail screen | REJECT |
+| Display unit and API fetch unit mismatch | REJECT |
+| Fetching all records just for a decision (should use aggregation API) | REJECT |
+| Each screen has dedicated fetch endpoints returning only needed data | OK |
+
+```tsx
+// REJECT - Reusing list API for detail screen
+const DetailScreen = ({ itemId }) => {
+  const { data: list } = useListItems({ date })
+  const item = list?.items.find(i => i.id === itemId)
+  return <Detail item={item} />
+}
+
+// OK - Detail screen uses detail API
+const DetailScreen = ({ itemId }) => {
+  const { data: item } = useGetItem(itemId)
+  return <Detail item={item} />
+}
+```
+
+### Communication Scope Limitation
+
+Communication is scoped to the active tab/screen. Do not prefetch for other tabs. Periodic polling runs only on the visible screen.
+
+| Criteria | Judgment |
+|----------|----------|
+| Only visible tab communicates on tab switch | OK |
+| Parent fetches for all tabs and distributes to children | REJECT |
+| Polling continues on hidden tabs | REJECT |
+
 ## Shared Components and Abstraction
 
 Common UI patterns should be shared components. Copy-paste of inline styles is prohibited.

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

@@ -67,6 +67,45 @@ Treat initial page load separately from reactive refetching. Unless refetching i
 | Loading state updates trigger refetching | REJECT |
 | Message display or dialog state triggers refetching | REJECT |
 
+## Data Fetching Library Cache Suitability
+
+Data fetching library caching (React Query, etc.) is not appropriate for all data. Judge by data volatility and pagination method.
+
+| Data Characteristics | Cache | Verdict |
+|---------------------|-------|---------|
+| Single resource detail (settings, profile, etc.) | Effective | OK |
+| Stable list (master data, low change frequency) | Effective | OK |
+| Cursor-paginated list with mid-stream additions, deletions, or reordering | Ineffective | Use local state |
+| Offset-paginated list with mid-stream data changes | Ineffective | Use local state |
+
+Why cursor pagination and caching are incompatible:
+
+- The nextId (cursor) goes stale, causing gaps or duplicates when fetching the next page
+- Fetching the next page based on a deleted row causes missed records
+- Auto-refetching middle pages on tab refocus causes the visible list to diverge from the server's truth
+
+If you need to effectively disable caching even when using a data fetching library, there is no point in using that library. Fetching fresh data each time as the screen's responsibility is safer.
+
+```tsx
+// REJECT - applying React Query cache to a volatile cursor-paged list
+const { data } = useInfiniteQuery({
+  queryKey: ['records'],
+  queryFn: ({ pageParam }) => fetchRecords(pageParam),
+  getNextPageParam: (last) => last.nextId,
+  staleTime: 5 * 60 * 1000,  // caching despite mid-stream deletions
+})
+
+// OK - local state fetching as the screen's responsibility
+const [records, setRecords] = useState<Record[]>([])
+const [nextId, setNextId] = useState<string | undefined>()
+
+const loadMore = async () => {
+  const result = await fetchRecords(nextId)
+  setRecords(prev => [...prev, ...result.items])
+  setNextId(result.nextId)
+}
+```
+
 ## Custom Hook Responsibility
 
 A React custom hook should encapsulate state, effects, refs, or event translation. Pure calculations belong in function modules, not in a `use*` hook.