takt 0.49.0 → 0.50.0

package/builtins/en/facets/knowledge/implementation-semantics.md

@@ -0,0 +1,104 @@
+# Implementation Semantics
+
+Knowledge for judging the micro-level design flaws that remain even when every test passes. The targets are data structure choice, state normalization, naming-meaning alignment, and fail-fast at boundaries. Each is a question of whether the meaning is correct, not whether the code runs, which is why tests are structurally bad at catching them.
+
+## Meaning-Driven Data Structure Choice
+
+Choose collection and dictionary types that match the meaning of the data. In particular, implementing a dictionary keyed by externally supplied strings as a plain object lets inherited prototype properties leak in.
+
+| Criterion | Verdict |
+|-----------|---------|
+| A dictionary keyed by external input (IDs, user input) is implemented as `Record` / plain object and membership is checked with `in` or `obj[key]` | REJECT |
+| Behavior can change for keys like `__proto__`, `constructor`, or `toString` | REJECT |
+| Dynamic-key dictionaries use `Map`, or block the inheritance chain via `Object.create(null)` / `Object.hasOwn` | OK |
+| A plain object is used for a fixed, finite key set (e.g. a config object) | OK |
+
+Never flag a guarded `Record` as "should be a `Map`". Blocking the inheritance chain via `Object.hasOwn` / `Object.create(null)` is a complete mitigation, and continuing to use `Record` on top of it is not a design flaw. In particular, when a published contract (a frozen type definition) mandates `Record`, guarding is everything the implementation can do. The only reportable finding is a remaining unguarded access, and it must be cited with its location.
+
+```typescript
+// REJECT - passing the ID "toString" reports it as present despite never being registered
+const reservations: Record<string, Reservation> = {};
+if (reservationId in reservations) { /* also matches inherited properties */ }
+
+// OK - Map has no inherited-property leakage
+const reservations = new Map<string, Reservation>();
+if (reservations.has(reservationId)) { /* matches registered keys only */ }
+```
+
+## Single Source of Truth for Derived Values
+
+Do not maintain a value in parallel when it can be computed from another. The moment it is duplicated, the two can drift, and the question of which one is authoritative is born with it.
+
+| Criterion | Verdict |
+|-----------|---------|
+| A derivable value (total, count, version) is also incremented/decremented as a separate variable | REJECT |
+| Detail records and an aggregate are updated in parallel and can diverge on invalid input | REJECT |
+| Derived values are computed where used, or only the source is updated and the aggregate is obtained via a function | OK |
+| When cached for performance, updates flow through a single path and divergence is detectable | OK |
+
+```typescript
+// REJECT - version is derivable from history length but tracked separately; drift corrupts stock math
+class EventStore {
+  private version = 0;
+  append(e: Event) { this.events.push(e); this.version++; }
+}
+
+// OK - hold only the source and derive the version
+class EventStore {
+  get version() { return this.events.length; }
+  append(e: Event) { this.events.push(e); }
+}
+```
+
+## Naming-Meaning Alignment
+
+A name states the meaning of the value it actually holds. A variable whose name and content diverge plants a false assumption in the reader and breeds the next bug.
+
+| Criterion | Verdict |
+|-----------|---------|
+| The meaning implied by a variable/parameter name differs from the value actually stored (e.g. an ID stored in something named `qty`) | REJECT |
+| Types match but the unit, coordinate system, or normalization state is unreadable from the name and gets mixed up | REJECT |
+| The meaning, unit, and state of the content are unambiguously readable from the name | OK |
+
+```typescript
+// REJECT - named qtyShip, but the value is actually a reservation ID
+function applyShipped(qtyShip: string) { delete this.reservations[qtyShip]; }
+
+// OK - the name matches the meaning of the content
+function applyShipped(reservationId: string) { delete this.reservations[reservationId]; }
+```
+
+## Fail-Fast at Boundaries
+
+Fail immediately at the boundary on impossible states and contract-violating input instead of silently ignoring them. Swallowing them lets the inconsistency propagate downstream before it surfaces, making the cause hard to trace.
+
+| Criterion | Verdict |
+|-----------|---------|
+| Input with broken preconditions (an event for a nonexistent target, ordering violations) is skipped without a word | REJECT |
+| Exceptions are swallowed and a normal value is returned, so callers cannot detect the failure | REJECT |
+| Contract violations surface immediately as explicit errors, exceptions, or Result types | OK |
+| When ignoring is the spec, that decision is documented in a comment or the spec | OK |
+
+```typescript
+// REJECT - silently ignores events for products created later; corrupted event logs go undetected
+apply(event: StockEvent) {
+  const product = this.products[event.productId];
+  if (!product) return;
+}
+
+// OK - fail immediately on impossible states to detect corruption early
+apply(event: StockEvent) {
+  const product = this.products.get(event.productId);
+  if (!product) throw new Error(`event for unknown product: ${event.productId}`);
+}
+```
+
+## Internal State Reference Leaks
+
+When a store or read model returns references to its internal state as-is, caller-side mutations propagate into the persisted data. Return defensive copies or immutable views.
+
+| Criterion | Verdict |
+|-----------|---------|
+| The collection is copied but the stored objects themselves are shared (shallow copy only) | REJECT |
+| Mutating an obtained reference rewrites the persisted state | REJECT |
+| Internal state is protected via defensive copies, freezing, or read-only views | OK |

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

@@ -169,10 +169,18 @@ Provider errors propagate through: `AgentResponse.error` → session log → con
 
 ## Session Management
 
-Agent sessions are stored per-cwd. Session resume is skipped during worktree/clone execution.
+Agent sessions are stored per-cwd and per-provider. Session resume is skipped during worktree/clone execution.
+
+When a normal Phase 1 response merely omits `sessionId`, that alone is not a reason to discard the existing session. Paths that are allowed to continue the existing resume context should preserve the old sessionId.
+
+However, when a retry or fallback explicitly runs as a new session and succeeds, a missing `sessionId` must not continue using the old resumed session. The storage layer must be told that the new run produced no sessionId, so the old session is cleared or isolated.
+
+The Report Phase is Phase 2 and reads Phase 1 outputs. Its execution contract is readonly and tool-free. Report retry/fallback must preserve `permissionMode: readonly`, empty tool permission, and provider capability overrides such as turn limits.
 
 | Criteria | Judgment |
 |----------|----------|
 | Session resuming when `cwd !== projectCwd` | REJECT (cross-project contamination) |
 | Session key missing provider identifier | REJECT (cross-provider contamination) |
-| Session broken between phases | REJECT (context loss) |
+| Session broken between phases that should continue context | REJECT (context loss) |
+| Old resumed session remains after successful new-session retry | REJECT (unintended resume) |
+| Report retry/fallback drops readonly mode, tool-free execution, or capability overrides | REJECT |

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

@@ -30,6 +30,20 @@ const result = await service.getUser('id')
 expect(result).toEqual(user)
 ```
 
+## Test Double Contract Fidelity
+
+When replacing builders, runners, adapters, providers, or similar dependencies with test doubles, match the production semantic contract, not only the TypeScript shape. A test double may simplify only responsibilities the target test does not observe.
+
+| Aspect | Check |
+|--------|-------|
+| Return value | Required values, optional values, missing values, and partial-success shapes match production |
+| Input propagation | Overrides, context, options, and other branch-relevant inputs can be received and verified |
+| Constraints | Permissions, capabilities, tool restrictions, and limits propagate with the same meaning as production |
+| Side effects | Session updates, event emission, persistence, and invalidation can be observed |
+| Simplification scope | Test names and expectations do not claim behavior the test double cannot prove |
+
+If a test double omits part of the production contract, the test should verify only behavior that does not depend on that omission. In tests for permission propagation, state transitions, or missing-value handling, omitted fields are themselves a common source of bugs.
+
 ## Boundary Value Analysis
 
 Boundary values and equivalence partitioning are fundamental unit testing techniques.

package/builtins/en/facets/output-contracts/ai-antipattern-review.md

@@ -14,6 +14,11 @@
 | Context fit | ✅ | - |
 | Scope | ✅ | - |
 
+## Non-Finding Concerns
+| Item | Location | Classification | Evidence for Not Making a Finding |
+|------|----------|----------------|-----------------------------------|
+| {Concern, or "none"} | `src/file.ts:42` | false_positive / overreach / out_of_scope / no_issue_after_verification | {Evidence} |
+
 ## Current Iteration Findings (new)
 | # | finding_id | family_tag | Category | Location | Issue | Fix Suggestion |
 |---|------------|------------|----------|----------|-------|----------------|
@@ -34,11 +39,16 @@
 |---|------------|------------|--------------------------|---------------------|-------|----------------|
 | 1 | AI-REOPENED-src-file-L55 | hallucination | `Previously fixed at src/file.ts:10` | `Recurred at src/file.ts:55` | Issue description | Fix approach |
 
+## Re-scan Evidence (required from the second review onward)
+| Policy/Knowledge section checked | Evidence in the diff (`file:line` or "none") |
+|----------------------------------|----------------------------------------------|
+| {section name} | {evidence} |
+
 ## Rejection Gate
 - REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
 - Findings without `finding_id` are invalid
 ```
 
 **Cognitive load reduction rules:**
-- No issues → Summary sentence + checklist + empty finding sections (10 lines or fewer)
+- No issues → Summary sentence + checklist + Re-scan Evidence (from the second iteration onward) + Non-Finding Concerns when needed
 - Issues found → include table rows only for impacted sections (30 lines or fewer)

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

@@ -41,11 +41,16 @@ Scope: "In-scope" (fixable in this change) / "Out-of-scope" (existing issue, non
 - 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}
 
+## Re-scan Evidence (required from the second review onward)
+| Policy/Knowledge section checked | Evidence in the diff (`file:line` or "none") |
+|----------------------------------|----------------------------------------------|
+| {section name} | {evidence} |
+
 ## Rejection Gate
 - REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
 - Findings without `finding_id` are invalid
 ```
 
 **Cognitive load reduction rules:**
-- APPROVE → Summary only (5 lines or fewer)
+- APPROVE → Summary + Verification Evidence + Re-scan Evidence (from the second iteration onward). Omit everything else
 - REJECT → Include only relevant finding rows (30 lines or fewer)

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

@@ -13,6 +13,11 @@ Fill this when the diff adds or changes IDs, names, metadata, config, environmen
 |--------------|----------------------|--------------------------|---------------|----------|---------------------------------|
 | {normal entry / derived condition / validation / evaluation / output / re-injection, etc.} | {Requirement} | `src/file.ts:42` | `src/file.test.ts:10` | ✅/❌/⚠️ | {none / evidence} |
 
+## Non-Finding Concerns
+| Item | Location | Classification | Evidence for Not Making a Finding |
+|------|----------|----------------|-----------------------------------|
+| {Concern, or "none"} | `src/file.ts:42` | false_positive / overreach / out_of_scope / no_issue_after_verification | {Evidence} |
+
 ## Current Iteration Findings (new)
 | # | finding_id | family_tag | Severity | Location | Issue | Impact | Fix Suggestion |
 |---|------------|------------|----------|----------|-------|--------|----------------|
@@ -38,11 +43,16 @@ Fill this when the diff adds or changes IDs, names, metadata, config, environmen
 - Build: {Result, or state unverified}
 - Tests: {Result, or state unverified}
 
+## Re-scan Evidence (required from the second review onward)
+| Policy/Knowledge section checked | Evidence in the diff (`file:line` or "none") |
+|----------------------------------|----------------------------------------------|
+| {section name} | {evidence} |
+
 ## Rejection Gate
 - REJECT only when at least one finding exists in `new`, `persists`, or `reopened`
 - Findings without `finding_id` are invalid
 ```
 
 **Cognitive load reduction rules:**
-- APPROVE: Summary plus Contract Entry Check when needed (10 lines or fewer total)
+- APPROVE: Summary plus Verification Evidence, Contract Entry Check, Re-scan Evidence (from the second iteration onward), and Non-Finding Concerns when needed
 - REJECT: Include only relevant finding rows (30 lines or fewer)

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

@@ -40,6 +40,20 @@
       "conflictId": "C-012345ABCDEF",
       "evidence": "Evidence that the conflict is adjudicated"
     }
+  ],
+  "waivedFindings": [
+    {
+      "findingId": "F-0003",
+      "reason": "The frozen public contract mandates Record and the hasOwn guard is the complete mitigation",
+      "evidence": "src/types.ts:94, src/domain.ts:82"
+    }
+  ],
+  "disputeNotes": [
+    {
+      "findingId": "F-0004",
+      "reason": "The coder claimed a spec constraint but the evidence does not point at the location; rejected",
+      "evidence": "src/store.ts:10"
+    }
   ]
 }
 ```

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

@@ -0,0 +1,28 @@
+```markdown
+# Implementation Semantics Review
+
+## Result: APPROVE / REJECT
+
+## Summary
+{1-2 sentence summary of the review outcome}
+
+## Observed Findings
+| # | family_tag | Severity | Location | Problem | Breaking Condition | Suggested Fix |
+|---|------------|----------|----------|---------|--------------------|---------------|
+| 1 | data-structure | High / Medium / Low | `src/file.ts:42` | {problem} | {which input or state breaks it} | {suggested fix} |
+
+## Verification Evidence
+- Diff check: {what was verified}
+- Citation check: {confirmation that every cited file:line was verified against the actual code}
+
+## REJECT Criteria
+- REJECT only when at least one blocking finding exists
+```
+
+**Cognitive-load rules:**
+- APPROVE -> summary only (within 5 lines)
+- REJECT -> only the relevant findings in the table (within 30 lines)
+
+**Cognitive-load rules:**
+- APPROVE -> summary only (within 5 lines)
+- REJECT -> only the relevant findings in the table (within 30 lines)

package/builtins/en/facets/output-contracts/implementation-semantics-review.md

@@ -0,0 +1,50 @@
+```markdown
+# Implementation Semantics Review
+
+## Verdict: APPROVE / REJECT
+
+## Summary
+{1-2 sentence summary of the review result}
+
+## Non-Finding Concerns
+| Item | Location | Category | Reason not raised as a finding |
+|------|----------|----------|--------------------------------|
+| {concern, or "none"} | `src/file.ts:42` | false_positive / overreach / out_of_scope / no_issue_after_verification | {reason} |
+
+## New Findings (new)
+| # | finding_id | family_tag | Severity | Location | Problem | Breaking condition | Fix |
+|---|------------|------------|----------|----------|---------|--------------------|-----|
+| 1 | SEM-NEW-src-file-L42 | data-structure | High / Medium / Low | `src/file.ts:42` | {problem} | {what input/state breaks it} | {fix} |
+
+## Persisting Findings (persists)
+| # | finding_id | family_tag | Previous evidence | Current evidence | Problem | Fix |
+|---|------------|------------|-------------------|------------------|---------|-----|
+| 1 | SEM-PERSIST-src-file-L77 | derived-state | `src/file.ts:77` | `src/file.ts:77` | {unresolved problem} | {fix} |
+
+## Resolved (resolved)
+| finding_id | Original acceptance condition | Resolution evidence |
+|------------|------------------------------|---------------------|
+| SEM-RESOLVED-src-file-L10 | {acceptance condition of the original finding} | resolved at `src/file.ts:10` |
+
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Resolution evidence (previous) | Recurrence evidence | Problem | Fix |
+|---|------------|------------|-------------------------------|---------------------|---------|-----|
+| 1 | SEM-REOPENED-src-file-L55 | fail-fast | `previous: src/file.ts:10` | `src/file.ts:55` | {recurred problem} | {fix} |
+
+## Verification Evidence
+- Diff check: {what was checked}
+- Citation existence check: {confirmation that every cited file:line was verified against real code}
+
+## Re-scan Evidence (required from the second review onward)
+| Policy/Knowledge chapter checked | Diff-side evidence (`file:line` or "none applicable") |
+|----------------------------------|------------------------------------------------------|
+| {chapter} | {evidence} |
+
+## Rejection Gate
+- REJECT only when there is at least one `new`, `persists`, or `reopened` finding
+- Findings without a `finding_id` are invalid
+```
+
+**Cognitive load reduction rules:**
+- APPROVE → Summary + Verification Evidence + Re-scan Evidence (from the second iteration onward), plus Non-Finding Concerns only when needed
+- REJECT → List only the applicable findings in tables (30 lines or fewer)

package/builtins/en/facets/output-contracts/{pure-review-finding-contract.md → merge-readiness-review-finding-contract.md}

@@ -1,19 +1,25 @@
 ```markdown
-# Pure Review
+# Merge Readiness Review
 
 ## Result: APPROVE / REJECT
 
 ## Summary
-{Summarize in 1-2 sentences whether this change is mergeable quality. If REJECT, mention the largest blocker first}
+{Summarize in 1-2 sentences whether this change is quality-ready for a codebase that must be maintained going forward. If REJECT, mention the largest blocker first}
 
-## Pure Review Check
+## Maintainability-Aware Merge Quality 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} |
+| 3 | Tests and verification | Sufficient / Insufficient / Unverified | `test evidence` | {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} |
+| 5 | Maintainability and future changeability | No issue / Issue found / Unverified | `src/file.ts:42` | {Notes} |
+| 6 | Obvious security, data-protection, or operational risk | No issue / Issue found / Unverified | `src/file.ts:42` | {Notes} |
+
+## Cross-Audit Evidence
+| # | Change Category | Extracted Item | Search Terms / Files Checked | Judgment | Comment |
+|---|-----------------|----------------|------------------------------|----------|---------|
+| 1 | ID / config / output contract / type / helper / adapter / entrypoint | {item} | `{search term}` / `file:line` | No issue / Issue found / Unverified | {Notes} |
 
 ## Requirements Cross-Reference
 | # | Requirement (from task) | Status | Evidence (file:line) | Comment |
@@ -28,7 +34,7 @@
 ## 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 |
+| 1 | maintainability-readiness | Regression / Requirement gap / Missing tests / Contract break / Maintainability degradation / 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}
@@ -37,9 +43,9 @@
 
 ## Rejection Gate
 - REJECT if at least one merge-blocking finding is observed
-- Unverified areas should block merge only when they affect mergeability
+- Unverified areas should block merge only when they affect maintainability-aware merge quality
 ```
 
 **Cognitive load reduction rules:**
-- APPROVE: Summary + Pure Review Check only (10 lines or fewer)
+- APPROVE: Summary + Maintainability-Aware Merge Quality Check + Cross-Audit Evidence only (15 lines or fewer)
 - REJECT: Prioritize blocker findings (40 lines or fewer)

package/builtins/en/facets/output-contracts/{pure-review.md → merge-readiness-review.md}

@@ -1,19 +1,25 @@
 ```markdown
-# Pure Review
+# Merge Readiness Review
 
 ## Result: APPROVE / REJECT
 
 ## Summary
-{Summarize in 1-2 sentences whether this change is mergeable quality. If REJECT, mention the largest blocker first}
+{Summarize in 1-2 sentences whether this change is quality-ready for a codebase that must be maintained going forward. If REJECT, mention the largest blocker first}
 
-## Pure Review Check
+## Maintainability-Aware Merge Quality 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} |
+| 3 | Tests and verification | Sufficient / Insufficient / Unverified | `test evidence` | {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} |
+| 5 | Maintainability and future changeability | No issue / Issue found / Unverified | `src/file.ts:42` | {Notes} |
+| 6 | Obvious security, data-protection, or operational risk | No issue / Issue found / Unverified | `src/file.ts:42` | {Notes} |
+
+## Cross-Audit Evidence
+| # | Change Category | Extracted Item | Search Terms / Files Checked | Judgment | Comment |
+|---|-----------------|----------------|------------------------------|----------|---------|
+| 1 | ID / config / output contract / type / helper / adapter / entrypoint | {item} | `{search term}` / `file:line` | No issue / Issue found / Unverified | {Notes} |
 
 ## Requirements Cross-Reference
 | # | Requirement (from task) | Original Requirement Source | Status | Evidence (file:line) | Exception / Unverified Evidence |
@@ -28,22 +34,22 @@
 ## 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 |
+| 1 | MERGE-NEW-src-file-L42 | maintainability-readiness | Regression / Requirement gap / Missing tests / Contract break / Maintainability degradation / 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 |
+| 1 | MERGE-PERSIST-src-file-L77 | maintainability-readiness | `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 |
+| MERGE-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 |
+| 1 | MERGE-REOPENED-src-file-L55 | maintainability-readiness | `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}
@@ -53,9 +59,9 @@
 ## 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
+- Unverified areas should block merge only when they affect maintainability-aware merge quality
 ```
 
 **Cognitive load reduction rules:**
-- APPROVE: Summary + Pure Review Check only (10 lines or fewer)
+- APPROVE: Summary + Maintainability-Aware Merge Quality Check + Cross-Audit Evidence only (15 lines or fewer)
 - REJECT: Prioritize blocker findings (40 lines or fewer)

package/builtins/en/facets/output-contracts/supervisor-validation.md

@@ -18,7 +18,7 @@ Extract requirements from the task spec and verify each one individually against
 - ✅ without evidence is invalid (must verify against actual code)
 - Do not mark a row as ✅ when the evidence covers only part of the cases
 - Treat optionalization, exclusion, or exception not present in the task spec as unmet
-- Do not rely on plan report's judgment; independently verify mergeability
+- Do not rely on plan report's judgment; independently verify maintainability-aware merge quality
 
 ## Re-evaluation of Prior Findings
 | finding_id | Prior Status | Original Expected Result | Re-evaluation | Evidence |
@@ -28,7 +28,11 @@ Extract requirements from the task spec and verify each one individually against
 - If final judgment differs from prior review conclusions, explain why with evidence
 - Treat `resolved` as valid only when it satisfies the original expected result and original requirement
 - If marking `false_positive` or `overreach`, state whether it conflicts with the task objective, the plan, or both
-- If overturning a pure-review conclusion, explain why with concrete evidence
+
+## Unclassified Concern Check
+| Review | Concern | Finding State | Supervisor Judgment | Evidence |
+|--------|---------|---------------|---------------------|----------|
+| {Review name} | {Concern, or "none"} | made finding / classified non-finding / unclassified | valid / REJECT reason / out of scope | `src/file.ts:42` |
 
 ## Maintenance Scope Check (maintenance workflows only)
 

package/builtins/en/facets/output-contracts/test-report.md

@@ -1,11 +1,36 @@
 ```markdown
 # Test Creation Report
 
+## Requirement-Test Matrix
+| Requirement ID | Observable Contract | Entry / Path | Test | Result | Uncovered Reason |
+|----------------|---------------------|--------------|------|--------|------------------|
+| `{ID}` | {return value, persisted format, config key, CLI output, event, error classification, side effect, etc.} | {CLI / config load / config save / runtime / batch / child / event / persistence, etc.} | `{test name or test file}` | Created / Existing / Not created | {reason only when not created} |
+
+## Risky Branch Tests
+| Branch | Incorrect Implementation To Catch | Test | Uncovered Reason |
+|--------|-----------------------------------|------|------------------|
+| {missing, unknown, invalid value, precedence conflict, override, round-trip, partial failure, etc.} | {incorrect implementation this test should detect} | `{test name or test file}` | {reason only when not created} |
+
+## Cross-Path Tests
+| Path | Producer | Consumer | Contract Guaranteed | Test | Uncovered Reason |
+|------|----------|----------|---------------------|------|------------------|
+| {path from entry point to endpoint} | {where the value or state is produced} | {where the value or state is consumed} | {propagation, conversion, persistence, event emission, etc.} | `{test name or test file}` | {reason only when not created} |
+
+## Negative Contracts
+| Prohibited Behavior | Observation Method | Test | Uncovered Reason |
+|---------------------|--------------------|------|------------------|
+| {value that must not be emitted, format that must not be saved, data that must not be sent, etc.} | {how to observe it as behavior} | `{test name or test file}` | {reason only when not created} |
+
 ## Created Tests
 | File | Type | Count | Summary |
 |------|------|-------|---------|
 | `{test file path}` | Unit / Integration | {N} | {what is tested} |
 
+## Uncovered Items
+| Requirement / Branch | Uncovered Reason | Required Follow-up |
+|----------------------|------------------|--------------------|
+| {uncovered requirement or branch} | {why it was not tested} | {implementation, review, or manual verification needed later} |
+
 ## Execution Results (Reference)
 Test failures and import errors are expected before implementation.
 

package/builtins/en/facets/personas/implementation-semantics-reviewer.md

@@ -0,0 +1,27 @@
+# Implementation Semantics Reviewer
+
+You are a code reviewer specializing in implementation semantics. You detect the micro-level design flaws that slip through passing tests: data structure choice, state normalization, naming-meaning alignment, and fail-fast at boundaries.
+
+## Role Boundaries
+
+**What you do:**
+- Verify that dictionary, collection, and type choices match the meaning of the data they hold
+- Verify that no value is kept in parallel when it can be derived (single source of truth violations)
+- Verify that variable, parameter, and field names match the meaning of the values actually stored
+- Verify that impossible states and invalid inputs are not silently ignored
+- Verify that references to internal state do not leak out raw
+
+**What you don't do:**
+- Evaluate module decomposition, layers, or dependency direction (architecture-reviewer's job)
+- Flag coding conventions, spec compliance, or missing tests (coding-reviewer's job)
+- Detect AI-specific antipatterns (ai-antipattern-reviewer's job)
+- Write code yourself
+- Demand rewrites based on preference alone
+
+## Behavioral Stance
+
+- Ask "is the meaning correct", not "do the tests pass"
+- Tie every finding to real code lines and the concrete conditions under which it breaks
+- Aggregate multiple locations of the same kind of problem into one representative finding and spend the remaining attention hunting different kinds
+- Do not raise findings whose reason to fix is weak
+- APPROVE when there is no problem

package/builtins/en/facets/personas/merge-readiness-reviewer.md

@@ -0,0 +1,28 @@
+# Merge Readiness Reviewer
+
+You are the final gate reviewer who decides whether the converged change is quality-ready to enter a codebase that must be maintained going forward. Without limiting yourself to one specialty, inspect the accumulated diff, surrounding code, and execution evidence for cross-cutting misses, maintainability risks, and merge blockers.
+
+## Role Boundaries
+
+**Do:**
+- Judge whether the change is quality-ready for a maintainable codebase based on actual code and diffs
+- Detect unmet requests, broken existing behavior, missing tests, out-of-scope changes, maintainability degradation, and obvious risks
+- Check cross-cutting coverage for changed contracts, identifiers, config, outputs, entry points, and persisted/displayed/executed paths
+- Report only blocking issues with concrete evidence
+
+**Don't:**
+- Write code yourself
+- Deep-review architecture direction; that is the Architecture Reviewer's job
+- Deep-review security vulnerabilities; that is the Security Reviewer's job
+- Deep-review test design; that is the Testing Reviewer's job
+- Deep-review code style or implementation craft; that is the Coding Reviewer's job
+
+## Behavioral Principles
+
+- Keep the final question as: "Is this change quality-ready for a codebase we must keep maintaining?"
+- Re-check the accumulated diff even when specialist reviews have passed
+- Trace changed names, contracts, and entry points across same-kind usages
+- Do not miss states that future maintainers cannot safely trace, modify, or verify
+- Do not mark an item verified unless you actually searched or inspected it
+- Judge `resolved` against the original finding's expected result and acceptance criteria
+- Report only issues that should block the merge, not preferences or general advice

package/builtins/en/facets/personas/supervisor.md

@@ -22,7 +22,7 @@ you verify "**was the right thing built (Validation)**".
 ## Behavioral Principles
 
 - Re-check requirements yourself. Do not adopt the decomposition from earlier reviews without verification
-- Treat `pure-review` as supporting material, not as the final answer
+- Treat `merge-readiness-review` as supporting material, not as the final answer
 - Mark missing execution evidence as unverified instead of assuming success
 - Treat contradictions between report text and execution evidence as first-class findings
 - Distinguish `false_positive` from `overreach`; a technically invalid finding and a scope-exceeding finding are not the same

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

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