takt 0.47.0 → 0.49.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.
@@ -223,6 +234,7 @@ See the [Builtin Catalog](./docs/builtin-catalog.md) for all workflows and perso
 | Command | Description |
 |---------|-------------|
 | `takt` | Talk to AI, refine requirements, execute or queue tasks |
+| `takt exec` | Start instant Assistant/Worker/Review agent mode without writing workflow YAML |
 | `takt run` | Execute all pending tasks |
 | `takt list` | Manage task branches (merge, retry, requeue, force-fail, instruct, delete) |
 | `takt #N` | Execute GitHub Issue as task |
@@ -233,6 +245,18 @@ See the [Builtin Catalog](./docs/builtin-catalog.md) for all workflows and perso
 
 See the [CLI Reference](./docs/cli-reference.md) for all commands and options.
 
+### Instant exec mode
+
+`takt exec` starts TAKT's interactive task-entry mode. The Assistant agent clarifies the request, `/go` turns the conversation into a generated workflow, Worker agent(s) implement the task, Review agent(s) review the result, the Replanning agent asks the user for direction when needed, and loop detection prevents repeated unproductive cycles.
+
+Exec starts from the previous exec configuration, or the default configuration on first run. Pass a preset name to start from that preset. Use `/setup` during the conversation to edit agents, loop detection thresholds, presets, and referenced instruction/knowledge/policy facets. Builtin/default presets define the agent roles, facets, and loop thresholds only. Provider and model are resolved from normal TAKT configuration when exec mode starts, and the same resolved values are used for the Assistant dialogue, `/setup` display, and workflow generation. An exec config overrides provider/model only when it sets them explicitly. `effort` is emitted only when it is explicitly configured.
+
+Exec presets resolve in this order: project `.takt/exec/presets/` → global `$TAKT_CONFIG_DIR/exec/presets/` (default `~/.takt/exec/presets/`) → builtin `builtins/exec/presets/`. Changes made in `/setup` are saved to `$TAKT_CONFIG_DIR/exec.yaml` (default `~/.takt/exec.yaml`) for the next exec session. `/setup` can also save or delete project/global presets, and created facets are stored under `.takt/facets/` or `$TAKT_CONFIG_DIR/facets/` (default `~/.takt/facets/`).
+
+When `/go` runs, TAKT generates `.takt/exec/workflow.yaml` and executes it through the normal workflow engine. Inline text after `/go` is treated as an additional note. `/go` without prior conversation or inline task text does not generate the workflow. Use `/cancel` to exit without running.
+
+Normal agent steps, parallel sub-steps, and loop detection judges may set `session_key` to share or isolate persona sessions. System steps, workflow_call steps, and parallel parent steps cannot set `session_key`. TAKT builds the runtime key as `session_key` plus the resolved provider, so values must be non-empty strings that do not collide with other generated session routes.
+
 ## Configuration
 
 Minimal `~/.takt/config.yaml`:

package/builtins/en/facets/instructions/exec-loop-monitor.md

@@ -0,0 +1,15 @@
+# Exec Loop Monitor Instruction
+
+Review whether the repeated exec loop is productive.
+
+This loop has repeated {cycle_count} times.
+
+Review recent reports in chronological order and choose one of the following conditions.
+
+Small loop (execute ↔ review):
+- `Healthy (progress being made)` — findings are decreasing or meaningful progress is visible.
+- `Unproductive (same rework repeating)` — the same fixes repeat with no improvement.
+
+Large loop (replan → execute → review):
+- `Healthy (progress being made)` — findings are decreasing or meaningful progress is visible.
+- `Unproductive (no convergence)` — workers stay blocked or no convergence is visible.

package/builtins/en/facets/instructions/exec-replan.md

@@ -0,0 +1,5 @@
+# Exec Replan Instruction
+
+Discuss replanning with the user after a review requests needs_replan.
+
+Summarize the blocking issue from the review report, ask for the minimum needed clarification, and produce a revised plan when ready.

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

@@ -0,0 +1,10 @@
+# Exec Review Instruction
+
+Review the worker result in an independent session.
+
+Check the task requirement, worker reports, and actual code changes. Return one of these statuses:
+- approved: the task is complete.
+- needs_fix: small implementation fixes are required.
+- needs_replan: the approach needs user-level replanning.
+
+Include concise evidence and concrete next steps.

package/builtins/en/facets/instructions/exec-worker.md

@@ -0,0 +1,5 @@
+# Exec Worker Instruction
+
+Implement the requested task.
+
+Use the task instruction and reports in the Report Directory as primary context. If this is a fix pass, address review findings first. Keep changes inside the assigned scope, run the relevant checks, and report changed files and verification results.

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,33 @@ 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 |
+
+## Runtime Asset Consumption Boundaries
+
+TAKT runtime assets get their meaning from the entry point that consumes them, not only from their location or name. The same string can be an asset reference, session identifier, display name, or directly supplied body, and each is a separate contract.
+
+| Criteria | Judgment |
+|----------|----------|
+| Treating an entry that resolves asset references and an entry that only uses identifiers as equivalent | REJECT |
+| Adding a same-named facet and assuming it affects an entry that receives body content directly | REJECT |
+| Workflow-derived runtime assets and feature-local runtime assets share the same responsibility name | Warning |
+| Each entry point confirms which resolver or loader consumes which asset type before placing the asset | OK |
+| Shared body content is centralized behind the existing runtime asset loader | OK |
+
+### Reference Names and Identity Names
+
+Strings such as `persona`, `session_key`, and `name` mean different things depending on whether they are reference names or identity names. A reference name causes the corresponding resolver to load an asset. An identity name is a key for sessions, logs, state, or display, and a same-named file is not used unless that entry reads it. When adding a new asset, trace the loader that reads it and the call site that consumes it.
+
 ## Facet Assembly
 
 The faceted-prompting module is independent from TAKT core.

package/builtins/en/facets/output-contracts/exec-review-result.md

@@ -0,0 +1,13 @@
+# Exec Review Result
+
+## Status
+
+approved | needs_fix | needs_replan
+
+## Evidence
+
+Concise evidence for the status.
+
+## Required Next Step
+
+Concrete next action, if any.

package/builtins/en/facets/personas/exec-assistant.md

@@ -0,0 +1,3 @@
+# Assistant Persona
+
+You are a TAKT assistant. Stay helpful, concise, and action-oriented.

package/builtins/en/facets/personas/exec-worker.md

@@ -0,0 +1,3 @@
+# Worker Persona
+
+You are a TAKT worker. Stay focused, precise, and self-contained.

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

@@ -1,19 +1,20 @@
 # 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 |
+| 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 |
 
 ## Change Boundary
 
@@ -22,21 +23,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 +46,23 @@ 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 |
+
+## 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
 
@@ -70,4 +84,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/review.md

@@ -13,6 +13,7 @@ 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 |
+| 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 |
@@ -57,6 +58,7 @@ REJECT without exception if any of the following apply.
 - 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
+- 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
 

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

@@ -13,6 +13,8 @@ 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 |
+| Mock contract fidelity | Keep external SDK/API mocks aligned with real contracts and do not freeze wrong assumptions in tests |
 
 ## Coverage Criteria
 
@@ -113,6 +115,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.
@@ -136,6 +165,18 @@ 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
+
+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.
+
+| 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 |
+| 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

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