takt 0.46.0 → 0.47.0

package/builtins/en/facets/personas/findings-manager.md

@@ -0,0 +1,18 @@
+# Findings Manager
+
+You manage Finding Contract reconciliation.
+
+Compare reviewer raw findings with the existing ledger, then classify each issue as an existing match, new finding, resolved finding, or reopened finding. The engine allocates final IDs, so only map raw findings to existing IDs and grouped rawFindingIds.
+
+Responsibilities:
+- Reconcile the prior integrated ledger with current raw findings.
+- Classify raw findings as existing matches, new findings, resolved findings, or reopened findings.
+- Group rawFindingIds into structured data that lets the engine allocate final IDs.
+
+Rules:
+- Do not make semantic severity or priority judgments.
+- Do not merge findings with different `family_tag`, location, or issue meaning.
+- Do not blame reviewers.
+- Do not allocate final `finding_id` values.
+- Treat identical location + `family_tag` + issue meaning as the existing-match standard.
+- Treat ambiguous or merely similar findings as distinct.

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

@@ -1,5 +1,20 @@
 # AI Antipattern Detection Criteria
 
+Detect assumptions, over-implementation, and superficial fixes that AI-generated changes commonly introduce.
+
+## Principles
+
+| Principle | Criteria |
+|-----------|----------|
+| Requirement fit | Verify that the implementation answers the actual request |
+| Reality check | Do not infer APIs, settings, fields, or wiring paths |
+| Context fit | Match existing naming, structure, error handling, logging, and tests |
+| Minimal diff | Do not mix in unnecessary features, abstractions, settings, or compatibility code |
+| Contract preservation | Do not change UI copy, public APIs, return values, errors, or test expectations out of scope |
+| Direct fixes | Do not replace a fix with tests or documentation explaining the issue |
+| Reachability | Confirm that added or retained code is used by current call paths |
+| Verifiability | Check code paths, usage sites, and execution results instead of explanations |
+
 ## Assumption Verification
 
 AI often makes assumptions. Verify them.
@@ -136,6 +151,22 @@ Questions to ask:
 - Does it feel like it belongs here?
 - Are there unexplained deviations from project conventions?
 
+## Integration Pattern Consistency
+
+Check whether the same kind of API connection, such as REST calls, is implemented in inconsistent ways within the project.
+
+| Pattern | Example | Verdict |
+|---------|---------|---------|
+| Mixed generated and hand-written clients | Screen A uses Orval-generated hooks, screen B calls axiosInstance directly | REJECT |
+| Different implementations for the same data-fetching pattern | Screen A uses useQuery + axios, screen B uses generated hooks | REJECT |
+| Mixed data type definition styles | Screen A uses generated types, screen B uses hand-written types | REJECT |
+
+Verification approach:
+1. Check the API calling style in the diff
+2. Grep existing code for the style used by code with the same purpose
+3. Check whether the project has API generation config, such as orval.config.ts
+4. If inconsistent, flag unification to the project standard pattern
+
 ## Scope Creep Detection
 
 AI tends to over-deliver. Check for unnecessary additions.

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

@@ -11,6 +11,11 @@ Define the shared judgment criteria and behavioral principles for all reviewers.
 | Fact-check | Verify against actual code before raising issues. Do not speculate |
 | Practical fixes | Propose implementable solutions, not theoretical ideals |
 | State consistency | For side effects and state changes, verify that success, failure, and interruption paths have no missing, duplicated, or inconsistent effects |
+| Contract coverage | Verify new contracts across normal entries, derived conditions, validation, evaluation, output, and re-injection paths |
+| Contract consistency | Verify that contracts carried by consolidation or abstraction are applied to existing equivalent branches by the same standard |
+| Specification completeness | When changing a user-facing contract, verify that implementation, tests, and documentation describe the same lookup order, override rules, special syntax, and failure conditions |
+| Requirement anchoring | Do not reinterpret required task items as optional, out of scope, or different requirements for implementation convenience |
+| Resolution judgment | Judge `resolved` against the original finding acceptance criteria and original task requirements, not merely against the presence of a fix |
 | Behavior evidence | Verify what behavior the tests or logs prove, not merely that they exist |
 | Boy Scout | Have problems fixed within the task scope when they are in changed code or in areas directly affecting correctness, contracts, or wiring of the change |
 
@@ -48,7 +53,10 @@ REJECT without exception if any of the following apply.
 - 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
+- Missing caller, producer, consumer, validator, test data, or derived-entry updates after a contract change
+- User-facing contract changes for configuration, CLI, or file formats where documentation or examples omit priority, first-match/merge behavior, inline overrides, scoped/special references, or failure conditions
+- Existing branches with the same contract remain on the old implementation after adding or changing a shared helper, normalizer, builder, or adapter
+- Fields, attributes, outputs, settings, or identifiers requested by the task are treated as optional, unset, out of scope, or missing for some entry point or execution mode without explicit evidence
 - Missing, duplicated, or incorrectly ordered effects in side-effect or state-change paths
 - Sensitive data exposed in logs, error responses, or test output
 
@@ -129,12 +137,39 @@ Every issue raised must include the following.
 
 To prevent circular rejections, track findings by ID.
 
+Finding Contract applies to the whole review workflow, not to individual findings.
+Treat a workflow as using Finding Contract only when it is declared at workflow level
+with `finding_contract` configuration. A `findings-ledger.json` file, a dedicated
+"Finding Contract" section in the instruction template, or an `Observed Findings`
+table in the output contract is supporting evidence inside an already configured
+Finding Contract workflow; none of these artifacts enables Finding Contract by itself.
+
+When Finding Contract is in use, reviewers must not allocate new final `finding_id`
+values and must not classify lifecycle as `new`, `persists`, `resolved`, or
+`reopened`. Report observed problems as raw findings in the `Observed Findings`
+table. Refer to existing IDs only when they are present in the ledger. ID assignment
+and lifecycle matching belong to the findings-manager and engine.
+
+When a workflow is configured with Finding Contract and a parseable ledger is available,
+the ledger is the authoritative source for tracked findings. Individual reports and raw
+finding details are supporting evidence. If a ledger exists but is incomplete, follow
+mapped findings from the ledger and treat unmapped raw findings as potential new entries
+pending findings-manager reconciliation. If no parseable ledger is available in a
+configured Finding Contract workflow, use report history only as supporting evidence for
+observed raw findings. Do not assign final `finding_id` values or lifecycle states and
+do not apply the legacy rules; wait for ledger regeneration or findings-manager
+reconciliation.
+
+### Legacy Finding ID Rules (for workflows without Finding Contract)
+
+When a workflow does not use `finding_contract` configuration, follow these legacy rules.
+
 - Every issue raised in a REJECT must include a `finding_id`
 - If the same issue is raised again, reuse the same `finding_id`
 - For repeated issues, set status to `persists` and include concrete evidence (file/line) that it remains unresolved
 - New issues must use status `new`
 - Resolved issues must be listed with status `resolved`
-- Issues without `finding_id` are invalid (cannot be used as rejection grounds)
+- Issues without `finding_id` are invalid (cannot be used as rejection grounds). This legacy rule does not apply to Finding Contract workflows.
 - REJECT is allowed only when there is at least one `new` or `persists` issue
 - Before treating a prior finding as resolved, verify that the fix did not introduce a different structural or contract problem
 
@@ -240,6 +275,7 @@ The review target is the entire cumulative diff from the task's starting point (
 - Use `order.md`, `plan.md`, and the actual code as primary sources
 - Treat decisions from earlier steps (prior review results, planning decisions) as supplementary
 - When information conflicts, prioritize `order.md` / `plan.md` / actual code
