takt 0.49.0 → 0.50.0

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

@@ -13,10 +13,12 @@ Define the shared judgment criteria and behavioral principles for all reviewers.
 | 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 |
+| Semantic contract | For meaningful fields such as IDs, source, trace, and issue/PR numbers, verify not only the storage shape but also the meaning interpreted downstream |
 | External contract verification | Verify semantic contracts of external services, SDKs, and generated artifacts from primary evidence or actual types |
 | 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 |
+| Concern handling | Any concern recognized in the prose must either become a finding or be explicitly classified with evidence as non-finding |
 | 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 |
 
@@ -27,6 +29,7 @@ Define the shared judgment criteria and behavioral principles for all reviewers.
 | Problem introduced by this change | Blocking | REJECT |
 | Code made unused by this change (arguments, imports, variables, functions) | Blocking | REJECT (change-induced problem) |
 | Existing problem in changed or directly related code | Blocking | REJECT (Boy Scout rule) |
+| Existing ambiguous or incorrect contract exposed through a new public entry, adapter, or tool | Blocking | REJECT (existing behavior is not an exemption) |
 | Structural problem directly affecting correctness of the change | Blocking | REJECT if within scope |
 | Problem in an unchanged file | Non-blocking | Record only (informational) |
 | Existing problem that merely shares a changed file but does not directly affect correctness of the change | Non-blocking | Record only (informational) |
@@ -55,12 +58,15 @@ REJECT without exception if any of the following apply.
 - Replaced code/exports surviving after refactoring
 - Missing cross-validation of related fields (invariants of semantically coupled config values left unverified)
 - Missing caller, producer, consumer, validator, test data, or derived-entry updates after a contract change
+- Meaningful fields such as IDs, source, trace, or issue/PR numbers are added, forwarded, or persisted while only the storage shape is checked, without verifying downstream interpretation or confusion with existing fields
 - 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
+- A new public entry, adapter, or tool republishes an existing ambiguous or incorrect contract as an external contract
 - 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
 - Operation-specific error types, statuses, return values, or idempotency of an external service, SDK, or generated artifact are not verified, and another operation's contract or mock success is used instead
 - Missing, duplicated, or incorrectly ordered effects in side-effect or state-change paths
 - Sensitive data exposed in logs, error responses, or test output
+- Review prose recognizes a contract mismatch, side effect, boundary value, or unverified risk but does not turn it into a finding and does not classify it as a non-finding with evidence
 
 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.
 
@@ -121,6 +127,11 @@ If tool output is unreadable, re-read using a reliable method before making any
 
 Every issue raised must include the following.
 
+When the same kind of problem appears in multiple locations, report one representative finding and list the other locations inline as `also: src/store.ts:L232, src/projection.ts:L243`. Do not spend rows enumerating the same kind of issue; use the remaining attention to hunt different kinds of problems. Do not merge, however, in these cases:
+
+- Findings already tracked under separate `finding_id`s (do not break the tracking unit)
+- When a Finding Contract is in use (report every observed problem as an individual raw finding; deduplication is the responsibility of the findings-manager and the ledger)
+
 - **Which file and line number**
 - **What the problem is**
 - **How to fix it**
@@ -257,6 +268,8 @@ Do not tolerate problems just because existing code does the same. If existing c
 - Issues detected in changed code or in areas directly affecting correctness, contracts, or wiring of the change are blocking (REJECT targets), even if the code existed before the change
 - Only issues not directly related to the change may be classified as "existing problems" or "non-blocking"
 - "The code itself existed before" is not a valid reason for non-blocking when the issue is in changed or directly related code
+- "Same as existing behavior" is not an approval reason when a new public entry, adapter, or tool exposes that contract
+- When a concern mentioned in prose is not made a finding, classify it as `false_positive` / `overreach` / `out_of_scope` / `no_issue_after_verification` and provide evidence
 - If even one issue exists, REJECT. "APPROVE with warnings" or "APPROVE with suggestions" is prohibited
 
 ## Basic Review Procedure
@@ -292,6 +305,7 @@ When the diff adds or changes a contract such as a config value, state, conditio
 - 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
