takt 0.47.0 → 0.48.0

package/README.md

@@ -112,6 +112,15 @@ Optional:
 npm install -g takt
 ```
 
+With Nix flakes:
+
+```bash
+nix run github:nrslib/takt
+nix profile install github:nrslib/takt
+```
+
+The Nix package installs the TAKT CLI itself. External CLI providers, `git`, and `gh`/`glab` still need to be installed and available on `PATH` or configured separately as described in [Requirements](#requirements).
+
 ### Talk to AI and queue tasks
 
 ```
@@ -214,6 +223,8 @@ When the same workflow name exists in multiple locations, TAKT resolves in this
 | `backend` | Backend development workflow. |
 | `dual` | Combined frontend + backend workflow. |
 | `takt-default` | The workflow used to develop TAKT itself. Directly applicable to other CLI tool development. |
+| `frontend-maintenance` | Frontend production maintenance. Strict multi-phase review with loop monitors. |
+| `backend-maintenance` | Backend production maintenance. Strict multi-phase review with dual-supervisor sign-off. |
 | `*-mini` series | Lightweight variants of each workflow (`default-mini` / `frontend-mini` / `backend-mini` / `dual-mini`). Omits `write_tests`. |
 
 See the [Builtin Catalog](./docs/builtin-catalog.md) for all workflows and personas.

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

@@ -1,4 +1,4 @@
-Use reports in the Report Directory and fix reviewer findings with the minimum diff that preserves existing contracts.
+Use reports in the Report Directory and fix reviewer findings within the causally related scope while preserving existing contracts.
 
 **Fix principles:**
 - When a finding includes a "suggested fix", follow it rather than inventing your own workaround

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

@@ -1,4 +1,4 @@
-Implement according to the plan with the minimum diff while preserving existing contracts.
+Implement according to the plan within the causally related scope 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.
 
@@ -14,7 +14,7 @@ Use reports in the Report Directory as the primary source of truth. If additiona
 - 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
+- Do not make structural changes that are not causally related to the request
 - When a specification change removes an old design, do not leave code or tests that only verify the absence of the old specification
 - After implementation, inspect the full diff and revert unnecessary changes
 

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

@@ -1,4 +1,4 @@
-Analyze the task as maintenance work for an existing frontend feature and produce a minimum-diff implementation plan that includes necessary design decisions.
+Analyze the task as maintenance work for an existing feature and produce a causal-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.
 
@@ -29,7 +29,7 @@ For small tasks, omit the design section. In maintenance work, do not omit exist
    - 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
+   - Where the request is not causally related, keep the existing structure 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
@@ -48,4 +48,4 @@ For small tasks, omit the design section. In maintenance work, do not omit exist
 ## Existing Contracts
 - {Existing contracts to preserve}
 ## Implementation Plan
-- {Minimum-diff plan}
+- {Causal-diff plan}

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

@@ -8,7 +8,9 @@ Procedure:
 5. If the diff adds or changes a shared helper, normalizer, builder, or adapter, verify that existing equivalent branches apply the same contract
 6. If types, schemas, validators, or resolvers changed, verify that the corresponding contracts are updated in the same change
 7. For values resolved or composed across multiple layers, trace the path from the real entry point through validation, not only standalone normalization
-8. For diffs involving side effects or state changes, trace entry, normal completion, early exit, exception, and cleanup paths
-9. Include only issues caused by the current diff that the user should fix
-10. For each finding, include location, impact, and fix direction
-11. Do not report unsupported speculation, preference-only changes, or unrelated pre-existing issues
+8. If a non-execution entry displays, validates, or explains the same value, compare whether it resolves through the same normalized input, override order, and resolver as the primary execution path
+9. When tests exist, verify that they cover the original requirement's branch conditions such as unset, set, invalid value, override, inherited, non-inherited, and unsupported target, not only value presence
+10. For diffs involving side effects or state changes, trace entry, normal completion, early exit, exception, and cleanup paths
+11. Include only issues caused by the current diff that the user should fix
+12. For each finding, include location, impact, and fix direction
+13. Do not report unsupported speculation, preference-only changes, or unrelated pre-existing issues

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

@@ -11,4 +11,9 @@ Procedure:
 2. If an external contract exists and input locations (root body / query / path) are not verified, treat it as a coverage gap by default
 3. For changes involving side effects or state transitions, check whether representative failure paths are tested, not just the happy path
 4. For changes that standardize a contract through consolidation or abstraction, check that contract tests cover existing equivalent branches as well as the new shared path
-5. Do not treat mock-substituted verification as proof that the real integration was verified
+5. For changes to config values, runtime-selected capabilities, backends, options, or permissions, verify that tests cover the original requirement's branch conditions such as unset, set, override, inherited, and non-inherited, not merely value presence
+6. For changes where a non-execution entry displays, validates, or explains the same value, verify that tests check displayed values against the resolution input used during execution
+7. Do not treat mock-substituted verification as proof that the real integration was verified
+8. For prohibition, rejection, non-inheritance, unsupported targets, and isolation, verify that tests extract observable units and check each forbidden value instead of relying on exact-string absence alone
+9. For new configuration boundaries, check normalization inputs such as empty strings, whitespace-only strings, empty arrays, and case variants when relevant
+10. Verify that E2E timeout, cleanup, and forced-termination handling follows existing same-kind test conventions

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

@@ -218,6 +218,8 @@ Separate read and write entrypoints. Read-side query boundaries have no side eff
 | Read-oriented class or method names hide side effects | REJECT |
 | Simple read API calls a query boundary and converts to response DTO | OK |
 | Simple state-changing API resolves structural validation and authorization boundary, then dispatches one command | OK |
+| Read-side coordinator for Controllers handles authorization boundaries, multiple Read Models, pagination, etc. | Express as ApplicationService or ReadService |
+| Sender or coordinating component named QueryService is placed near QueryHandlers | Warning. Easy to confuse with the query handling side |
 | Controller contains multiple Read Model lookups, external integration, multiple commands, or result waiting | REJECT. Separate into UseCase layer |
 | UseCase only delegates to another service or command dispatch without domain coordination | Consider deleting |
 

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

@@ -243,6 +243,18 @@ Event distribution uses PubSub (via message broker) to deliver events to all ins
 | Command and Query responsibilities mixed in the same service | REJECT. Separate responsibility and naming |
 | Query side checks existence or scope and caller dispatches command | OK |
 
+### QueryHandler and ApplicationService Naming
+
+In CQRS, the component that receives a query is the QueryHandler, and the entrypoint for dispatching queries is the QueryGateway / QueryBus. A facade called by Controllers for read use cases should be named ApplicationService or ReadService so it is not confused with a QueryHandler.
+
+| Criteria | Judgment |
+|----------|----------|
+| Receives a Query, reads the Read Model, and returns a query result type | QueryHandler |
+| Coordinates multiple Queries, authorization boundaries, pagination, or DTO assembly for Controllers | ApplicationService or ReadService |
+| Class that only dispatches queries or coordinates reads is named QueryService | Warning. Easy to confuse with QueryHandler |
+| QueryHandler knows HTTP requests/responses or Controller-specific error translation | REJECT |
+| Simple read wrapper with no additional decision-making | Consider deleting. Controller may call QueryGateway directly |
+
 Types between layers:
 - `application/query/` - Query result types (e.g., `OrderDetail`)
 - `adapter/protocol/` - REST response types (e.g., `OrderDetailResponse`)

package/builtins/en/facets/knowledge/e2e-testing.md

@@ -28,6 +28,18 @@ E2E tests observe behavior visible to the user. Checking configuration values, l
 | Only configuration or internal state is checked, with no user-visible result | REJECT |
 | Only real external-environment verification exists, with no deterministic test for the main boundary | Warning or REJECT |
 
+## Observing Negative Contracts
+
+When E2E tests verify permissions, runtime-selected capabilities, backends, options, configuration, rejection, or isolation, a string-level negation across the whole output is weak evidence.
+Extract the relevant line, event, record, field, or call argument, then check each forbidden value so order, case, whitespace, delimiters, or partial leaks cannot be missed.
+
+| Criteria | Judgment |
+|----------|----------|
+| Treating rejection, non-inheritance, or isolation as verified only because one exact sentence is absent | REJECT |
+| Checking only the displayed allowed value without proving forbidden values do not reach final processing | REJECT |
+| Extracting observable units and checking forbidden, rejected, or non-inherited values per value | OK |
+| Comparing allowed vs rejected and inherited vs non-inherited cases in the same scenario family | OK |
+
 ## UX Route Identification
 
 E2E test completeness depends on thorough UX route identification. Identify entry points from code, not documentation.
@@ -77,6 +89,7 @@ E2E tests are prone to non-deterministic failures.
 | Process leaks | Set timeouts and force-kill |
 | Environment dependency | Explicitly set up prerequisites for test execution |
 | Execution order dependency | Initialize state so each test runs independently |
+| Timeout/cleanup diverges from existing convention | Follow existing same-kind E2E conventions |
 
 ```typescript
 // NG - fixed sleep for timing

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

@@ -40,9 +40,9 @@ In maintenance work, general design improvements and framework style are not alw
 
 | Situation | Judgment |
 |-----------|----------|
-| Component extraction would look cleaner but is unnecessary for this fix | Do not change |
+| Component extraction would look cleaner but is not causally related to the request | 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 cannot satisfy the request | Change within the causally related scope |
 | The existing structure is the cause of the bug | Change it with reason and impact scope documented |
 
 ## Meaning of Comments and Tests

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

@@ -77,6 +77,17 @@ Models resolve through 5-level priority. Higher takes precedence.
 4. config.yaml (when resolved provider matches)
 5. Provider default
 
+## Auxiliary Entry Contracts
+
+In TAKT, workflow runtime is not the only user-visible contract entry. Preview, doctor, workflow summary, validation, and report paths are also contract entries. Auxiliary entries that display or validate config values, providers, models, tools, permissions, or output contracts should use the same normalized input, resolver, and override order as runtime.
+
+| Criteria | Judgment |
+|----------|----------|
+| Runtime and preview resolve provider, model, tool, or permission from different inputs | REJECT |
+| Preview only displays a value without verifying the same override conditions as runtime | REJECT |
+| Doctor or validation accepts config that fails at runtime due to different conditions | Warning |
+| Runtime and auxiliary entries share the same normalized input or resolver | OK |
+
 ## Facet Assembly
 
 The faceted-prompting module is independent from TAKT core.

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

@@ -1,19 +1,19 @@
 # Existing System Respect Policy
 
-For released or operational systems, make only the minimum changes required by the request and avoid changing existing contracts unnecessarily.
+For released or operational systems, make changes that are causally related to the request and do not change existing contracts that lack that relationship.
 
 ## Principles
 
 | Principle | Criteria |
 |-----------|----------|
 | Existing contracts first | Preserve contracts relied on by users, tests, and operations |
-| Minimum diff | Keep only changes required to satisfy the request |
+| Causal diff | Make changes causally related to the request; exclude changes without causal relationship |
 | Necessity over proximity | Do not use nearby code as a reason to change it |
-| Respect existing structure | Do not change file placement, type names, public APIs, or responsibility boundaries without explicit need |
+| 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 |
-| Separate improvements | Style or cleanup improvements must be directly required by the task |
-| Maintenance constraints first | Prefer preserving existing behavior and structure over general quality improvements |
+| 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 |
 
 ## Change Boundary
 
@@ -22,21 +22,22 @@ For released or operational systems, make only the minimum changes required by t
 | Change required to satisfy the request | OK |
 | Call-site update required to wire a necessary change | OK |
 | Local fix required to prevent side effects of a necessary change | OK |
+| Structural change or refactoring causally related to the request | OK |
 | Cleanup justified only because the file was touched | REJECT |
-| Moving files, renaming types, or changing public APIs without explicit need | REJECT |
-| Mixing framework-style improvements into the task | REJECT |
-| Including improvements that can be handled in another PR | REJECT |
+| Moving files, renaming types, or changing public APIs without causal relationship to the request | REJECT |
+| Mixing framework-style improvements not causally related to the request | REJECT |
+| Including improvements not causally related to the request | REJECT |
 
 ## Priority Against Other Policies
 
-In existing-system maintenance, apply general quality policies such as coding, frontend, design-fidelity, and testing only within the scope required by the request.
+In existing-system maintenance, apply general quality policies such as coding, frontend, design-fidelity, and testing within the scope causally related to the request.
 
 | Conflict | Verdict |
 |----------|---------|
-| General quality criteria suggest an improvement, but the request does not require it | Do not change |
-| Existing structure is imperfect, but can satisfy this request | Preserve existing structure |
+| General quality criteria suggest an improvement, but it is not causally related to the request | Do not change |
+| Existing structure is imperfect, but not causally related to the request | Preserve existing structure |
 | Satisfying a quality criterion requires changing an existing contract | Requires an explicit user request or plan-level rationale |
-| A minimal structural change is required for a bug fix | Make it with reason and impact scope documented |
+| Structural change causally related to the request | Make it with reason and impact scope documented |
 
 ## Observable Contracts
 
@@ -44,11 +45,11 @@ UI, accessibility, tests, logs, APIs, types, file placement, and comments can be
 
 | Contract | Change condition |
 |----------|------------------|
-| UI copy, accessible names, role/state | Change only when directly required by the request |
-| Hook return values, Props type names, public function names | Change only when caller updates are required to satisfy the request |
+| UI copy, accessible names, role/state | Change only when causally related to the request |
+| Hook return values, Props type names, public function names | Change only when required for caller updates causally related to the request |
 | Test expectations | Change only when the requested behavior changes |
 | Comments | Change only when correcting inaccurate comments or when code makes them truly obsolete |
-| File placement | Change only when the existing structure cannot satisfy the request |
+| File placement | Change only when causally related to the request |
 
 ## Test Changes
 
@@ -70,4 +71,4 @@ Before completion, classify the full diff as required changes, related changes,
 |----------------|----------|
 | Required change | The request fails without it |
 | Related change | Needed to connect, verify, or keep a required change consistent |
-| Unnecessary change | Justified only by readability, style, cleanup, or future extensibility |
+| Unnecessary change | Not causally related to the request; justified only by readability, style, cleanup, or future extensibility |

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

@@ -13,6 +13,7 @@ Every behavior change requires a corresponding test, and every bug fix requires
 | Type safety | Code must pass the build (type check) |
 | Reproducibility | Do not depend on time or randomness. Same result every run |
 | Do not freeze non-executable assets | Do not make prose or section structure that does not define runtime behavior a CI failure condition |
+| Verify negative contracts at observable units | Do not pass prohibition, rejection, non-inheritance, or unsupported cases by exact-string absence alone |
 
 ## Coverage Criteria
 
@@ -113,6 +114,33 @@ When a change standardizes a contract through a shared helper, normalizer, build
 | 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 |
 
+## Contract Test Sufficiency
+
+When adding or changing a config value, runtime-selected capability, backend, option, permission, or output contract, tests must prove the branch conditions that change the contract, not merely that a value exists.
+
+| Criteria | Verdict |
+|----------|---------|
+| Only the happy path for a new option is verified | Warning |
+| Requirement-relevant branches among unset, set, invalid value, inherited, non-inherited, override, and unsupported target are not verified | REJECT |
+| A user-facing display or validation entry is not verified to follow the same contract as the primary execution path | REJECT |
+| A test only checks displayed values without verifying they match the resolution input used during execution | REJECT |
+| Absence is verified only by exact string matching, missing order, case, whitespace, or partial-leak differences | REJECT |
+| Boundary values that may be normalized at configuration boundaries, such as empty strings, whitespace-only strings, empty arrays, or case variants, are not tested | Warning. REJECT when this is a primary contract branch |
+| The path from entry point to final call verifies happy, rejection, and non-inheritance cases | OK |
+
+## Testing Negative, Non-Inheritance, and Rejection Contracts
+
+Tests for prohibition, rejection, non-inheritance, unsupported targets, and isolation must not rely only on a specific string being absent from the whole output.
+Extract observable units such as output lines, records, fields, or call arguments, then verify each forbidden value cannot leak through order, case, whitespace, delimiter, or partial-match differences.
+
+| Criteria | Verdict |
+|----------|---------|
+| Exact-string absence alone is used to conclude that a forbidden or non-inherited value was not used | REJECT |
+| Only allowed-value presence is checked, without proving rejected, forbidden, or non-inherited values do not reach final processing | REJECT |
+| Observable units such as output lines, events, records, fields, or call arguments are extracted and checked per forbidden value | OK |
+| Allowed vs rejected and inherited vs non-inherited cases are tested as pairs | OK |
+| A new E2E test does not follow existing same-kind conventions for timeout, cleanup, and forced termination | Warning. REJECT when it can cause process leaks or flakes |
+
 ## 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.

package/builtins/en/workflow-categories.yaml

@@ -24,6 +24,7 @@ workflow_categories:
     workflows:
       - backend
       - backend-mini
+      - backend-maintenance
       - backend-cqrs
       - backend-cqrs-mini
   🔧 Dual: