takt 0.45.0 → 0.47.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,19 @@ 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 |
+| 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 +258,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,9 @@ 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 |
 
 Types between layers:
 - `application/query/` - Query result types (e.g., `OrderDetail`)
@@ -249,6 +294,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

@@ -17,6 +17,17 @@ E2E tests verify the entire user operation flow. Their scope differs from unit a
 | Scenarios spanning multiple commands/pages | E2E test is appropriate |
 | Error message display verification | E2E test is appropriate |
 
+## Behavior Observation
+
+E2E tests observe behavior visible to the user. Checking configuration values, logs, or snapshots alone does not prove that rejection, permission, isolation, or recovery actually occurred.
+
+| Criteria | Judgment |
+|----------|----------|
+| Results from user actions or external inputs are observed | OK |
+| Rejection, error, and recovery paths verify the expected result | OK |
+| 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 |
+
 ## UX Route Identification
 
 E2E test completeness depends on thorough UX route identification. Identify entry points from code, not documentation.
@@ -86,4 +97,3 @@ Manage test cases as a list to guarantee E2E test completeness.
 | Classify by entry point | Group by command/page/endpoint |
 | Prioritize | Determine priority by user impact × untested risk |
 | Cross-reference with existing tests | Check existing test coverage before adding new tests |
-

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

@@ -54,6 +54,17 @@ test('validates age at boundaries', () => {
 })
 ```
 
+## Behavior Guarantees
+
+Unit tests should verify that the public contract behaves as expected, not only that configuration values or internal-state snapshots changed. Boundary changes such as rejection, permission, isolation, or release should cover the main success/failure cases deterministically.
+
+| Criteria | Judgment |
+|----------|----------|
+| Expected return values, exceptions, or side effects are directly verified | OK |
+| Both sides of a boundary change, such as success/failure or allow/deny, are verified | OK |
+| Only configuration values or the last internal state are checked | REJECT |
+| Main boundary conditions require an external environment to reproduce | Consider a deterministic test with a fake or stub |
+
 ## Test Fixture Design
 
 Manage test data with factory functions.

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/maintenance-scope.md

@@ -19,6 +19,11 @@
 |----------|--------|--------------|
 | {Contract type} | {Target} | {What is preserved} |
 
+## Replaced Old Specifications
+| Old Specification | New Specification | Deletion Targets | Test Strategy |
+|-------------------|-------------------|------------------|---------------|
+| {Old specification} | {New specification} | {Implementation/tests to delete} | {Where to verify the new specification} |
+
 ## Unnecessary Change Check
 | Check Target | Result | Notes |
 |--------------|--------|-------|

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

@@ -0,0 +1,61 @@
+```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) | 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 |
+|---|--------|------|----------|---------|
+| 1 | {out-of-scope change or existing impact} | `src/file.ts` | Justified / Needs review / Unnecessary / Problematic | {Reason} |
+
+## Current Iteration Findings (new)
+| # | finding_id | family_tag | Category | Location | Issue | Fix Suggestion |
+|---|------------|------------|----------|----------|-------|----------------|
+| 1 | PURE-NEW-src-file-L42 | mergeability | Regression / Requirement gap / Missing tests / Contract break / Scope creep | `src/file.ts:42` | Issue description | Fix suggestion |
+
+## Carry-over Findings (persists)
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | PURE-PERSIST-src-file-L77 | mergeability | `file:line` | `file:line` | Unresolved | Fix suggestion |
+
+## Resolved Findings (resolved)
+| 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 |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | PURE-REOPENED-src-file-L55 | mergeability | `Previously fixed at file:line` | `Recurred at file:line` | Issue description | Fix approach |
+
+## 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 issue exists in `new`, `persists`, or `reopened`
+- Findings without `finding_id` are invalid
+- 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/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 |
@@ -40,6 +47,11 @@
 - 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 finding exists in `new`, `persists`, or `reopened`
 - Findings without `finding_id` are invalid

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)