+- When a user-facing specification changes, treat documentation and configuration examples as part of the contract and verify that every behavior listed in the requirements is present
 
 ### Referring to Design Decisions
 
@@ -247,6 +283,19 @@ The review target is the entire cumulative diff from the task's starting point (
 - Do not dismiss intentional decisions as false positives just because they were recorded. Evaluate validity against `order.md` / `plan.md` / actual code
 - If the design decision itself is flawed, raise it
 
+### Full Entry Review for Contract Additions and Changes
+
+When the diff adds or changes a contract such as a config value, state, condition expression, file format, event, builder, adapter, or state-transition function, enumerate and reconcile every entry, exit, and re-injection path that can carry that contract.
+
+- Verify that definition, production, normalization, validation, evaluation, persistence, output, and event emission all apply the same contract
+- Check derived paths as well as the normal entry: derived conditions, aggregate conditions, parent/child workflows, loop decisions, early exits, and exception paths
+- When persisted data or externally supplied data is re-injected into JSON, Markdown, logs, events, or later instructions, include escaping, boundary handling, and failure behavior in the contract
+- Search for existing returns, throws, catches, early returns, branches, and call sites with the same responsibility
+- If an existing branch does not satisfy the new contract, treat it as related code even if the code itself predates the change
+- If tests cover only the new path and do not verify existing equivalent branches or derived entries, treat it as a coverage gap
+- Treating a required contract as optional, excluded, or a different requirement requires evidence from the task spec, specification, or explicit user instruction
+- "Not explicitly stated in the task requirements" is not a valid reason to mark a contract inconsistency introduced by the diff as non-blocking
+
 ### Reviewing Side Effects and State Transitions
 
 When a change involves side effects or state changes such as external calls, configuration application, sessions, queues, locks, subscriptions, caches, or temporary resources, do not judge from the happy path alone.
@@ -259,11 +308,18 @@ When a change involves side effects or state changes such as external calls, con
 
 ### Tracking Findings from Previous Reviews
 
-- Look in the Report Directory for review reports this step has previously produced, along with their timestamped history
-- Treat the unsuffixed file as the latest result and the most recent `{report-name}.{timestamp}` as the previous result
-- `Previous Response` may be used as supplementary information, but finding state determinations must prioritize the report history
-- Do not drop open findings from the previous report when producing the new report
-- Apply the `finding_id` management rules when classifying each finding as `new` / `persists` / `resolved` / `reopened`
+**Precedence:**
+
+1. If a parseable Finding Contract ledger / `findings-ledger.json` is available in a workflow configured with Finding Contract, use the ledger as the authoritative source for tracked findings. Fix only open findings from the ledger (`new`, `persists`, or `reopened`); ignore resolved or closed findings. Treat individual reports as supporting evidence reachable from the ledger.
+2. If a ledger exists but is incomplete, follow mapped findings from the ledger and treat unmapped raw findings as potential new entries pending findings-manager reconciliation.
+3. If the workflow is configured with Finding Contract but no parseable ledger is available, use the latest review reports in the Report Directory only as supporting evidence for observed raw findings. Do not assign final `finding_id` values or lifecycle states and do not apply the legacy rules; wait for ledger regeneration or findings-manager reconciliation.
+4. If the workflow does not use `finding_contract` configuration, use the latest review reports in the Report Directory as the primary evidence and apply the legacy rules:
+   - Look in the Report Directory for review reports this step has previously produced, along with their timestamped history
+   - Treat the unsuffixed file as the latest result and the most recent `{report-name}.{timestamp}` as the previous result
+   - `Previous Response` may be used as supplementary information, but finding state determinations must prioritize the report history
+   - Do not drop open findings from the previous report when producing the new report
+   - Apply the `finding_id` management rules when classifying each finding as `new` / `persists` / `resolved` / `reopened`
+   - Mark `resolved` only when the original expected result and original requirement are satisfied, not merely because a patch exists
 
 ### Final Decision Steps
 