+- Verify that values normalized or validated at a boundary propagate as the same normalized value through persistence, execution, external calls, and event emission. Treat reuse of pre-normalized values in later stages as a contract inconsistency
 - 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
@@ -305,6 +319,7 @@ When a change involves side effects or state changes such as external calls, con
 - Trace entry, normal completion, early return, exception, retry, interruption, and cleanup paths
 - Verify that anything acquired, started, registered, or applied is handled exactly as required on the corresponding paths
 - Verify that the same side effect is not executed more than once, and that required effects are not skipped on failure paths
+- Verify that no new side effect, such as an external notification, confirmation request, tool call, or persistence write, is started after interruption, cancellation, timeout, or any other condition has made continuation invalid
 - For changes that affect shared state or downstream execution, verify that partial failure does not leave state that breaks the next run
 - If these checks have not been performed, do not treat the behavior as functionally verified
 

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

@@ -165,9 +165,9 @@ Test data should explicitly generate the minimum facts needed by each test. Muta
 | Factories provide defaults and each test overrides only relevant fields | OK |
 | Contract changes update fixtures, mocks, and snapshots in the same change | OK |
 
-## External Contract Mocks
+## Contract Mocks and Test Doubles
 
-When mocking an external SDK, external API, generated client, or CLI, align mocked exception types, statuses, return values, missing values, partial successes, and idempotency with the real contract. Type compatibility alone does not verify the semantic contract.
+When mocking an external SDK, external API, generated client, or CLI, align mocked exception types, statuses, return values, missing values, partial successes, and idempotency with the real contract. When using test doubles for internal builders, runners, or adapters, also match production semantics for permissions, capabilities, overrides, missing values, and side effects. Type compatibility alone does not verify the semantic contract.
 
 | Criteria | Verdict |
 |----------|---------|
@@ -175,6 +175,7 @@ When mocking an external SDK, external API, generated client, or CLI, align mock
 | The mock throws the exception or return value expected by the implementation, and test success is used as proof of the external contract | REJECT |
 | Error types or response shapes from a different operation in the same service are reused | REJECT |
 | The mock is type-safe but operation-specific semantic contracts, such as existing-resource behavior, partial success, or missing detection, are not verified | REJECT |
+| Internal test double drops constraints, overrides, or side effects that production always passes | REJECT |
 | When real integration is stubbed, the report separates what the mock verifies from the unverified real-integration scope | OK |
 
 ### Naming

package/builtins/en/workflow-categories.yaml

@@ -4,6 +4,7 @@ workflow_categories:
       - default
       - default-mini
       - default-high
+      - cli
       - frontend
       - backend
       - dual
@@ -20,6 +21,7 @@ workflow_categories:
       - frontend
       - frontend-mini
       - frontend-maintenance
+      - frontend-for-local-llm
   ⚙️ Backend:
     workflows:
       - backend
@@ -27,12 +29,15 @@ workflow_categories:
       - backend-maintenance
       - backend-cqrs
       - backend-cqrs-mini
+      - backend-for-local-llm
+      - backend-cqrs-for-local-llm
   🔧 Dual:
     workflows:
       - dual
       - dual-mini
       - dual-cqrs
       - dual-cqrs-mini
+      - dual-for-local-llm
   🏗️ Infrastructure:
     workflows:
       - terraform
@@ -62,12 +67,19 @@ workflow_categories:
   🎵 TAKT Development:
     workflows:
       - takt-default
-      - takt-default-with-fc
       - takt-default-refresh-all
       - takt-default-refresh-fast
       - auto-improvement-loop
       - review-takt-default
       - review-fix-takt-default
+      - takt-default-for-local-llm
+  🖥️ Local LLM:
+    workflows:
+      - takt-default-for-local-llm
+      - frontend-for-local-llm
+      - backend-for-local-llm
+      - backend-cqrs-for-local-llm
+      - dual-for-local-llm
   Others:
     workflows:
       - research

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

@@ -66,6 +66,7 @@ steps:
   - name: supervise
     tags:
       - review
+      - supervise
     persona: supervisor
     policy: review
     knowledge:

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

@@ -68,6 +68,7 @@ steps:
   - name: supervise
     tags:
       - review
