takt 0.48.0 → 0.50.0

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

@@ -135,6 +135,24 @@ Verification approach:
 3. If tests are added as part of the fix, verify they test "correct behavior after the fix" (not "the finding itself")
 4. For mid-PR specification changes, verify the tests cover the new behavior in the layer that owns it, not only the absence of the old specification
 
+## Superficial Fixes Through Test Doubles
+
+AI sometimes makes tests pass by loosening test doubles or ignoring arguments the production code uses instead of fixing the production contract. A passing test is evidence only when it exercised the same semantic contract as production.
+
+| Pattern | Example | Verdict |
+|---------|---------|---------|
+| A test double omits constraints or overrides always applied by the production helper | Permissions, capabilities, limits, or missing-value semantics differ from production | REJECT |
+| A mock ignores input that production uses for branching | Accepts `options` or `context` but never verifies them | REJECT |
+| A dependency with side-effect contracts is replaced by a return-only stub | Session updates, cache invalidation, or event emission are unobserved | REJECT |
+| The test only verifies that something was called, not the arguments or side effects | The test passes even when constraints are not propagated | REJECT |
+| The test double reproduces the observable production contract and assertions inspect arguments and side effects | Key options, missing values, and failure-state transitions are verified | OK |
+
+Verification approach:
+1. Inspect the replaced production function, builder, or adapter for return shape, missing values, side effects, and override propagation
+2. Check whether the test double collapses branch-relevant inputs into fixed values
+3. When the fix concerns state transitions or permission propagation, verify call arguments and side effects in addition to final state
+4. Check that test names and completion reports do not overclaim behavior the test double cannot prove
+
 ## Context Fitness Assessment
 
 Does the code fit this specific project?

package/builtins/en/facets/policies/existing-system-respect.md

@@ -12,6 +12,7 @@ For released or operational systems, make changes that are causally related to t
 | Respect existing structure | Do not change file placement, type names, public APIs, or responsibility boundaries without causal relationship to the request |
 | Preserve comments | Do not delete comments that explain intent, constraints, or calculation rationale |
 | Tests are contracts | Do not treat behavior asserted by existing tests as incidental |
+| Verify external contracts from primary evidence | Confirm behavior of external services, SDKs, and generated artifacts from official specs or actual types/schemas |
 | Causal improvement judgment | Perform style improvements and refactoring when causally related to the request. Do not mix improvements without causal relationship |
 | Protect unrelated code | Prioritize preserving existing behavior and structure that is not causally related to the request |
 
@@ -51,6 +52,18 @@ UI, accessibility, tests, logs, APIs, types, file placement, and comments can be
 | Comments | Change only when correcting inaccurate comments or when code makes them truly obsolete |
 | File placement | Change only when causally related to the request |
 
+## External Dependency Contracts
+
+Treat behavior of external services, SDKs, generated code, schemas, and CLIs as boundary contracts of the existing system. Do not infer one operation's error types, statuses, return values, idempotency, limits, or optionality from another operation without verification.
+
+| Criteria | Verdict |
+|----------|---------|
+| The concrete contract is verified from official specs, actual type definitions, generated schemas, or existing equivalent implementation | OK |
+| Error types, statuses, or return values from a different operation in the same service are generalized as "equivalent" and reused for an unverified operation | REJECT |
+| Compile success, mock success, or stub expectations alone are treated as proof of the external contract | REJECT |
+| Plans or implementation guidelines keep vague external-contract wording such as "equivalent" or "same as" | REJECT |
+| When the external contract cannot be verified, the unverified scope, risk, and verification method are recorded | OK |
+
 ## Test Changes
 
 Tests should distinguish existing contracts from new requirements, not merely follow the implementation.

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

@@ -13,9 +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 |
 
@@ -26,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) |
@@ -54,11 +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.
 
@@ -119,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**
@@ -255,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
@@ -290,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
@@ -303,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

@@ -14,6 +14,7 @@ Every behavior change requires a corresponding test, and every bug fix requires
 | 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 |
 | Verify negative contracts at observable units | Do not pass prohibition, rejection, non-inheritance, or unsupported cases by exact-string absence alone |
+| Mock contract fidelity | Keep external SDK/API mocks aligned with real contracts and do not freeze wrong assumptions in tests |
 
 ## Coverage Criteria
 
@@ -164,6 +165,19 @@ 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 |
 
+## 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. 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 |
+|----------|---------|
+| Mock values are chosen by checking official specs, SDK types, generated schemas, or existing equivalent tests | OK |
+| 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
 
 Test names describe expected behavior. Use the `should {expected behavior} when {condition}` pattern.

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