@@ -273,12 +329,4 @@ When a change involves side effects or state changes such as external calls, con
 
 ## Detecting Circular Arguments
 
-When the same kind of issue keeps recurring, reconsider the approach itself rather than repeating the same fix instructions.
-
-### When the Same Problem Recurs
-
-1. Check if the same kind of issue is being repeated
-2. If so, propose an alternative approach instead of granular fix instructions
-3. Even when rejecting, include the perspective of "a different approach should be considered"
-
-Rather than repeating "fix this again," stop and suggest a different path.
+When the same kind of issue keeps recurring, reconsider the approach itself rather than repeating granular fix instructions.

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

@@ -22,6 +22,8 @@ Every behavior change requires a corresponding test, and every bug fix requires
 | Bug fix | Regression test required. REJECT if missing |
 | Behavior change | Test update required. REJECT if missing |
 | Side-effect or state-transition change | Successful path and representative failure paths must be verified. REJECT if failure paths are untested |
+| Contract changes through consolidation or abstraction | Must verify that the contract holds on existing equivalent branches, not only on the new shared path |
+| Parser or configuration boundary changes | Must verify syntactically valid inputs with unexpected shapes, missing values, and isolation from personal configuration |
 | Build (type check) | Build must succeed. REJECT if it fails |
 | Edge cases / boundary values | Test recommended (Warning) |
 
@@ -100,6 +102,28 @@ Changes involving side effects or state transitions are not sufficiently verifie
 | Mock-verified behavior is not distinguished from unverified real-integration scope | Warning. REJECT when it is a primary requirement |
 | Successful path, representative failure paths, and boundary state transitions are each verified | OK |
 
+## Testing Contract Changes and Existing Branches
+
+When a change standardizes a contract through a shared helper, normalizer, builder, or adapter, testing only the newly added path is not sufficient. Verify that existing equivalent branches satisfy the same contract.
+
+| Criteria | Verdict |
+|----------|---------|
+| Only the new shared path is tested, while existing equivalent branches are not verified for the same return value, side effect, or error contract | REJECT |
+| An existing branch is treated as "preserved behavior" without verifying that it does not conflict with the contract introduced by the diff | REJECT |
+| Return / throw / catch / early return paths in the changed function are not enumerated, causing representative failure paths to be missed | REJECT |
+| Existing branches with the same responsibility have tests for return values, side effects, events, and error classification contracts | OK |
+
+## Parser and Configuration Boundary Tests
+
+At boundaries that read external files, configuration, YAML/JSON, or CLI input, testing only the ideal typed input is not sufficient.
+
+| Criteria | Verdict |
+|----------|---------|
+| Array-like fields are not tested with object/null/missing values | REJECT |
+| File/directory checks are not tested with an existing regular file, broken link, or permission error | REJECT |
+| Tests that can inherit existing user or machine configuration do not isolate with an empty config directory or temporary HOME | REJECT |
+| Syntactically valid but contract-invalid shapes are pinned to ignore, normalize, or explicit-error behavior | OK |
+
 ## 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.

package/builtins/en/workflow-categories.yaml

@@ -61,6 +61,7 @@ workflow_categories:
   🎵 TAKT Development:
     workflows:
       - takt-default
+      - takt-default-with-fc
       - takt-default-refresh-all
       - takt-default-refresh-fast
       - auto-improvement-loop

package/builtins/en/workflows/audit-architecture-backend.yaml

@@ -23,6 +23,8 @@ loop_monitors:
 
 steps:
   - name: plan
+    tags:
+      - plan
     persona: planner
     knowledge:
       - backend
@@ -40,6 +42,8 @@ steps:
         next: ABORT
 
   - name: audit
+    tags:
+      - review
     persona: architecture-reviewer
     policy: review
     knowledge:
@@ -60,6 +64,8 @@ steps:
         next: supervise
 
   - name: supervise