+      - supervise
     persona: supervisor
     policy: review
     knowledge:

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

@@ -68,6 +68,7 @@ steps:
   - name: supervise
     tags:
       - review
+      - supervise
     persona: supervisor
     policy: review
     knowledge:

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

@@ -62,6 +62,7 @@ steps:
   - name: supervise
     tags:
       - review
+      - supervise
     persona: supervisor
     policy: review
     knowledge: architecture

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

@@ -75,6 +75,7 @@ steps:
   - name: supervise
     tags:
       - review
+      - supervise
     edit: false
     persona: supervisor
     policy: review

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

@@ -58,6 +58,7 @@ steps:
   - name: supervise
     tags:
       - review
+      - supervise
     persona: supervisor
     knowledge: security
     instruction: audit-security-supervise

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

@@ -77,6 +77,7 @@ steps:
   - name: supervise
     tags:
       - review
+      - supervise
     edit: false
     persona: supervisor
     policy: review

package/builtins/en/workflows/backend-cqrs-for-local-llm.yaml

@@ -0,0 +1,288 @@
+name: backend-cqrs-for-local-llm
+description: CQRS+ES backend development workflow for local LLMs. Four parallel specialist reviewers plus the Finding Contract build discipline for weak models structurally
+finding_contract:
+  ledger_path: .takt/findings/backend-cqrs-for-local-llm.json
+  raw_findings_path: .takt/findings/backend-cqrs-for-local-llm/raw
+  manager:
+    persona: findings-manager
+    instruction: findings-manager
+    output_contract: findings-manager
+max_steps: 50
+initial_step: plan
+workflow_config:
+  provider_options:
+    codex:
+      network_access: true
+    opencode:
+      network_access: true
+
+loop_monitors:
+  - cycle:
+      - plan
+      - write_tests
+      - implement
+      - reviewers
+      - fix
+    threshold: 2
+    judge:
+      persona: supervisor
+      instruction: loop-monitor-fix-replan
+      rules:
+        - condition: The latest fix ended with fixes complete (not a dead end)
+          next: reviewers
+        - condition: Healthy (each replan moves the blocker toward resolution)
+          next: plan
+        - condition: Unproductive (the same dead end repeats)
+          next: ABORT
+  - cycle:
+      - reviewers
+      - fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction: loop-monitor-reviewers-fix
+      rules:
+        - condition: converging (findings decreasing, fixes applied)
+          next: reviewers
+        - condition: unproductive (the same findings repeat), but replanning could break the deadlock
+          next: plan
+        - condition: unproductive (the same findings repeat), and replanning is unlikely to help
+          next: ABORT
+  - cycle:
+      - reviewers
+      - final-gate
+      - fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction: loop-monitor-reviewers-fix
+      rules:
+        - condition: converging (findings decreasing, fixes applied)
+          next: reviewers
+        - condition: unproductive (the same findings repeat), but replanning could break the deadlock
+          next: plan
+        - condition: unproductive (the same findings repeat), and replanning is unlikely to help
+          next: ABORT
+
+steps:
+  - name: plan
+    tags:
+      - plan
+    edit: false
+    persona: planner
+    knowledge:
+      - backend
+      - cqrs-es
+      - architecture
+    provider_options:
+      extends: review-readonly
+    instruction: plan
+    rules:
+      - condition: Task analysis and planning is complete
+        next: write_tests
+      - condition: The user is asking a question (not an implementation task)
+        next: COMPLETE
+      - condition: Requirements are unclear and planning cannot proceed
+        next: ABORT
+    output_contracts:
+      report:
+        - name: plan.md
+          format: plan
+
+  - name: write_tests
+    tags:
+      - coding
+      - test-planning
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    knowledge:
+      - backend
+      - cqrs-es
+      - architecture
+      - unit-testing
+      - e2e-testing
+      - implementation-semantics
+    provider_options:
+      extends: edit
+    required_permission_mode: edit
+    instruction: write-tests-first
+    rules:
+      - condition: Test creation is complete
+        next: implement
+      - condition: Skipping test creation as target is not yet implemented
+        next: implement
+      - condition: Cannot proceed with test creation
+        next: plan
+      - condition: User input required for clarification
+        next: write_tests
+        requires_user_input: true
+        interactive_only: true
+    output_contracts:
+      report:
+        - name: test-report.md
+          format: test-report
+
+  - name: implement
+    tags:
+      - coding
+    edit: true
+    persona: coder
+    policy:
+      - coding
+    knowledge:
+      - backend
+      - cqrs-es
+      - architecture
+      - implementation-semantics
+    provider_options:
+      extends: edit
+    required_permission_mode: edit
+    instruction: implement
+    rules:
+      - condition: Implementation is complete
+        next: reviewers
+      - condition: Cannot proceed with implementation (environment issue or missing information)
+        next: ABORT
+
+  - name: reviewers
+    tags:
+      - review
+    parallel:
+      - name: cqrs-es-review
+        tags:
+          - review
+        edit: false
+        persona: cqrs-es-reviewer
+        policy:
+          - review
+        knowledge:
+          - cqrs-es
+        instruction: review-cqrs-es
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        output_contracts:
+          report:
+            - name: cqrs-es-review.md
+              format: cqrs-es-review-finding-contract
+
+      - name: ai-antipattern-review
+        tags:
+          - review
+        edit: false
+        persona: ai-antipattern-reviewer
+        policy:
+          - review
+          - ai-antipattern
+        pass_previous_response: false
+        instruction: ai-antipattern-review
+        rules:
+          - condition: No AI-specific issues
+          - condition: AI-specific issues found
+        output_contracts:
+          report:
+            - name: ai-antipattern-review.md
+              format: ai-antipattern-review-finding-contract
+
+      - name: coding-review
+        tags:
+          - review
+        edit: false
+        persona: coding-reviewer
+        policy:
+          - review
+          - coding
+        pass_previous_response: false
+        instruction: review-coding
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        output_contracts:
+          report:
+            - name: coding-review.md
+              format: coding-review-finding-contract
+
+      - name: implementation-semantics-review
+        tags:
+          - review
+        edit: false
+        persona: implementation-semantics-reviewer
+        policy:
+          - review
+        knowledge:
+          - implementation-semantics
+        pass_previous_response: false
+        instruction: review-implementation-semantics
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        output_contracts:
+          report:
+            - name: implementation-semantics-review.md
+              format: implementation-semantics-review-finding-contract
+    rules:
+      - condition: all("approved", "No AI-specific issues", "approved", "approved") && when(findings.open.count == 0 && findings.conflicts.count == 0)
+        next: final-gate
+      - condition: any("needs_fix", "AI-specific issues found", "needs_fix", "needs_fix") && when(findings.conflicts.count == 0)
+        next: fix
+      - condition: when(findings.conflicts.count == 0 && findings.open.count > 0)
+        next: fix
+      - condition: ai("There are unadjudicated findings.conflicts. Choose fix only when a concrete code change by the coder can resolve them. Do not choose it for reviewer disagreements or anything requiring human judgment.")
+        next: fix
+      - condition: when(findings.conflicts.count > 0)
+        next: ABORT
+
+  - name: final-gate
+    tags:
+      - review
+      - final-gate
+    edit: false
+    persona: merge-readiness-reviewer
+    policy: review
+    pass_previous_response: false
+    instruction: review-merge-readiness
+    output_contracts:
+      report:
+        - name: merge-readiness-review.md
+          format: merge-readiness-review-finding-contract
+    rules:
+      - condition: approved && when(findings.open.count == 0 && findings.conflicts.count == 0)
+        next: COMPLETE
+      - condition: needs_fix && when(findings.conflicts.count == 0)
+        next: fix
+      - condition: when(findings.conflicts.count == 0 && findings.open.count > 0)
+        next: fix
+      - condition: ai("There are unadjudicated findings.conflicts. Choose fix only when a concrete code change by the coder can resolve them. Do not choose it for reviewer disagreements or anything requiring human judgment.")
+        next: fix
+      - condition: when(findings.conflicts.count > 0)
+        next: ABORT
+
+  - name: fix
+    tags:
+      - coding
+    edit: true
+    persona: coder
+    policy:
+      - coding
+    knowledge:
+      - backend
+      - cqrs-es
+      - architecture
+      - implementation-semantics
+    provider_options:
+      extends: edit
+    required_permission_mode: edit
+    instruction: fix
+    rules:
+      - condition: Fixes are complete
+        next: reviewers
+      - condition: Cannot proceed with fixes, or human judgment is required
+        next: plan
+        appendix: |
+          The fix attempt is stuck. Read the rejection details and the stated
+          blocker, decompose the work again, and replan. Declare planning
+          impossible only if human judgment is genuinely required, with the
+          reasons stated explicitly.

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

@@ -125,6 +125,7 @@ steps:
       - name: supervise
         tags:
           - review
+          - supervise
         edit: false
         persona: supervisor
         policy: review

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

@@ -23,6 +23,8 @@ loop_monitors:
           next: reviewers_1
   - cycle:
       - reviewers_1
+      - reviewers_2
+      - final-gate
       - fix
     threshold: 3
     judge:
@@ -32,7 +34,7 @@ loop_monitors:
         - condition: converging (findings decreasing, fixes applied)
           next: reviewers_1
         - condition: unproductive (same findings repeating)
-          next: supervise
+          next: final-gate
 steps:
   - name: plan
     tags:
@@ -65,6 +67,7 @@ steps:
   - name: write_tests
     tags:
       - coding
+      - test-planning
     edit: true
     persona: coder
     policy:
@@ -361,29 +364,6 @@ steps:
           report:
             - name: qa-review.md
               format: qa-review
-      - name: pure-review
-        tags:
-          - review
-        edit: false
-        persona: pure-reviewer
-        policy: review
-        provider_options:
-          claude:
-            allowed_tools:
-              - Read
-              - Glob
-              - Grep
-              - Bash
-              - WebSearch
-              - WebFetch
-        rules:
-          - condition: approved
-          - condition: needs_fix
-        instruction: review-pure
-        output_contracts:
-          report:
-            - name: pure-review.md
-              format: pure-review
       - name: coding-review
         tags:
           - review
@@ -411,9 +391,32 @@ steps:
           - condition: needs_fix
     rules:
       - condition: all("approved")
-        next: supervise
+        next: final-gate
       - condition: any("needs_fix")
         next: fix
+  - name: final-gate
+    kind: workflow_call
+    call: merge-readiness-dual-final-gate
+    args:
+      merge_readiness_knowledge:
+        - backend
+        - cqrs-es
+        - security
+        - architecture
+      supervise_knowledge:
+        - backend
+        - cqrs-es
+        - security
+        - architecture
+    rules:
+      - condition: COMPLETE
+        next: COMPLETE
+      - condition: needs_fix
+        next: fix
+      - condition: need_replan
+        next: plan
+      - condition: ABORT
+        next: ABORT
   - name: fix
     tags:
       - coding
@@ -446,62 +449,3 @@ steps:
       - condition: Cannot proceed, insufficient info
         next: plan
     instruction: fix
-  - name: supervise
-    tags:
-      - review
-    edit: false
-    persona: dual-supervisor
-    policy: review
-    provider_options:
-      claude:
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - WebSearch
-          - WebFetch
-    instruction: supervise
-    pass_previous_response: false
-    rules:
-      - condition: All validations pass and ready to merge
-        next: COMPLETE
-      - condition: Issues detected during final review
-        next: fix_supervisor
-    output_contracts:
-      report:
-        - name: supervisor-validation.md
-          format: supervisor-validation
-        - name: summary.md
-          format: summary
-          use_judge: false
-  - name: fix_supervisor
-    tags:
-      - coding
-    edit: true
-    persona: coder
-    policy:
-      - coding
-      - testing
-    knowledge:
-      - backend
-      - cqrs-es
-      - security
-      - architecture
-    provider_options:
-      claude:
-        allowed_tools:
-          - Read
-          - Glob
-          - Grep
-          - Edit
-          - Write
-          - Bash
-          - WebSearch
-          - WebFetch
-    instruction: fix-supervisor
-    pass_previous_response: false
-    rules:
-      - condition: Supervisor's issues have been fixed
-        next: supervise
-      - condition: Unable to proceed with fixes
-        next: plan