takt 0.41.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/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/knowledge/architecture.md

@@ -374,14 +374,14 @@ Don't overlook compromises made to "just make it work."
 | Swallowed errors | Empty `catch {}`, `rescue nil` |
 | Magic numbers | Unexplained `if (status == 3)` |
 
-## Strict TODO Comment Prohibition
+## Unfinished Code Detection
 
-"We'll do it later" never gets done. What's not done now is never done.
+Unfinished-code judgment follows the coding policy. In architecture review, check whether TODO/FIXME comments, empty implementations, or stubs are being used as substitutes for required boundaries, authorization, validation, or contract updates.
 
-TODO comments are immediate REJECT.
+TODO/FIXME without an issue number, external blocker, and removal condition is REJECT.
 
 ```kotlin
-// REJECT - Future-looking TODO
+// REJECT - Authorization check deferred with TODO
 // TODO: Add authorization check by facility ID
 fun deleteCustomHoliday(@PathVariable id: String) {
     deleteCustomHolidayInputPort.execute(input)
@@ -398,12 +398,12 @@ fun deleteCustomHoliday(@PathVariable id: String) {
 }
 ```
 
-Only acceptable TODO cases:
+Acceptable TODO/FIXME cases:
 
 | Condition | Example | Judgment |
 |-----------|---------|----------|
-| External dependency prevents implementation + Issued | `// TODO(#123): Implement after API key obtained` | Acceptable |
-| Technical constraint prevents + Issued | `// TODO(#456): Waiting for library bug fix` | Acceptable |
+| External dependency prevents implementation + issue exists + removal condition documented | `// TODO(#123): Implement after API key obtained` | Acceptable |
+| Technical constraint prevents implementation + issue exists + removal condition documented | `// TODO(#456): Waiting for library bug fix` | Acceptable |
 | "Future implementation", "add later" | `// TODO: Add validation` | REJECT |
 | "No time for now" | `// TODO: Refactor` | REJECT |
 
@@ -429,7 +429,7 @@ When NOT to apply DRY:
 
 ## Spec Compliance Verification
 
-Verify that changes comply with the project's documented specifications.
+Contract-change consistency follows the coding policy. In architecture review, check whether changes contradict documented specifications, types, schemas, or config formats.
 
 Verification targets:
 
@@ -460,10 +460,10 @@ REJECT when these patterns are found:
 
 ## Call Chain Verification
 
-When new parameters/fields are added, verify not just the changed file but also callers.
+Missing wiring after contract changes follows the coding policy. In architecture review, check whether new parameters or fields actually reach callers, producers, and readers instead of staying local to the changed file.
 
 Verification steps:
-1. When finding new optional parameters or interface fields, `Grep` all callers
+1. When finding new optional parameters or interface fields, search all callers
 2. Check if all callers pass the new parameter
 3. If fallback value (`?? default`) exists, verify if fallback is used as intended
 
@@ -471,7 +471,7 @@ Danger patterns:
 
 | Pattern | Problem | Detection |
 |---------|---------|-----------|
-| `options.xxx ?? fallback` where all callers omit `xxx` | Feature implemented but always falls back | grep callers |
+| `options.xxx ?? fallback` where all callers omit `xxx` | Feature implemented but always falls back | Check callers |
 | Tests set values directly with mocks | Don't go through actual call chain | Check test construction |
 | `executeXxx()` doesn't receive `options` it uses internally | No route to pass value from above | Check function signature |
 
@@ -493,12 +493,12 @@ Call chain verification applies not only to "missing wiring" but also to the rev
 
 | Pattern | Problem | Detection |
 |---------|---------|-----------|
-| TTY check when all callers require TTY | Unreachable branch remains | grep all callers' preconditions |
+| TTY check when all callers require TTY | Unreachable branch remains | Check all callers' preconditions |
 | Null guard when callers already check null | Redundant defense | Trace caller constraints |
 | Runtime type check when TypeScript types constrain | Not trusting type safety | Check TypeScript type constraints |
 
 Verification steps:
-1. When finding defensive branches (TTY check, null guard, etc.), grep all callers
+1. When finding defensive branches (TTY check, null guard, etc.), check all callers
 2. If all callers already guarantee the condition, guard is unnecessary → REJECT
 3. If some callers don't guarantee it, keep the guard
 

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

@@ -84,6 +84,54 @@ Event Granularity:
 - Appropriate: `ShippingAddressChanged` → Intent is clear
 - Too coarse: `OrderModified` → What changed is unclear
 
