takt 0.42.0 → 0.43.0

package/README.md

@@ -279,6 +279,7 @@ See [External Integrations](./docs/external-integrations.md) for other community
 
 | Document | Description |
 |----------|-------------|
+| [Tutorial](./docs/tutorial.md) | Improve one example over three phases while queuing, running, and inspecting tasks |
 | [CLI Reference](./docs/cli-reference.md) | All commands and options |
 | [Configuration](./docs/configuration.md) | Global and project settings |
 | [Design Philosophy](./docs/design-philosophy.md) | Why TAKT is built around workflows, facets, feedback loops, and traceability |

package/builtins/en/config.yaml

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

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

@@ -6,10 +6,13 @@ Analyze the implementation task and, if decomposition is appropriate, split into
 
 1. Assess whether decomposition is appropriate
    - Identify files to change and check inter-file dependencies
-   - If cross-cutting concerns exist (shared types, IDs, events), implement in a single part
+   - First look for parallelizable responsibility boundaries
+   - If cross-cutting concerns exist (shared types, IDs, events), consider staged work: foundation part -> consuming parts -> verification part
    - If few files are involved, or the task is a rename/refactoring, implement in a single part
+   - When parts.length === 1, first consider whether verification separation or staged work is possible
+   - Avoid oversized single parts such as "implementation and verification"
 
-2. If decomposing: prioritize splitting along frontend and backend boundaries
+2. If decomposing: prioritize splitting along frontend and backend boundaries, or group files by layer/module when that split does not fit
    - **If design references exist and backend changes are not explicitly required, do not decompose.** Visual structure, copy, spacing, and styling are tightly coupled, and splitting them increases design drift risk
    - **If design references exist, keep all UI components of the same screen in the same part.** Do not split headers, filters, cards, banners, and modals of one screen across different parts
    - Splitting between frontend (UI, components, styles) and backend (API, logic, data layer) is the most natural decomposition axis
@@ -19,6 +22,7 @@ Analyze the implementation task and, if decomposition is appropriate, split into
    - If there are type or interface dependencies, keep both sides in the same group
    - Never assign the same file to multiple parts
    - Keep test files and implementation files in the same part
+   - Separate implementation parts from verification parts
 
 3. Assign file ownership exclusively to each part
    - Each part's instruction must clearly state:
@@ -32,6 +36,7 @@ Analyze the implementation task and, if decomposition is appropriate, split into
    - If tests are already written, instruct parts to implement so existing tests pass
    - Refer to Quality Gates and plan any required verification as a dedicated single verification part
    - Do not make parallel implementation parts run duplicate full-build or full-test checks
+   - Do not duplicate npm test / npm run test:e2e:mock in each implementation part
 
 **Constraints:**
 - If tests or build verification are needed, run them as a dedicated single verification part after dependent implementation parts are complete

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -212,6 +212,7 @@ Detect comments that simply restate code behavior in natural language.
 | REJECT | JSDoc that only paraphrases the function name without adding information |
 | OK | Explains why a particular implementation was chosen |
 | OK | Explains the reason behind seemingly unusual behavior |
+| OK | Explains the calculation basis or components of a constant or magic number |
 | Best | No comment needed — the code itself communicates intent |
 
 ```typescript
@@ -238,6 +239,10 @@ if (status === 'interrupted') {
 // OK - Reason behind seemingly odd behavior
 // stay can cause loops, but is only used when explicitly specified by the user
 return step.name;
+
+// OK - Calculation basis for a constant
+// paddingTop + paddingBottom + button height
+const footerHeight = 24 + 12 + 48;
 ```
 
 **Direct State Mutation Detection Criteria:**

package/builtins/en/facets/knowledge/existing-system.md