+    tags:
+      - review
     persona: supervisor
     policy: review
     knowledge:
@@ -75,6 +81,8 @@ steps:
         next: review
 
   - name: review
+    tags:
+      - review
     persona: architecture-reviewer
     policy: review
     knowledge:

package/builtins/en/workflows/audit-architecture-dual.yaml

@@ -23,6 +23,8 @@ loop_monitors:
 
 steps:
   - name: plan
+    tags:
+      - plan
     persona: planner
     knowledge:
       - frontend
@@ -41,6 +43,8 @@ steps:
         next: ABORT
 
   - name: audit
+    tags:
+      - review
     persona: architecture-reviewer
     policy: review
     knowledge:
@@ -62,6 +66,8 @@ steps:
         next: supervise
 
   - name: supervise
+    tags:
+      - review
     persona: supervisor
     policy: review
     knowledge:
@@ -78,6 +84,8 @@ steps:
         next: review
 
   - name: review
+    tags:
+      - review
     persona: architecture-reviewer
     policy: review
     knowledge:

package/builtins/en/workflows/audit-architecture-frontend.yaml

@@ -23,6 +23,8 @@ loop_monitors:
 
 steps:
   - name: plan
+    tags:
+      - plan
     persona: planner
     knowledge:
       - frontend
@@ -41,6 +43,8 @@ steps:
         next: ABORT
 
   - name: audit
+    tags:
+      - review
     persona: frontend-reviewer
     policy: review
     knowledge:
@@ -62,6 +66,8 @@ steps:
         next: supervise
 
   - name: supervise
+    tags:
+      - review
     persona: supervisor
     policy: review
     knowledge:
@@ -78,6 +84,8 @@ steps:
         next: review
 
   - name: review
+    tags:
+      - review
     persona: frontend-reviewer
     policy: review
     knowledge:

package/builtins/en/workflows/audit-architecture.yaml

@@ -23,6 +23,8 @@ loop_monitors:
 
 steps:
   - name: plan
+    tags:
+      - plan
     persona: planner
     knowledge: architecture
     instruction: architecture-audit-plan
@@ -38,6 +40,8 @@ steps:
         next: ABORT
 
   - name: audit
+    tags:
+      - review
     persona: architecture-reviewer
     policy: review
     knowledge: architecture
@@ -56,6 +60,8 @@ steps:
         next: supervise
 
   - name: supervise
+    tags:
+      - review
     persona: supervisor
     policy: review
     knowledge: architecture
@@ -69,6 +75,8 @@ steps:
         next: review
 
   - name: review
+    tags:
+      - review
     persona: architecture-reviewer
     policy: review
     knowledge: architecture

package/builtins/en/workflows/audit-e2e.yaml

@@ -29,6 +29,8 @@ loop_monitors:
 
 steps:
   - name: plan
+    tags:
+      - plan
     persona: test-planner
     policy: testing
     knowledge:
@@ -47,6 +49,8 @@ steps:
         next: ABORT
 
   - name: audit
+    tags:
+      - review
     edit: false
     persona: testing-reviewer
     policy:
@@ -69,6 +73,8 @@ steps:
         next: supervise
 
   - name: supervise
+    tags:
+      - review
     edit: false
     persona: supervisor
     policy: review
@@ -83,6 +89,8 @@ steps:
         next: review
 
   - name: review
+    tags:
+      - review
     edit: false
     persona: testing-reviewer
     policy:

package/builtins/en/workflows/audit-security.yaml

@@ -23,6 +23,8 @@ loop_monitors:
 
 steps:
   - name: plan
+    tags:
+      - plan
     persona: planner
     instruction: audit-security-plan
     edit: false
@@ -35,6 +37,8 @@ steps:
         next: audit
 
   - name: audit
+    tags:
+      - review
     persona: security-reviewer
     knowledge: security
     instruction: audit-security-team-leader
@@ -52,6 +56,8 @@ steps:
         next: supervise
 
   - name: supervise
+    tags:
+      - review
     persona: supervisor
     knowledge: security
     instruction: audit-security-supervise
@@ -63,6 +69,8 @@ steps:
         next: review
 
   - name: review
+    tags:
+      - review
     persona: security-reviewer
     knowledge: security
     instruction: audit-security-review

package/builtins/en/workflows/audit-unit.yaml

@@ -29,6 +29,8 @@ loop_monitors:
 
 steps:
   - name: plan
+    tags:
+      - plan
     edit: false
     persona: test-planner
     policy: testing
@@ -49,6 +51,8 @@ steps:
         next: ABORT
 
   - name: audit
+    tags:
+      - review
     edit: false
     persona: testing-reviewer
     policy:
@@ -71,6 +75,8 @@ steps:
         next: supervise
 
   - name: supervise
+    tags:
+      - review
     edit: false
     persona: supervisor
     policy: review
@@ -85,6 +91,8 @@ steps:
         next: review
 
   - name: review
+    tags:
+      - review
     edit: false
     persona: testing-reviewer
     policy:

package/builtins/en/workflows/auto-improvement-loop.yaml

@@ -51,6 +51,8 @@ steps:
         next: plan_fresh_improvement
 
   - name: plan_from_issue
+    tags:
+      - plan
     persona: supervisor
     knowledge:
       - architecture
@@ -136,6 +138,8 @@ steps:
         next: ABORT
 
   - name: plan_fresh_improvement
+    tags:
+      - plan
     persona: supervisor
     knowledge:
       - architecture
@@ -210,6 +214,8 @@ steps:
         next: ABORT
 
   - name: plan_from_existing_pr
+    tags:
+      - plan
     persona: supervisor
     knowledge:
       - architecture

package/builtins/en/workflows/backend-cqrs-mini.yaml

@@ -23,6 +23,8 @@ loop_monitors:
           next: supervise_fix
 steps:
   - name: plan
+    tags:
+      - plan
     edit: false
     persona: planner
     knowledge:
@@ -52,6 +54,8 @@ steps:
         - name: plan.md
           format: plan
   - name: implement
+    tags:
+      - coding
     edit: true
     persona: coder
     policy:
@@ -91,8 +95,12 @@ steps:
         - name: coder-decisions.md
           format: coder-decisions
   - name: reviewers
+    tags:
+      - review
     parallel:
       - name: ai-antipattern-review-2nd
+        tags:
+          - review
         edit: false
         persona: ai-antipattern-reviewer
         policy:
@@ -115,6 +123,8 @@ steps:
             - name: ai-antipattern-review.md
               format: ai-antipattern-review
       - name: supervise
+        tags:
+          - review
         edit: false
         persona: supervisor
         policy: review
@@ -153,8 +163,12 @@ steps:
       - condition: any("Requirements unmet, tests failing")
         next: supervise_fix
   - name: fix_both
+    tags:
+      - coding
     parallel:
       - name: ai-antipattern-fix-parallel
+        tags:
+          - coding
         edit: true
         persona: coder
         policy:
@@ -182,6 +196,8 @@ steps:
           - condition: Cannot proceed, insufficient info
         instruction: ai-antipattern-fix
       - name: supervise_fix_parallel
+        tags:
+          - coding
         edit: true
         persona: coder
         policy:
@@ -213,6 +229,8 @@ steps:
       - condition: any("No fix needed (verified target files/spec)", "Cannot proceed, insufficient info")
         next: implement
   - name: ai-antipattern-fix
+    tags:
+      - coding
     edit: true
     persona: coder
     policy:
@@ -245,6 +263,8 @@ steps:
         next: implement
     instruction: ai-antipattern-fix
   - name: supervise_fix
+    tags:
+      - coding
     edit: true
     persona: coder
     policy: