takt 0.46.0 → 0.48.0

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

@@ -65,7 +65,7 @@ data class Order(
 
 ## API Layer Design (Controller)
 
-Keep Controllers thin. Their only job: receive request → delegate to UseCase → return response.
+Keep Controllers thin. Focus them on receiving requests, DTO conversion, resolving authentication/authorization boundaries, delegating to a UseCase or query boundary, and returning responses.
 
 ```kotlin
 // CORRECT - Thin Controller
@@ -208,6 +208,21 @@ fun confirm(confirmedBy: String): OrderConfirmedEvent {
 | Structural validation (@NotBlank, etc.) in domain | REJECT. Belongs in API layer |
 | UseCase-level validation inside Aggregate | REJECT. Read Model queries belong in UseCase layer |
 
+### Read and Write Entrypoints
+
+Separate read and write entrypoints. Read-side query boundaries have no side effects; writes are handled by commands or UseCases.
+
+| Criteria | Judgment |
+|----------|----------|
+| Query boundary saves, deletes, calls external services, or dispatches commands | REJECT |
+| 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 |
+
 ## Error Handling
 
 ### Exception Hierarchy Design
@@ -245,6 +260,17 @@ class OrderExceptionHandler {
 | Empty try-catch blocks | REJECT |
 | Controller swallowing exceptions and returning 200 | REJECT |
 
+### Exception Translation Scope
+
+Translate exceptions into HTTP status codes at an exception translation layer on the HTTP adapter boundary. Global translation should be limited to truly cross-cutting cases such as authentication, input validation, and common error shapes; API- or resource-specific mappings belong in a boundary scoped to that API.
+
+| Criteria | Judgment |
+|----------|----------|
+| Each endpoint maps exceptions to HTTP representation through the same try-catch or wrapper | REJECT. Move it to an exception translation layer at the HTTP adapter boundary |
+| API-specific exception mapping is added to a global handler | Scope is too broad. Keep it inside the target API boundary |
+| Authentication failures, input validation, and common error shapes shared by all APIs | OK. Handle at a global boundary |
+| HTTP representation mapping lives in the application or domain layer | REJECT. Keep it at the HTTP adapter boundary |
+
 ## Domain Model Design
 
 ### Immutable + require

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

@@ -167,6 +167,35 @@ Validation inside an Aggregate should be limited to facts reproducible by event
 
 Example: for an upload-completed command, the Aggregate decides whether the session owner matches the requester and whether the current state can be completed. The storage object key format and whether the key belongs to the current user/tenant are validated in the UseCase layer before sending the command.
 
+## UseCase Layer (Orchestration)
+
+UseCases sit between Controllers and command dispatch when orchestration is needed. They validate preconditions from Read Models across aggregates and perform required preparation before sending commands.
+
+```
+Controller → UseCase → CommandGateway → Aggregate
+                ↓
+          QueryGateway / Repository (Read Model lookup)
+```
+
+Cases where UseCase is needed:
+- Read Model checks from multiple aggregates before command dispatch
+- Multiple validations executed in sequence
+- Result consistency waiting after command dispatch
+- External integration or multiple command dispatches
+
+Cases where UseCase is unnecessary:
+- Simple operation completed by sending one command from Controller
+- Simple read that only queries the query side and converts to response
+- Operation that checks resource existence/scope and then sends one command
+
+| Criteria | Judgment |
+|----------|----------|
+| Controller directly references Repository for validation | Separate into UseCase layer |
+| UseCase depends on HTTP requests/responses | REJECT. UseCase must be protocol-independent |
+| UseCase directly modifies Aggregate internal state | REJECT. Use CommandGateway |
+| UseCase waits for results via Subscription Query | REJECT. Does not work in distributed environments. Use reactive polling |
+| UseCase only delegates to a query boundary or command dispatch | Consider deleting |
+
 ## Projection Design
 
 | Criteria | Judgment |
@@ -181,6 +210,19 @@ Good Projection:
 - Idempotently reconstructible from events
 - Completely independent from Write model
 
+### External Work Triggers
+
+External workers and asynchronous work should start from domain events confirmed by the Aggregate. Application Services and Coordinators must not bundle command dispatch and external side effects in the same control flow.
+
+| Criteria | Judgment |
+|----------|----------|
+| Application Service or Coordinator dispatches a command, then starts external work for the same state transition | REJECT. Separate into an EventHandler for the confirmed event |
+| Aggregate emits an event that represents generation or processing start, and an EventHandler starts external work | OK |
+| EventHandler converts external start failure into a failure command back to the Aggregate | OK |
+| Inputs needed by external work are represented in the event or reloadable through stable identifiers | OK |
+| Inputs needed by external work exist only as local variables during command handling | REJECT. Move them to events or reloadable references |
+| Saga is used only to start simple external work without contention or compensation | REJECT. EventHandler is sufficient |
+
 ## Query Side Design
 
 Query side operates on an event-driven PubSub model. Projections update Read Models via EventHandler, and queries read from Read Models.
@@ -197,6 +239,21 @@ Event distribution uses PubSub (via message broker) to deliver events to all ins
 | Controller directly referencing Repository | REJECT. Must go through UseCase layer |
 | Query side referencing Command Model | REJECT |
 | QueryHandler issuing commands | REJECT |
+| Query-side service or handler saves, deletes, or calls external APIs | REJECT |
+| 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`)
@@ -249,6 +306,18 @@ Aggregate → Event Bus → Projection(@EventHandler) → Repository(Read Model)
                                           QueryHandler reads from here
 ```
 
+### Async Callbacks and Concurrency Control
+
+Completion notifications for asynchronous work must assume duplicates, delays, and reordering. Protect the workflow with Aggregate state transitions and command idempotency, not Controller-level or single-process locks.
+
+| Criteria | Judgment |
+|----------|----------|
+| Controller or application-process lock prevents duplicate callbacks | REJECT. It does not work across multiple instances |
+| Aggregate state decides whether work is processing | OK |
+| Aggregate verifies callback attempt/generation identifiers | OK |
+| Stale or duplicate callbacks are idempotently ignored by state transition | OK |
+| Concurrency control is duplicated across Controller, UseCase, and Aggregate | REJECT |
+
 ## Eventual Consistency
 
 When synchronous response is needed after command dispatch, use reactive polling to wait for Projection updates.

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/output-contracts/ai-antipattern-review-finding-contract.md

@@ -0,0 +1,31 @@
+```markdown
+# AI-Generated Code Review
+
+## Result: APPROVE / REJECT
+
+## Summary
+{Summarize the result in one sentence}
+
+## Verified Items
+| Aspect | Result | Notes |
+|--------|--------|-------|
+| Validity of assumptions | ✅ | - |
+| API/library existence | ✅ | - |
+| Context fit | ✅ | - |
+| Scope | ✅ | - |
+
+Expected `family_tag` values: `hallucination`, `unvalidated-assumption`, `off-by-one`, `api-mismatch`, `missing-edge-case`, `logic-error`, `scope-creep`.
+When structured raw findings are requested, copy this table's `family_tag` value into the structured `familyTag` field.
+
+## Observed Findings
+| # | family_tag | Category | Severity | Location | Issue | Fix Suggestion |
+|---|------------|----------|----------|----------|-------|----------------|
+| 1 | hallucination | Hallucinated API | high / medium / low | `src/file.ts:23` | Non-existent method | Replace with existing API |
+
+## Rejection Gate
+- REJECT is valid only when at least one blocking finding is observed
+```
+
+**Cognitive load reduction rules:**
+- No issues → Summary sentence + checklist + empty finding sections (10 lines or fewer)
+- Issues found → include table rows only for impacted sections (30 lines or fewer)

package/builtins/en/facets/output-contracts/architecture-review-finding-contract.md

@@ -0,0 +1,35 @@
+```markdown
+# Architecture Review
+
+## Result: APPROVE / IMPROVE / REJECT
+
+## Summary
+{Summarize the result in 1-2 sentences}
+
+## Reviewed Aspects
+- [x] Structure & design
+- [x] Code quality
+- [x] Change scope
+- [x] Test coverage
+- [x] Dead code
+- [x] Call chain verification
+
+## Observed Findings
+| # | family_tag | Scope | Severity | Location | Issue | Fix Suggestion |
+|---|------------|-------|----------|----------|-------|----------------|
+| 1 | design-violation | In-scope | high / medium / low | `src/file.ts:42` | Issue description | Fix approach |
+
+Scope: "In-scope" (fixable in this change) / "Out-of-scope" (existing issue, non-blocking)
+
+## Verification Evidence
+- Build: {Verified target, what was checked, and observed result; or state that it was unverified}
+- Tests: {Verified target, what was checked, and observed result; or state that it was unverified}
+- Functional check: {Verified target, what was checked, and observed result; or state that it was unverified}
+
+## Rejection Gate
+- REJECT is valid only when at least one in-scope blocking finding is observed
+```
+
+**Cognitive load reduction rules:**
+- APPROVE → Summary only (5 lines or fewer)
+- REJECT → Include only relevant finding rows (30 lines or fewer)

package/builtins/en/facets/output-contracts/coding-review-finding-contract.md

@@ -0,0 +1,25 @@
+```markdown
+# Coding Review
+
+## Result: APPROVE / REJECT
+
+## Summary
+{Summarize the review result in 1-2 sentences}
+
+## Observed Findings
+| # | family_tag | Severity | Location | Issue | Impact | Fix Suggestion |
+|---|------------|----------|----------|-------|--------|----------------|
+| 1 | bug | High / Medium / Low | `src/file.ts:42` | {Issue} | {Impact} | {Fix suggestion} |
+
+## Verification Evidence
+- Diff review: {What was checked}
+- Build: {Result, or state unverified}
+- Tests: {Result, or state unverified}
+
+## Rejection Gate
+- REJECT only when at least one blocking finding is observed
+```
+
+**Cognitive load reduction rules:**
+- APPROVE: Summary only (5 lines or fewer)
+- REJECT: Include only relevant finding rows (30 lines or fewer)

package/builtins/en/facets/output-contracts/coding-review.md

@@ -6,6 +6,13 @@
 ## Summary
 {Summarize the review result in 1-2 sentences}
 
+## Contract Entry Check
+Fill this when the diff adds or changes IDs, names, metadata, config, environment variables, or output contracts.
+
+| Entry / Path | Original Requirement | Implementation Evidence | Test Evidence | Judgment | Exception / Unverified Evidence |
+|--------------|----------------------|--------------------------|---------------|----------|---------------------------------|
+| {normal entry / derived condition / validation / evaluation / output / re-injection, etc.} | {Requirement} | `src/file.ts:42` | `src/file.test.ts:10` | ✅/❌/⚠️ | {none / evidence} |
+
 ## Current Iteration Findings (new)
 | # | finding_id | family_tag | Severity | Location | Issue | Impact | Fix Suggestion |
 |---|------------|------------|----------|----------|-------|--------|----------------|
@@ -17,9 +24,9 @@
 | 1 | CODE-PERSIST-src-file-L77 | regression | `src/file.ts:77` | `src/file.ts:77` | {Unresolved issue} | {Fix suggestion} |
 
 ## Resolved Findings (resolved)
-| finding_id | Resolution Evidence |
-|------------|---------------------|
-| CODE-RESOLVED-src-file-L10 | Resolved at `src/file.ts:10` |
+| finding_id | Original Expected Result | Resolution Evidence |
+|------------|--------------------------|---------------------|
+| CODE-RESOLVED-src-file-L10 | {Original finding acceptance criteria} | Resolved at `src/file.ts:10` |
 
 ## Reopened Findings (reopened)
 | # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
@@ -37,5 +44,5 @@
 ```
 
 **Cognitive load reduction rules:**
-- APPROVE: Summary only (5 lines or fewer)
+- APPROVE: Summary plus Contract Entry Check when needed (10 lines or fewer total)
 - REJECT: Include only relevant finding rows (30 lines or fewer)

package/builtins/en/facets/output-contracts/cqrs-es-review-finding-contract.md

@@ -0,0 +1,31 @@
+```markdown
+# CQRS+ES Review
+
+## Result: APPROVE / REJECT
+
+## Summary
+{Summarize the result in 1-2 sentences}
+
+## Reviewed Aspects
+| Aspect | Result | Notes |
+|--------|--------|-------|
+| Aggregate design | ✅ | - |
+| Event design | ✅ | - |
+| Command/Query separation | ✅ | - |
+| Projections | ✅ | - |
+| Eventual consistency | ✅ | - |
+
+## Observed Findings
+| # | family_tag | Severity | Scope | Location | Issue | Impact | Fix Suggestion |
+|---|------------|----------|-------|----------|-------|--------|----------------|
+| 1 | cqrs-violation | High / Medium / Low | In-scope | `src/file.ts:42` | Issue description | Domain consistency or maintainability impact | Fix approach |
+
+Scope: "In-scope" (fixable in this change) / "Out-of-scope" (existing issue, non-blocking)
+
+## Rejection Gate
+- REJECT only when at least one blocking finding is observed
+```
+
+**Cognitive load reduction rules:**
+- APPROVE → Summary only (5 lines or fewer)
+- REJECT → Include only relevant finding rows (30 lines or fewer)

package/builtins/en/facets/output-contracts/findings-manager.md

@@ -0,0 +1,45 @@
+```json
+{
+  "matches": [
+    {
+      "findingId": "F-0001",
+      "rawFindingIds": ["raw-1"],
+      "evidence": "Why this is the same issue"
+    }
+  ],
+  "newFindings": [
+    {
+      "rawFindingIds": ["raw-2"],
+      "title": "Short title for the new finding",
+      "severity": "high"
+    }
+  ],
+  "resolvedFindings": [
+    {
+      "findingId": "F-0002",
+      "rawFindingIds": ["raw-previous-1"],
+      "evidence": "Evidence that the finding is resolved"
+    }
+  ],
+  "reopenedFindings": [
+    {
+      "findingId": "F-0003",
+      "rawFindingIds": ["raw-3"],
+      "evidence": "Evidence that the finding has reappeared"
+    }
+  ],
+  "conflicts": [
+    {
+      "findingIds": [],
+      "rawFindingIds": ["raw-4", "raw-5"],
+      "description": "Reviewer contradiction"
+    }
+  ],
+  "resolvedConflicts": [
+    {
+      "conflictId": "C-012345ABCDEF",
+      "evidence": "Evidence that the conflict is adjudicated"
+    }
+  ]
+}
+```

package/builtins/en/facets/output-contracts/frontend-review-finding-contract.md

@@ -0,0 +1,30 @@
+```markdown
+# Frontend Review
+
+## Result: APPROVE / REJECT
+
+## Summary
+{Summarize the result in 1-2 sentences}
+
+## Reviewed Aspects
+| Aspect | Result | Notes |
+|--------|--------|-------|
+| Component design | ✅ | - |
+| State management | ✅ | - |
+| Canonical and derived state | ✅ | - |
+| Performance | ✅ | - |
+| Accessibility | ✅ | - |
+| Type safety | ✅ | - |
+
+## Observed Findings
+| # | family_tag | Severity | Location | Issue | Impact | Fix Suggestion |
+|---|------------|----------|----------|-------|--------|----------------|
+| 1 | component-design | High / Medium / Low | `src/file.tsx:42` | Issue description | User experience or maintainability impact | Fix approach |
+
+## Rejection Gate
+- REJECT only when at least one blocking finding is observed
+```
+
+**Cognitive load reduction rules:**
+- APPROVE → Summary only (5 lines or fewer)
+- REJECT → Include only relevant finding rows (30 lines or fewer)

package/builtins/en/facets/output-contracts/pure-review-finding-contract.md

@@ -0,0 +1,45 @@
+```markdown
+# Pure Review
+
+## Result: APPROVE / REJECT
+
+## Summary
+{Summarize in 1-2 sentences whether this change is mergeable quality. If REJECT, mention the largest blocker first}
+
+## Pure Review Check
+| # | Area | Status | Evidence (file:line / test / execution evidence) | Comment |
+|---|------|--------|--------------------------------------------------|---------|
+| 1 | Requirement fulfillment | Satisfied / Unmet / Unverified | `src/file.ts:42` | {Notes} |
+| 2 | Existing contract and existing-flow impact | No issue / Issue found / Unverified | `src/file.ts:42` | {Notes} |
+| 3 | Tests and verification | Sufficient / Insufficient / Unverified | `npm test` | {Notes} |
+| 4 | Out-of-scope changes and scope creep | No issue / Issue found / Unverified | `src/file.ts:42` | {Notes} |
+| 5 | Obvious security, data-protection, or operational risk | No issue / Issue found / Unverified | `src/file.ts:42` | {Notes} |
+
+## Requirements Cross-Reference
+| # | Requirement (from task) | Status | Evidence (file:line) | Comment |
+|---|-------------------------|--------|----------------------|---------|
+| 1 | {requirement 1} | Satisfied / Unmet / Unverified | `src/file.ts:42` | {Notes} |
+
+## Out-of-Scope Changes and Existing Impact
+| # | Change | File | Judgment | Comment |
+|---|--------|------|----------|---------|
+| 1 | {out-of-scope change or existing impact} | `src/file.ts` | Justified / Needs review / Unnecessary / Problematic | {Reason} |
+
+## Observed Findings
+| # | family_tag | Category | Severity | Location | Issue | Fix Suggestion |
+|---|------------|----------|----------|----------|-------|----------------|
+| 1 | mergeability | Regression / Requirement gap / Missing tests / Contract break / Scope creep | high / medium / low | `src/file.ts:42` | Issue description | Fix suggestion |
+
+## Verification Evidence
+- Build: {Verified target, what was checked, and observed result; or state that it was unverified}
+- Tests: {Verified target, what was checked, and observed result; or state that it was unverified}
+- Functional check: {Verified target, what was checked, and observed result; or state that it was unverified}
+
+## Rejection Gate
+- REJECT if at least one merge-blocking finding is observed
+- Unverified areas should block merge only when they affect mergeability
+```
+
+**Cognitive load reduction rules:**
+- APPROVE: Summary + Pure Review Check only (10 lines or fewer)
+- REJECT: Prioritize blocker findings (40 lines or fewer)

package/builtins/en/facets/output-contracts/pure-review.md

@@ -16,9 +16,9 @@
 | 5 | Obvious security, data-protection, or operational risk | No issue / Issue found / Unverified | `src/file.ts:42` | {Notes} |
 
 ## Requirements Cross-Reference
-| # | Requirement (from task) | Status | Evidence (file:line) | Comment |
-|---|-------------------------|--------|----------------------|---------|
-| 1 | {requirement 1} | Satisfied / Unmet / Unverified | `src/file.ts:42` | {Notes} |
+| # | Requirement (from task) | Original Requirement Source | Status | Evidence (file:line) | Exception / Unverified Evidence |
+|---|-------------------------|-----------------------------|--------|----------------------|---------------------------------|
+| 1 | {requirement 1} | `order.md:10` | Satisfied / Unmet / Unverified | `src/file.ts:42` | {none / evidence} |
 
 ## Out-of-Scope Changes and Existing Impact
 | # | Change | File | Judgment | Comment |
@@ -36,9 +36,9 @@
 | 1 | PURE-PERSIST-src-file-L77 | mergeability | `file:line` | `file:line` | Unresolved | Fix suggestion |
 
 ## Resolved Findings (resolved)
-| finding_id | Resolution Evidence |
-|------------|---------------------|
-| PURE-RESOLVED-src-file-L10 | `file:line` resolves the issue |
+| finding_id | Original Expected Result | Resolution Evidence |
+|------------|--------------------------|---------------------|
+| PURE-RESOLVED-src-file-L10 | {Original finding acceptance criteria} | `file:line` resolves the issue |
 
 ## Reopened Findings (reopened)
 | # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |

package/builtins/en/facets/output-contracts/qa-review-finding-contract.md

@@ -0,0 +1,35 @@
+```markdown
+# QA Review
+
+## Result: APPROVE / REJECT
+
+## Summary
+{Summarize the result in 1-2 sentences}
+
+## Reviewed Aspects
+| Aspect | Result | Notes |
+|--------|--------|-------|
+| Test coverage | ✅ | - |
+| Test quality | ✅ | - |
+| Error handling | ✅ | - |
+| Documentation | ✅ | - |
+| Maintainability | ✅ | - |
+
+## Observed Findings
+| # | family_tag | Category | Severity | Location | Issue | Fix Suggestion |
+|---|------------|----------|----------|----------|-------|----------------|
+| 1 | test-coverage | Testing | high / medium / low | `src/test.ts:42` | Missing negative test | Add failure-path test |
+
+## Verification Evidence
+- Build: {Verified target, what was checked, and observed result; or state that it was unverified}
+- Tests: {Verified target, what was checked, and observed result; or state that it was unverified}
+- Functional check: {Verified target, what was checked, and observed result; or state that it was unverified}
+
+## Unverified Scope
+| Item | Reason | Impact on Decision |
+|------|--------|--------------------|
+| {Unverified scope, or "none"} | {Reason it was not verified} | {APPROVE allowed / REJECT reason} |
+
+## Rejection Gate
+- REJECT is valid only when at least one blocking finding is observed
+```

package/builtins/en/facets/output-contracts/qa-review.md

@@ -15,6 +15,13 @@
 | Documentation | ✅ | - |
 | Maintainability | ✅ | - |
 
+## Contract Entry Check
+Fill this when the diff adds or changes IDs, names, metadata, config, environment variables, or output contracts.
+
+| Entry / Path | Original Requirement | Implementation Evidence | Test Evidence | Judgment | Exception / Unverified Evidence |
+|--------------|----------------------|--------------------------|---------------|----------|---------------------------------|
+| {normal entry / derived condition / validation / evaluation / output / re-injection, etc.} | {Requirement} | `src/file.ts:42` | `src/file.test.ts:10` | ✅/❌/⚠️ | {none / evidence} |
+
 ## Current Iteration Findings (new)
 | # | finding_id | family_tag | Category | Location | Issue | Fix Suggestion |
 |---|------------|------------|----------|----------|-------|----------------|
@@ -26,9 +33,9 @@
 | 1 | QA-PERSIST-src-test-L77 | test-coverage | `src/test.ts:77` | `src/test.ts:77` | Still flaky | Stabilize assertion & setup |
 
 ## Resolved Findings (resolved)
-| finding_id | Resolution Evidence |
-|------------|---------------------|
-| QA-RESOLVED-src-test-L10 | `src/test.ts:10` now covers error path |
+| finding_id | Original Expected Result | Resolution Evidence |
+|------------|--------------------------|---------------------|
+| QA-RESOLVED-src-test-L10 | {Original finding acceptance criteria} | `src/test.ts:10` now covers error path |
 
 ## Reopened Findings (reopened)
 | # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |

package/builtins/en/facets/output-contracts/security-review-finding-contract.md

@@ -0,0 +1,36 @@
+```markdown
+# Security Review
+
+## Result: APPROVE / REJECT
+
+## Severity: None / Low / Medium / High / Critical
+
+## Check Results
+| Category | Result | Notes |
+|----------|--------|-------|
+| Injection | ✅ | - |
+| Authentication & Authorization | ✅ | - |
+| Data Protection | ✅ | - |
+| Dependencies | ✅ | - |
+
+## Observed Findings
+| # | family_tag | Severity | Type | Location | Issue | Fix Suggestion |
+|---|------------|----------|------|----------|-------|----------------|
+| 1 | injection-risk | High | SQLi | `src/db.ts:42` | Raw query string | Use parameterized queries |
+
+## Verification Evidence
+- Build: {Verified target, what was checked, and observed result; or state that it was unverified}
+- Tests: {Verified target, what was checked, and observed result; or state that it was unverified}
+- Functional check: {Verified target, what was checked, and observed result; or state that it was unverified}
+
+## Warnings (non-blocking)
+- {Security recommendations}
+
+## Rejection Gate
+- REJECT is valid only when at least one blocking vulnerability is observed
+```
+
+**Cognitive load reduction rules:**
+- No issues → Checklist only (10 lines or fewer)
+- Warnings only → + Warnings in 1-2 lines (15 lines or fewer)
+- Vulnerabilities found → + finding tables (30 lines or fewer)