@@ -0,0 +1,70 @@
+# Existing System Knowledge
+
+## Existing System Contracts
+
+In an existing system, contracts are not limited to explicit APIs. Values and structures observed by users or developers also function as contracts. A small code change can affect production screens, tests, reviews, and maintenance workflows.
+
+| Criteria | Judgment |
+|----------|----------|
+| User-visible copy or state changes | Contract change |
+| A value asserted by tests changes | Contract change |
+| Hook or component call shape changes | Contract change |
+| Only file placement or type names change | May still be a maintenance contract change |
+| Closed internal duplication is removed | Internal change if impact is contained |
+
+## Diff Classification
+
+Changes in existing systems are classified by causal relationship to the request. The question is whether the request requires the change, not whether the change is in a touched file.
+
+| Classification | Decision criteria |
+|----------------|-------------------|
+| Required change | Directly required to satisfy the request |
+| Related change | Required to wire, verify, or keep a required change consistent |
+| Unnecessary change | The request still succeeds without it |
+| Dangerous unnecessary change | The request still succeeds without it and it changes an existing contract |
+
+### Boundary of Related Changes
+
+A related change must have an explainable connection to a required change. Proximity, same file, or same responsibility is not enough.
+
+| Example | Classification |
+|---------|----------------|
+| Updating callers after adding a required parameter | Related change |
+| Deleting an old store after changing persistence boundary | Related change |
+| Renaming a touched component's Props type by preference | Unnecessary change |
+| Changing a hook return shape to a props object as cleanup | Dangerous unnecessary change |
+
+## Conflicts With General Quality Criteria
+
+In maintenance work, general design improvements and framework style are not always the highest priority. Even when the existing structure is imperfect, leaving it unchanged can be lower risk when the request does not require changing it.
+
+| Situation | Judgment |
+|-----------|----------|
+| Component extraction would look cleaner but is unnecessary for this fix | Do not change |
+| Renaming or relocating Props types only to match common style | Do not change |
+| The existing structure cannot satisfy the request | Change the minimum necessary scope |
+| The existing structure is the cause of the bug | Change it with reason and impact scope documented |
+
+## Meaning of Comments and Tests
+
+Comments and tests may preserve historical constraints or intent. Even comments that look explanatory can act like contracts when they document calculation rationale, platform constraints, or known workaround reasons.
+
+| Target | Handling |
+|--------|----------|
+| Calculation rationale comments | Preserve |
+| Constraint or workaround comments | Preserve |
+| Comments contradicting code | Correct |
+| Comments that only restate function names | May consider deleting |
+| Existing test expectations | Treat as existing contracts |
+
+## Maintenance Change Risk
+
+For maintenance work, preserving existing behavior is more important than making new code look better. Even a technically good change increases review cost and regression risk when it is outside the request.
+
+| Change | Risk |
+|--------|------|
+| Rename | Increases grep, history tracing, and review scope |
+| File move | Changes ownership boundaries, imports, and history tracing |
+| UI contract change | Changes user experience, assistive technology behavior, and tests |
+| Test weakening | Reduces regression detection |
+| Extra abstraction | Adds present understanding cost for future flexibility |

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

@@ -81,6 +81,18 @@ Third-party UI libraries such as data grids, date pickers, charts, and virtualiz
 | The real component is rendered with representative props and verified not to crash at screen level | OK |
 | Prop shapes are chosen by referencing existing in-project usage patterns and the installed version | OK |
 
+### Accessibility Contracts
+
+Accessible names, roles, and states are UI contracts consumed by assistive technologies and tests. Add appropriate accessibility attributes for new UI elements, but treat changes to existing accessibility contracts like other user-facing copy or behavior changes.
+
+| Criteria | Judgment |
+|----------|----------|
+| A new interactive element has no accessible name | REJECT |
+| Checked, expanded, disabled, or similar state is not exposed to assistive technologies | Warning |
+| An existing accessible name is changed without being required by the task | REJECT |
+| Existing accessible names are preserved while missing role/state is added | OK |
+| The reason and impact scope for changing an existing contract are explicit | OK |
+
 ## State Management
 
 Child components do not modify their own state. They bubble events to parent, and parent manipulates state.

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

@@ -120,6 +120,41 @@ When shared state is required, call the hook once in the nearest common parent a
 | Multiple components call the same stateful hook independently when they need shared state | REJECT |
 | A hook returns JSX | REJECT |
 