+## Event Evolution
+
+Events are persisted contracts. When the current event type changes, old events must still be replayable. Translation of old events belongs in the upcaster / migration layer at the event-store boundary, not in the event type itself or in domain logic.
+
+| Criteria | Judgment |
+|----------|----------|
+| Persisted event type or fields changed with no translation path | REJECT |
+| Current event type keeps aliases or compatibility-only properties for old field names | REJECT. Keep history compatibility in upcasters |
+| Aggregate or apply directly interprets old event shapes | REJECT. Convert to current events before replay |
+| Event carries "previous value" only for compatibility | REJECT. Events represent the fact after it happened |
+| Upcaster converts old payloads to the current event meaning | OK |
+| Tests verify old payloads deserialize into current events through the upcaster | OK |
+
+Responsibility split for event evolution:
+
+| Responsibility | Place |
+|----------------|-------|
+| Current event meaning and fields | Event type |
+| Translation of old payloads | Upcaster / migration layer |
+| State restoration by event replay | Aggregate `apply` |
+| Guarantee that old events can become current events | Upcaster tests |
+
+```kotlin
+// NG - mixing old-field compatibility into the current event type
+data class OrderAssignedEvent(
+    val orderId: String,
+    @JsonAlias("assigneeId")
+    val assigneeIds: List<String>
+)
+
+// OK - current event type represents only the current contract
+data class OrderAssignedEvent(
+    val orderId: String,
+    val assigneeIds: List<String>
+)
+```
+
+```kotlin
+// OK - convert old payloads to current payloads in the upcaster
+when (eventType) {
+    OrderAssignedEvent::class.java.typeName -> {
+        event.moveTextFieldToArray("assigneeId", "assigneeIds")
+    }
+}
+```
+
+Whether to keep old event classes depends on the framework and operations policy. In general, do not treat old classes as normal domain events; treat old serialized type names and payloads as the upcaster input contract and cover them with tests.
+
 ## Command Handlers
 
 | Criteria | Judgment |

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

@@ -117,6 +117,19 @@ Exception (OK for child to have local state):
 | Inappropriate useEffect dependencies | REJECT |
 | Initial load tied to unstable Context/Provider function references | REJECT |
 
+### Canonical and Derived State
+
+State should hold canonical values such as user input, server data, and temporary UI state. Display values, aggregates, selection states, sorted results, and grouped results that can be computed from canonical state are derived values and must not be kept as independent state.
+
+| Criteria | Judgment |
+|----------|----------|
+| A value that can always be computed from one state is kept as another state | REJECT |
+| Multiple state fields have invariants that require constant synchronization | REJECT |
+| Display labels, counts, totals, all-selected flags, sorted results, or grouped results are kept as canonical state | REJECT |
+| API sending, persistence, or diffing depends on derived state instead of canonical state | REJECT |
+| Only canonical state is stored, and display, aggregation, and decisions are derived via selectors, render logic, or useMemo | OK |
+| Derived values required by external contracts are generated from canonical state at send or persistence boundaries | OK |
+
 State Placement Guidelines:
 
 | State Nature | Recommended Placement |

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

@@ -11,6 +11,7 @@
 |--------|--------|-------|
 | Component design | ✅ | - |
 | State management | ✅ | - |
+| Canonical and derived state | ✅ | - |
 | Performance | ✅ | - |
 | Accessibility | ✅ | - |
 | Type safety | ✅ | - |

package/builtins/en/facets/policies/ai-antipattern.md

@@ -153,6 +153,25 @@ Legacy support criteria:
 - Do not add `.transform()` normalization, `LEGACY_*_MAP` mappings, or `@deprecated` type definitions
 - Support only new values and keep it simple
 
+### Over-Abstracting with Function Objects
+
+AI often turns a small number of concrete branches into config arrays, function objects, and generic loops to make the code look "extensible". The problem is not Strategy itself; the problem is hiding differences in data without naming the concept. A Strategy is useful when it names a domain concept and makes the replacement boundary explicit.
+
+| Pattern | Example | Verdict |
+|---------|---------|---------|
+| Single-use operation config array | Processing `[{ kind, fields, removedFields }]` in a loop | REJECT |
+| Deletions, side effects, or exception cases are hidden in config objects | Readers must inspect config values to find destructive behavior | REJECT |
+| Function object introduced when each branch is only 1-3 lines | `handlers[type]()` adds indirection only | REJECT |
+| Strategy represents a domain concept and clarifies the implementation boundary | `TaxPolicy`, `PaymentMethod`, `RetryStrategy` | OK |
+| Many branches share the same shape and are expected to grow | Consider a handler map | OK |
+
+Verification approach:
+1. Grep usage sites for added arrays, Maps, Strategies, or function objects
+2. If used in only one place, check whether explicit branching would be clearer
+3. Check whether side effects, deleted fields, or compatibility behavior are hidden in config objects
+4. Prefer `when` / `switch` when branch names sufficiently express domain meaning
+5. Allow Strategy when naming the concept improves understanding
+
 ## Premature Caching Strategy Introduction
 
 AI tends to proactively introduce caching mechanisms to "improve" performance. Do not add caching strategies until explicitly requested.

package/builtins/en/facets/policies/coding.md

@@ -14,6 +14,7 @@ Prioritize correctness over speed, and code accuracy over ease of implementation
 | Boy Scout | Leave touched areas a little better than you found them |
 | Fail Fast | Detect errors early. Never swallow them |
 | Project scripts first | Use project-defined scripts for tool execution. Direct invocation is a last resort |
+| State normalization | Do not keep the same fact in multiple states |
 
 ## No Fallbacks or Default Arguments
 
@@ -183,6 +184,41 @@ const handlers = { A: handleA, B: handleB, C: handleC };
 handlers[type]?.();
 ```
 
+### Do Not Over-Abstract
+
+Use abstraction to reduce duplication and real axes of change, and also to name concepts so the code is easier to understand. Turning a few concrete operations into "config objects + function objects + loops" is not abstraction if it only makes domain differences harder to read.
+
+| Criteria | Judgment |
+|----------|----------|
+| A small number of branches differs by event type, state, or domain concept | Use explicit `when` / `switch` |
+| The same operation with the same argument shape repeats in 3+ places | Consider abstraction |
+| A config array or function object is used in only one place | REJECT. Prefer explicit branching first |
+| Side effects or removed fields cannot be understood without reading config objects | REJECT |
+| Strategy names a domain concept and makes interchangeable implementations explicit | OK |
+| Branch names read as domain concepts | OK |
+
+```typescript
+// ❌ Over-abstracted - readers must inspect both the config array and loop to see behavior
+const operations = [
+  { kind: 'create', normalize: ['owner'], remove: [] },
+  { kind: 'revise', normalize: ['owner'], remove: ['legacyOwner'] },
+]
+for (const operation of operations) {
+  applyOperation(record, operation)
+}
+
+// ✅ When branch meaning matters, make it explicit
+switch (record.kind) {
+  case 'create':
+    normalizeOwner(record)
+    break
+  case 'revise':
+    removeLegacyOwner(record)
+    normalizeOwner(record)
+    break
+}
+```
+
 ### Keep Abstraction Levels Consistent
 
 Within a single function, keep operations at the same granularity. Extract detailed operations into separate functions. Do not mix "what to do" with "how to do it."
@@ -319,11 +355,56 @@ Dependencies and triggers must match the conditions under which the behavior sho
 | Rerun conditions correspond to URL, filters, explicit refresh actions, or other intended behavior | OK |
 | Initialization and later refetch triggers are designed separately | OK |
 
+## Contract Change Consistency
+
+When changing contracts that other code or users depend on — types, interfaces, APIs, config schemas, persistence formats, events, or file formats — keep definitions, producers, consumers, and verification aligned in the same change.
+
+| Criteria | Judgment |
+|----------|----------|
+| Only the contract definition is changed, while callers, producers, or readers are not updated | REJECT |
+| A new argument, field, or config value is added but there is no route to pass it to consumers | REJECT |
+| Fields or values not present in the documented schema/config format are used | REJECT |
+| Mocks, fixtures, or test data return shapes that differ from the real contract | REJECT |
+| The contract change and updates to callers, producers, and tests are made in the same change | OK |
+
 ## State Management
 
 - Confine state to where it is used
 - Children do not modify state directly (notify parents via events)
 - State flow is unidirectional
+- Do not keep derived values that can be computed from canonical state as independent state
+- If multiple fields require constant synchronization, revisit the state model
+
+| Criteria | Judgment |
+|----------|----------|
+| A value that can always be computed from one state is kept as another state | REJECT |
+| Multiple states have invariants that must always stay in sync | REJECT |
+| Persistence, sending, or diffing depends on derived values | REJECT |
+| Only canonical state is stored, and derived values are generated at use sites or boundaries | OK |
+
+## Unfinished Code
+
+Do not leave TODO/FIXME comments, empty implementations, stubs, or commented-out old implementations as substitutes for completed code. Implement what is needed now and delete what is not needed.
+
+| Criteria | Judgment |
+|----------|----------|
+| TODO/FIXME without an issue number, external blocker, and removal condition | REJECT |
+| Authorization, validation, persistence, or error handling is deferred with TODO | REJECT |
+| Empty implementations, `return null`, `pass`, or commented-out old implementations remain | REJECT |
+| An external dependency or known blocker makes implementation impossible now, with issue number and removal condition documented | Acceptable |
+| TODO only for future extension | REJECT |
+
+## Sensitive Information Handling
+
+Do not expose passwords, tokens, API keys, session IDs, auth headers, personal information, or other sensitive data in code, logs, error responses, or test output.
+
+| Criteria | Judgment |
+|----------|----------|
+| Sensitive data is hardcoded in source code or config files | REJECT |
+| Logs, exceptions, error responses, or test snapshots contain sensitive data | REJECT |
+| Whole requests or DTOs are logged and may include sensitive fields | REJECT |
+| Sensitive fields are explicitly omitted or masked | OK |
+| Debug logs include personal data but are assumed disabled in production | Warning. Verify it cannot leak through misconfiguration |
 
 ## Error Handling
 
@@ -486,10 +567,11 @@ Verification approach:
 - **Fallbacks are prohibited by default** - Do not write fallbacks using `?? 'unknown'`, `|| 'default'`, or swallowing via `try-catch`. Propagate errors upward. If absolutely necessary, add a comment explaining why
 - **Explanatory comments** - Express intent through code. Do not write What/How comments
 - **Unused code** - Do not write "just in case" code
+- **Unfinished code** - Do not leave TODO/FIXME without an issue number, external blocker, and removal condition; do not leave stubs or commented-out old code
 - **any type** - Do not break type safety
 - **Direct mutation of objects/arrays** - Create new instances with spread operators
 - **console.log** - Do not leave in production code
-- **Hardcoded secrets**
+- **Sensitive information exposure** - Do not include sensitive data in hardcoded values, logs, error responses, or test output
 - **Scattered hardcoded contract strings** - File names and config key names must be defined as constants in one place. Scattered literals are prohibited
 - **Scattered try-catch** - Centralize error handling at the upper layer
 - **Unsolicited backward compatibility / legacy support** - Not needed unless explicitly instructed
@@ -497,6 +579,6 @@ Verification approach:
 - **Replaced code surviving after refactoring** - Remove replaced code and exports. Do not keep unless explicitly told to
 - **Workarounds that bypass safety mechanisms** - If the root fix is correct, no additional bypass is needed
 - **Direct tool execution bypassing project scripts** - `npx tool` and similar bypass the lockfile, causing version mismatches. Look for project-defined scripts (npm scripts, Makefile, etc.) first. Only consider direct execution when no script exists
-- **Missing wiring** - When adding new parameters or fields, grep the entire call chain to verify. If callers do not pass the value, `options.xxx ?? fallback` always uses the fallback
+- **Missing wiring** - When adding new parameters or fields, search the entire call chain to verify. If callers do not pass the value, `options.xxx ?? fallback` always uses the fallback
 - **Redundant conditionals** - When if/else calls the same function with only argument differences, unify using ternary operators or spread syntax
-- **Copy-paste patterns** - Before writing new code, grep for existing implementations of the same kind and follow the existing pattern. Do not introduce your own style
+- **Copy-paste patterns** - Before writing new code, search for existing implementations of the same kind and follow the existing pattern. Do not introduce your own style

package/builtins/en/facets/policies/qa.md

@@ -22,7 +22,9 @@
 
 | Pattern | Verdict |
 |---------|---------|
-| Abandoned TODO/FIXME | Warning |
+| TODO/FIXME without an issue number, external blocker, and removal condition | REJECT |
+| TODO/FIXME with issue number, external blocker, and removal condition | Warning |
+| Empty implementations, stubs, or commented-out old implementations left behind | REJECT |
 | @ts-ignore, @ts-expect-error without reason | Warning |
 | eslint-disable without reason | Warning |
 | Usage of deprecated APIs | Warning |

package/builtins/en/facets/policies/review.md

@@ -37,13 +37,15 @@ REJECT without exception if any of the following apply.
 - Unused code ("just in case" code)
 - Direct mutation of objects/arrays
 - Swallowed errors (empty catch blocks)
-- TODO comments (not tracked in an issue)
+- TODO/FIXME without an issue number, external blocker, and removal condition
 - Essentially identical logic duplicated (DRY violation)
 - Method proliferation doing the same thing (should be absorbed by configuration differences)
 - Specific implementation leaking into generic layers (imports and branching for specific implementations in generic layers)
 - Internal implementation exported from public API (infrastructure functions or internal classes exposed publicly)
 - Replaced code/exports surviving after refactoring
 - Missing cross-validation of related fields (invariants of semantically coupled config values left unverified)
+- Missing caller, producer, or test data updates after a contract change
+- Sensitive data exposed in logs, error responses, or test output
 
 A DRY finding is not complete unless the proposed consolidation target is also sound. A consolidation proposal is invalid unless all of the following hold.
 
@@ -59,7 +61,7 @@ Not blocking, but improvement is recommended.
 - Tests coupled to implementation details
 - Overly complex functions/files
 - Unclear naming
-- Abandoned TODO/FIXME (those with issue numbers are acceptable)
+- TODO/FIXME with issue number, external blocker, and removal condition
 - `@ts-ignore` or `eslint-disable` without justification
 
 ### APPROVE
@@ -73,7 +75,7 @@ Always verify facts before raising an issue.
 | Do | Do Not |
 |----|--------|
 | Open the file and check actual code | Assume "it should be fixed already" |
-| Search for call sites and usages with grep | Raise issues based on memory |
+| Search for call sites and usages | Raise issues based on memory |
 | Cross-reference type definitions and schemas | Guess that code is dead |
 | Distinguish generated files (reports, etc.) from source | Review generated files as if they were source code |
 | Verify tool output is readable and uncorrupted | Raise issues based on garbled or abnormal output |

package/builtins/en/facets/policies/testing.md

@@ -12,6 +12,7 @@ Every behavior change requires a corresponding test, and every bug fix requires
 | Independence | Do not depend on other tests or execution order |
 | Type safety | Code must pass the build (type check) |
 | Reproducibility | Do not depend on time or randomness. Same result every run |
+| Do not freeze non-executable assets | Do not make prose or section structure that does not define runtime behavior a CI failure condition |
 
 ## Coverage Criteria
 
@@ -33,6 +34,23 @@ Every behavior change requires a corresponding test, and every bug fix requires
 
 **Note:** When a design reference is provided, UI appearance verification is elevated to medium priority. Refer to the Design Fidelity Policy.
 
+## Non-Executable Asset Tests
+
+Tests that freeze prose, headings, or structure in non-executable assets such as explanations, guides, README files, or Markdown documentation are prohibited by default.
+These assets change often during wording improvements and reorganization, so making prose diffs fail CI creates high maintenance cost.
+
+| Criteria | Verdict |
+|----------|---------|
+| Exact prose, heading, or section-structure assertions for non-executable assets | REJECT |
+| Scanning all non-executable assets only to enforce wording or terminology | REJECT |
+| Tests that require explanatory files that may be deleted or consolidated | REJECT |
+| Adding tests for docs-only changes when no executable contract exists | REJECT |
+| Validating executable or machine-processed contracts such as CLI examples, config examples, or generated artifacts | OK |
+| Contract tests for schemas, configuration, code, generators, or runtime behavior | OK |
+| Not adding tests for docs-only changes that have no executable contract | OK |
+
+Verify non-executable asset changes with review, Markdown lint, link checks, or sample command execution when needed.
+
 ## Test Structure: Given-When-Then
 
 ```typescript
@@ -57,6 +75,18 @@ test('should return NotFound error when user does not exist', async () => {
 | Clarity | Failure cause is obvious | Failure cause is unclear |
 | Focus | One test, one concept | Multiple concerns mixed |
 
+## Test Data and Fixtures
+
+Test data should explicitly generate the minimum facts needed by each test. Mutating shared fixtures or using mocks that drift from real contracts reduces test reliability.
+
+| Criteria | Verdict |
+|----------|---------|
+| Shared fixtures are mutated and reused across tests | REJECT |
+| Mocks, fixtures, or factories return shapes that differ from real types or API contracts | REJECT |
+| Each test hand-writes a huge full-field fixture | Warning. Consider a factory |
+| Factories provide defaults and each test overrides only relevant fields | OK |
+| Contract changes update fixtures, mocks, and snapshots in the same change | OK |
+
 ### Naming
 
 Test names describe expected behavior. Use the `should {expected behavior} when {condition}` pattern.
@@ -125,8 +155,11 @@ Verify data flow coupling that unit tests alone cannot cover.
 
 ## E2E Test Criteria
 
+Design E2E tests from the entry points users actually use. Use code-level entry points such as routes, commands, endpoints, navigation, buttons, or external callbacks, not documentation assumptions alone.
+
 | Criteria | Verdict |
 |----------|---------|
+| E2E tests are written for imagined flows without checking real entry points | REJECT |
 | Hitting production APIs without mocking external calls | REJECT. Test reproducibility is lost |
 | Mocking the core logic under test | REJECT. Defeats the purpose of E2E |
 | Using fixed sleep for timing synchronization | REJECT. Use state-based waits |