+### Props Type Placement and Hook Boundaries
+
+Props types that belong to a single component should generally live in the same file as that component. Separate type files are appropriate when the contract is shared by multiple components, is part of a public API, or has independent meaning as a domain model.
+
+| Criteria | Judgment |
+|----------|----------|
+| A single component's private Props type is moved to a `types` file without a clear reason | Warning |
+| Props are moved to a separate file only so a hook can import a component's Props type | REJECT |
+| Shared Props/data contracts used by multiple components or public APIs live in a separate file | OK |
+| A hook returns state, events, and derived values while a container maps them to component props | OK |
+| Even when a hook returns a props-like object, the hook does not depend on the component's Props type | OK |
+
+```tsx
+// REJECT - the hook depends on a specific component's Props contract
+import type { DialogProps } from './Dialog'
+
+export function useDialog(): { dialogProps: DialogProps } {
+  return { dialogProps: { open, onOpenChange } }
+}
+
+// OK - component-local Props stay with the component
+interface DialogProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+}
+
+export function Dialog(props: DialogProps) {
+  return <Modal {...props} />
+}
+
+// OK - the hook returns UI state and operations, and the caller passes them to the component
+const dialog = useDialog()
+return <Dialog open={dialog.open} onOpenChange={dialog.setOpen} />
+```
+
 ## Handling exhaustive-deps
 
 `react-hooks/exhaustive-deps` is not a rule to satisfy mechanically. If adding dependencies changes a mount-only effect into a loop, keep the effect mount-only and document why the suppression exists.

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

@@ -0,0 +1,41 @@
+```markdown
+# Coding Review
+
+## Result: APPROVE / REJECT
+
+## Summary
+{Summarize the review result in 1-2 sentences}
+
+## Current Iteration Findings (new)
+| # | finding_id | family_tag | Severity | Location | Issue | Impact | Fix Suggestion |
+|---|------------|------------|----------|----------|-------|--------|----------------|
+| 1 | CODE-NEW-src-file-L42 | bug | High / Medium / Low | `src/file.ts:42` | {Issue} | {Impact} | {Fix suggestion} |
+
+## Carry-over Findings (persists)
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | CODE-PERSIST-src-file-L77 | regression | `src/file.ts:77` | `src/file.ts:77` | {Unresolved issue} | {Fix suggestion} |
+
+## Resolved Findings (resolved)
+| finding_id | Resolution Evidence |
+|------------|---------------------|
+| CODE-RESOLVED-src-file-L10 | Resolved at `src/file.ts:10` |
+
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | CODE-REOPENED-src-file-L55 | bug | `Previously: src/file.ts:10` | `src/file.ts:55` | {Reopened issue} | {Fix suggestion} |
+
+## Verification Evidence
+- Diff review: {What was checked}
+- Build: {Result, or state unverified}
+- Tests: {Result, or state unverified}
+
+## Rejection Gate
+- REJECT only when at least one finding exists in `new`, `persists`, or `reopened`
+- Findings without `finding_id` are invalid
+```
+
+**Cognitive load reduction rules:**
+- APPROVE: Summary only (5 lines or fewer)
+- REJECT: Include only relevant finding rows (30 lines or fewer)

package/builtins/en/facets/output-contracts/maintenance-scope.md

@@ -0,0 +1,29 @@
+```markdown
+# Maintenance Change Scope
+
+## Task
+{One-line task summary}
+
+## Required Changes
+| File | Reason | Requirement Mapping |
+|------|--------|---------------------|
+| {File} | {Reason} | {Mapped requirement} |
+
+## Related Changes
+| File | Reason | Relation to Required Change |
+|------|--------|-----------------------------|
+| {File} | {Reason} | {Relation} |
+
+## Existing Contracts Preserved
+| Contract | Target | Preservation |
+|----------|--------|--------------|
+| {Contract type} | {Target} | {What is preserved} |
+
+## Unnecessary Change Check
+| Check Target | Result | Notes |
+|--------------|--------|-------|
+| Renames or moves | {Present/none} | {Notes} |
+| UI copy or accessibility | {Present/none} | {Notes} |
+| Comment deletion | {Present/none} | {Notes} |
+| Test expectation changes | {Present/none} | {Notes} |
+```