mandrel 1.87.0 → 1.89.0

package/.agents/README.md

@@ -731,13 +731,18 @@ chain, `security-review`, and `ultrareview` were added in Story #2871.
 
 ---
 
-## Feedback loop — code-review auto-graduation
-
-When the Epic finalize listener runs, non-blocking code-review findings
-(severity `high`, `medium`, or `low`) that survived merge are
-auto-graduated into follow-up issues, routed by source classification
-into the framework repo or the consumer repo. The toggle lives at
-`delivery.feedbackLoop.codeReviewAutoFile` and defaults to `true`.
+## Feedback loop — verification-results auto-graduation
+
+When the Epic finalize listener runs, non-blocking findings (severity
+`high`, `medium`, or `suggestion`) that survived merge are auto-graduated
+into follow-up issues in a SINGLE pass over the unified
+`verification-results` structured comment (Story #4411 folded the former
+`code-review` and `audit-results` comments into one), routed by source
+classification into the framework repo or the consumer repo. The toggle
+lives at `delivery.feedbackLoop.auditResultsAutoFile` and defaults to
+`true`. (The former `codeReviewAutoFile` key was retired with its
+graduator when the pass unified — a config carrying it fails validation;
+delete the key.)
 
 To opt out (for example, to triage findings manually during a
 stabilization window), set the toggle to `false` in your root
@@ -747,17 +752,17 @@ stabilization window), set the toggle to `false` in your root
 {
   "delivery": {
     "feedbackLoop": {
-      "codeReviewAutoFile": false
+      "auditResultsAutoFile": false
     }
   }
 }
 ```
 
-When disabled, the listener short-circuits and leaves the structured
-`code-review` comments on the Epic ticket untouched. Re-enabling the
-toggle is safe: the graduator embeds an idempotency marker
-(`<!-- code-review-followup: epic-<id>-finding-<idx> -->`) in each filed
-issue body, so re-runs skip findings that already have an issue.
+When disabled, the listener short-circuits and leaves the
+`verification-results` comment on the Epic ticket untouched. Re-enabling
+the toggle is safe: the graduator embeds a content-derived idempotency
+marker in each filed issue body, so re-runs skip findings that already
+have an issue.
 
 ---
 

package/.agents/audit-checklists/architecture.md

@@ -0,0 +1,24 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-architecture.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# Architecture & Clean Code Audit — authoring checklist
+
+> Audit architectural boundaries, module coupling, and layering violations; emit a structured findings report keyed to High/Medium/Low severity.
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Documented architecture boundaries
+- [ ] Automated boundary checks
+- [ ] Over-Engineering & Abstractions
+- [ ] Cognitive Load & Nesting
+- [ ] Dead Code & Redundancy
+- [ ] Naming & Self-Documentation
+- [ ] Coupling & Cohesion
+- [ ] Testable Surface (Humble-Object Boundary)
+- [ ] High
+- [ ] Medium
+- [ ] Low
+- [ ] Automated Architecture Guardrails

package/.agents/audit-checklists/clean-code.md

@@ -0,0 +1,24 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-clean-code.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# Clean Code & Maintainability Audit — authoring checklist
+
+> Audit code smells, dead code, complexity hotspots, and maintainability-index outliers; emit a structured findings report.
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Logic Complexity
+- [ ] Duplication
+- [ ] Component Health
+- [ ] Naming Clarity
+- [ ] Error Handling
+- [ ] Dead Code
+- [ ] SOLID Principles
+- [ ] DRY (Don't Repeat Yourself)
+- [ ] KISS (Keep It Simple, Stupid)
+- [ ] Testability
+- [ ] Dead Code & Orphaned Modules
+- [ ] Documentation

package/.agents/audit-checklists/dependencies.md

@@ -0,0 +1,14 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-dependencies.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# Dependency Update Audit — authoring checklist
+
+> Audit `package. json` for unused, outdated, and major-version-stale dependencies; surface Node-engine drift and propose upgrade batches.
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Inventory & Stale Check
+- [ ] Vulnerability Scan

package/.agents/audit-checklists/devops.md

@@ -0,0 +1,17 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-devops.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# DevOps Infrastructure Audit — authoring checklist
+
+> Audit CI/CD workflows, container images, infrastructure-as-code, and deployment pipelines; surface failure modes and hardening gaps.
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Redundancy & Duplication
+- [ ] Performance Gaps
+- [ ] Security & Compliance
+- [ ] Standardization & Modernization
+- [ ] Reliability & Resilience

package/.agents/audit-checklists/documentation.md

@@ -0,0 +1,22 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-documentation.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# Documentation Staleness & Completeness Audit — authoring checklist
+
+> Audit the repository's main documentation for staleness, semantic drift, and completeness; emit a structured High/Medium/Low findings report.
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Checker failures
+- [ ] Generator dirtiness
+- [ ] Command & Script References
+- [ ] Path & Module References
+- [ ] Workflow & Contract Descriptions
+- [ ] Version & Topology Claims
+- [ ] Completeness
+- [ ] History Bloat
+- [ ] Contradiction
+- [ ] Authority Drift

package/.agents/audit-checklists/lighthouse.md

@@ -0,0 +1,15 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-lighthouse.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# Lighthouse Audit & Analysis — authoring checklist
+
+> Run a Lighthouse audit (Performance / Accessibility / Best Practices / SEO) and produce a structured findings report
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Opportunities
+- [ ] Diagnostics
+- [ ] Failed audits

package/.agents/audit-checklists/navigability.md

@@ -0,0 +1,14 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-navigability.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# Navigability Audit — authoring checklist
+
+> Audit the whole route tree against the consumer's nav-registry SSOT — every route has a persona nav door and no nav href is dead. A deliberately-global lens (Epic #4131, F2/F3) exempt from the cross-epic-leak guard and routed onto route-adding change sets.
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Every route has a persona nav door.
+- [ ] No nav href is dead.

package/.agents/audit-checklists/performance.md

@@ -0,0 +1,22 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-performance.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# Performance & Bottleneck Audit — authoring checklist
+
+> Audit hot paths, algorithmic complexity, and I/O bottlenecks in the tooling surface (`epic-close`, dispatcher, gates); propose remediations.
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Database/API Efficiency
+- [ ] Frontend Rendering
+- [ ] Bundle Size
+- [ ] Resource Usage
+- [ ] Network Path
+- [ ] Latency
+- [ ] Throughput
+- [ ] Efficiency
+- [ ] Scalability
+- [ ] Core Web Vitals

package/.agents/audit-checklists/privacy.md

@@ -0,0 +1,21 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-privacy.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# Privacy and PII Data Audit — authoring checklist
+
+> Audit logs, telemetry, and persistence paths for PII leakage and retention violations; surface secrets exposure and consent gaps.
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Log Statements
+- [ ] Storage
+- [ ] API Requests
+- [ ] Analytics
+- [ ] Data Minimization
+- [ ] Leaky Logging
+- [ ] Insecure Transmission
+- [ ] Hardcoded Secrets
+- [ ] Consent & Retention

package/.agents/audit-checklists/quality.md

@@ -0,0 +1,18 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-quality.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# Testing & Quality Assurance Audit — authoring checklist
+
+> Audit test coverage gaps, flaky tests, missing assertions, and test-pyramid balance; recommend a remediation batch.
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Coverage vs. Confidence
+- [ ] Test Fragility & Flakiness
+- [ ] Mocking & Stubbing Strategy
+- [ ] Test Data Management
+- [ ] Performance & Execution
+- [ ] Requirement Alignment

package/.agents/audit-checklists/security.md

@@ -0,0 +1,22 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-security.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# Security & Vulnerability Audit — authoring checklist
+
+> Audit dependency CVEs, input-validation gaps, secrets handling, and auth boundaries; emit a structured High/Medium/Low findings report.
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Input Validation
+- [ ] Injection Risks
+- [ ] Authentication/Authorization
+- [ ] Dependency Security
+- [ ] Secret Management
+- [ ] Injection
+- [ ] Broken Access Control
+- [ ] Cryptographic Failures
+- [ ] Security Misconfiguration
+- [ ] Vulnerable Components

package/.agents/audit-checklists/seo.md

@@ -0,0 +1,16 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-seo.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# SEO & Generative Engine Optimization Audit — authoring checklist
+
+> Audit SEO fundamentals and Generative Engine Optimization signals (meta, structured data, crawlability); only relevant for web targets.
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Traditional SEO
+- [ ] AIO & GEO (Answer Engine Optimization)
+- [ ] Core Web Vitals
+- [ ] Crawlability

package/.agents/audit-checklists/sre.md

@@ -0,0 +1,24 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-sre.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# Production Release Candidate Audit — authoring checklist
+
+> Audit production-readiness for a release candidate: SLOs, observability, runbooks, error budgets, and rollback paths.
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Config Integrity
+- [ ] Hardcoding Scan
+- [ ] Fallback Logic
+- [ ] Secret Leaks
+- [ ] Input Sanitization
+- [ ] Dependency Risks
+- [ ] Console Hygiene
+- [ ] Error Swallowing
+- [ ] Boundary Handling
+- [ ] Dead Code
+- [ ] Complexity
+- [ ] Asset Loading

package/.agents/audit-checklists/ux-ui.md

@@ -0,0 +1,21 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-ux-ui.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# UX/UI & Design System Audit — authoring checklist
+
+> Audit UX/UI consistency and design system adherence
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Hardcoded Values
+- [ ] Component Re-implementation
+- [ ] Interactive States
+- [ ] Typography
+- [ ] Information Hierarchy
+- [ ] Error States
+- [ ] Loading States
+- [ ] Responsiveness
+- [ ] Accessibility (UX-focused)

package/.agents/docs/SDLC.md

@@ -112,12 +112,18 @@ From zero to shipped:
    3. **Phase 3 — close-validation** — lint, test, and the project's
       ratcheted baselines run against the Epic branch. Evidence is
       cached by HEAD SHA so re-runs short-circuit.
-   4. **Phase 4 — audit** — runs the change-set audit lenses against
-      the Epic diff; findings flow through as advisory signal.
+   4. **Phase 4 — Epic-close lens roster** — resolves (does not walk) the
+      slim Epic-close lens roster: the change-set `gate3` selection plus the
+      risk-routed lenses, restricted to the **cumulative + global +
+      risk-routed** tiers via `selectEpicCloseLenses` (every local-tier
+      change-set lens is excluded — already verified shift-left). The roster is
+      handed to Phase 5.
    5. **Phase 5 — code-review** — auto-invokes the in-process
-      `lib/orchestration/code-review.js` (extracted from the old
-      `helpers/code-review.md` helper); findings persist as a
-      `code-review` structured comment on the Epic. Critical findings
+      `lib/orchestration/code-review.js`; walks the cumulative Epic diff
+      **once**, executing the Phase 4 lens roster as review dimensions
+      **alongside** the review pillars (Story #4412 folded the standalone lens
+      walk into this pass). Findings persist as the single unified
+      `verification-results` structured comment on the Epic. Critical findings
       halt the run.
    6. **Phase 6 — retro** — auto-invokes the in-process
       `lib/orchestration/retro-runner.js` (extracted from the old
@@ -889,13 +895,31 @@ watch / auto-merge / cleanup tail that drives the PR to merge:
    on `git rev-parse HEAD`. A clean tree on a re-run short-circuits in
    milliseconds. A failing gate halts the workflow until the regression is
    fixed on a hotfix branch and re-merged into the Epic.
-2. **Audit (Phase 4).** The change-set audit lenses run against the Epic
-   diff; findings flow through as advisory signal to inform the code
-   review that follows.
-3. **Code-review (Phase 5).** `lib/orchestration/code-review.js` (extracted
-   from the `code-review.md` helper) audits the diff and posts the
-   findings as a `code-review` structured comment on the Epic. 🔴 Critical
-   findings halt the run; 🟠/🟡/🟢 findings flow through as non-blocking.
+2. **Epic-close lens roster (Phase 4).** Resolves — does not walk — the slim
+   Epic-close lens roster (`epicCloseLenses`): the `gate3` change-set selection
+   plus the risk-routed lenses, restricted to the **cumulative + global +
+   risk-routed** tiers via `selectEpicCloseLenses`. Every **local-tier**
+   change-set lens is excluded because its concern is already verified
+   shift-left — the write-time distilled checklist threaded into the Story
+   prompt (Story #4410) and the maker-blind Story-scope local-lens pass in
+   `story-close` (Story #4409). The roster is handed to Phase 5; there is no
+   standalone Phase 4 walk and no separate `audit-results` comment (Story
+   #4412).
+3. **Code-review (Phase 5) — cumulative diff walked once.**
+   `lib/orchestration/code-review.js` walks `main..epic/<id>` a single time,
+   executing the Phase 4 lens roster as review **dimensions** alongside the
+   review pillars, and posts the unified `verification-results` structured
+   comment on the Epic (Story #4411 unified the former `code-review` and
+   `audit-results` contracts; Story #4412 folded the lens walk into this pass).
+   Remediation is **tier-aware and split by finding class** (Story #4412): the
+   review-pillar findings route off `delivery.codeReview.autoFixSeverity`
+   (default `medium` — 🔴/🟠/🟡 on-branch, 🟢 stays on the comment), while the
+   Epic-close lens findings route off `delivery.epicAudit.autoFixSeverity`
+   (default **`high`** — only 🔴/🟠 on-branch; 🟡/🟢 graduate, because 🟡
+   Medium concerns were already remediated shift-left). Fixed findings land
+   under the comment's `## Fixed on-branch` section so the graduator skips
+   them. The severity gate is unchanged: surviving 🔴 Critical findings halt
+   the run; surviving 🟠/🟡/🟢 flow through as non-blocking.
 4. **Retro (Phase 6).** `lib/orchestration/retro-runner.js` (extracted from the old
    retro helper) aggregates perf signals, friction counts, hotfix counts,
    recut counts, parked counts, and HITL count using
@@ -992,7 +1016,7 @@ required checks fail.
    label-transition pathway flips the Epic to `agent::done` on merge.
    The operator becomes a touchpoint here only when they (a) disarm
    auto-merge in the GitHub UI to inspect required-checks, the
-   `code-review` comment, and the retro before merging by hand, or
+   `verification-results` comment, and the retro before merging by hand, or
    (b) checks fail and need remediation on the Epic branch. There is
    no separate close command — the close-out side effects (PR open,
    handoff comment) are owned by `/deliver`'s
@@ -1213,15 +1237,38 @@ on so re-runs short-circuit when state has not changed.
 
 | Gate                      | When                                                 | What Runs                                                                                 | Blocking? | Idempotency key                                                          |
 | ------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------ |
-| Gate 1                    | After Story completion                               | Content-triggered audits (clean-code, etc.)                                              | advisory  | Audit-report comment per Story (`audit-<lens>` structured comment)       |
-| Gate 2                    | Pre-integration                                      | Dependency + DevOps audits                                                                | advisory  | Audit-report comment per Epic (`audit-<lens>` structured comment)        |
-| Gate 3                    | `/deliver` `delivery.code-review` state         | Full automated audit pass                                                                 | blocking  | `code-review` structured comment on Epic, keyed by Epic HEAD SHA          |
+| Tier 1 — write-time       | During Story implementation                          | Local-tier lens checklists threaded into the Story prompt (clean-code, etc.)             | advisory  | Distilled checklist in the hydrated Story prompt (Story #4410)           |
+| Tier 2 — Story-scope      | `story-close` (maker-blind subprocess)               | Local-tier lens roster over the Story diff (`selectLocalLenses`)                          | advisory  | `verification-results` structured comment on the Story                   |
+| Tier 3 — Epic-close       | `/deliver` Phase 4→5 (code-review pass)              | Slim roster: cumulative + global + risk-routed lenses (`selectEpicCloseLenses`) + pillars | blocking  | `verification-results` structured comment on Epic, keyed by Epic HEAD SHA |
 | Gate 4                    | `/deliver` `delivery.finalize` state (pre-PR)   | `audit-sre` production readiness gate                                                     | blocking  | `audit-sre` structured comment on Epic, keyed by Epic HEAD SHA            |
 | Close-validation          | `/deliver` `delivery.close-validation` state    | lint + test + maintainability + CRAP + coverage ratchets via `evidence-gate.js`           | blocking  | `evidence-gate` cache entry keyed by `git rev-parse HEAD`                 |
 | Pre-push                  | Local `.husky/pre-push` hook on every push           | Diff-scoped quality preview + coverage/CRAP ratchet                                       | blocking  | Working-tree SHA + staged-diff hash (per push)                            |
 | Acceptance reconciliation | `/deliver` `delivery.finalize` state            | `acceptance-spec-reconciler.js` diffs AC IDs against `@ac-*` / `@pending` feature tags    | blocking  | `acceptance-reconcile` structured comment on Epic, keyed by spec-body SHA |
 | Spec freshness            | `/plan` `planning.spec-authoring` state         | Re-derives Tech Spec / Acceptance Spec staleness against Epic body checksum               | advisory  | `epic-plan-state` checkpoint entry per spec artifact body SHA             |
 
+#### Three-tier lens model (Epic #4405)
+
+The three audit-lens tiers above (write-time → Story-scope → Epic-close) form a
+**shift-left** verification model in which **each lens concern is verified at
+exactly one tier**, chosen by the lens's `scope` field in `audit-rules.json`
+(resolved by `resolveLensTier`):
+
+- **`local`** lenses (decidable from a single Story's diff) are verified at the
+  two innermost tiers — the write-time distilled checklist (Tier 1) and the
+  maker-blind Story-scope pass (Tier 2). They are **not** re-run at Epic close.
+- **`cumulative`** lenses (only decidable across the Epic's combined diff) and
+  **`global`** lenses (whole-product properties) are verified at Epic close
+  (Tier 3) only.
+- **Risk-routed** lenses run at Epic close regardless of tier, because a
+  high-risk axis (or a route-adding change set) explicitly demands them.
+
+The Epic-close roster (`selectEpicCloseLenses`) is deliberately **slim**: it
+excludes every local-tier change-set lens so the outermost tier — where a fix
+is most expensive — does not re-verify a concern already covered shift-left.
+The Epic-close remediation threshold reflects this (`delivery.epicAudit.autoFixSeverity`
+defaults to `high`): 🟡 Medium code-quality findings are remediated at the
+innermost tiers, not re-remediated at close.
+
 ### Review & feedback loop
 
 When audits produce findings, the orchestrator compiles a structured Markdown

package/.agents/docs/configuration.md

@@ -275,12 +275,14 @@ top-level keys are validation errors.
 | `epicAudit` | No | `object` | — | Nested configuration block. |
 | `epicAudit.maxFixAttempts` | No | `integer` | — | Maximum auto-fix retry attempts per finding in /deliver Phase 4 (epic-audit). 0 disables auto-fix. Default 3. |
 | `epicAudit.maxFixScopeFiles` | No | `integer` | — | Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5. |
+| `epicAudit.autoFixSeverity` | No | `"high"` \| `"medium"` | `"high"` | Severity threshold for on-branch remediation of the Epic-close lens findings walked inside the /deliver Phase 5 code-review pass (Story #4412 folded the former Phase 4 lens walk into that single cumulative-diff pass). `high` (default) routes only 🔴 Critical / 🟠 High lens findings into the host-LLM remediation loop while 🟡 Medium and 🟢 Suggestion findings graduate to follow-up issues (🟡 Medium concerns are already remediated shift-left at the write-time and Story-scope tiers); `medium` opts back into routing 🔴/🟠/🟡 (Mediums batched per lens). Hard cutover — no back-compat flag. |
 | `codeReview` | No | `object` | — | Nested configuration block. |
 | `codeReview.provider` | No | `"native"` \| `"codex"` \| `"security-review"` | `"native"` | Legacy single-adapter selection. ReviewProvider that produces the Finding[] consumed by runCodeReview(). Story #2833 registered `native` (in-process maintainability/lint); Story #2830 added `codex` (invokes `/codex:review` plugin); Story #2871 added `security-review` (shells out to `claude --print /security-review`). When `providers` (chain shape) is set this field is ignored with a warning. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain. |
 | `codeReview.providers[]` | No | `array<object>` | — | Multi-provider chain (Story #2871). When set and non-empty, takes precedence over the legacy `provider` field. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Each item has: name, scopes, optional, manualPrompt, when. |
 | `codeReview.providerConfig` | No | `object` | — | Optional escape hatch for adapter-specific configuration. No documented keys in Epic #2815; reserved so future adapters can be configured without another schema migration. |
 | `codeReview.maxFixAttempts` | No | `integer` | — | Maximum auto-fix retry attempts per finding in /deliver Phase 5 (code-review). 0 disables auto-fix. Default 3. |
 | `codeReview.maxFixScopeFiles` | No | `integer` | — | Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5. |
+| `codeReview.autoFixSeverity` | No | `"high"` \| `"medium"` | `"medium"` | Severity threshold for on-branch remediation in /deliver Phase 5 (code-review). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM focused-fix routing (Mediums batched per lens: one commit per lens, a single validation + rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag. |
 | `retro` | No | `object` | — | Story #3042 (Epic #3019). Operator-tunable retro behaviour. Currently exposes `perfThresholds`, the gates the retro perf-signals classifier uses to decide which signals to surface in the `## Performance Signals` / `## Recommended Follow-Ons` retro sections. |
 | `retro.perfThresholds` | No | `object` | — | Gates for `classifyPerfSignals` (lib/orchestration/retro-perf-heuristics.js). Defaults are 0.6 / 0.4 / 2. |
 | `retro.perfThresholds.utilisation` | No | `number` | — | Per-wave utilisation threshold. Waves whose `utilisation` is strictly below this value emit a `low-utilisation` signal. Default 0.6. |
@@ -306,8 +308,8 @@ top-level keys are validation errors.
 | `preflight.maxClaudeQuotaTokens` | No | `integer` | — | — |
 | `failOnConcurrencyHazards` | No | `boolean` | — | — |
 | `feedbackLoop` | No | `object` | — | Nested configuration block. |
-| `feedbackLoop.codeReviewAutoFile` | No | `boolean` | `true` | When true (default), the Epic finalize listener auto-files non-blocking code-review findings as follow-up issues routed by source classification. Set to false to suppress auto-filing; findings remain accessible in the structured comments on the Epic. |
 | `feedbackLoop.auditResultsAutoFile` | No | `boolean` | `true` | When true (default), the Epic finalize listener auto-files non-blocking audit-results findings as follow-up issues routed by source classification. Set to false to suppress auto-filing; findings remain accessible in the structured comments on the Epic. |
+| `feedbackLoop.retroProposals` | No | `boolean` | `true` | When true (default), the retro auto-files its actionable routed proposals as meta::<framework-gap\|consumer-improvement> + friction::<category> issues via the graduator pre-parsed-findings seam, and the rendered retro sections list the filed issue numbers instead of paste-ready gh command stanzas. Set to false to fall back to the command stanzas. |
 
 <!-- END GENERATED:agentrc -->
 
@@ -749,8 +751,8 @@ per-scope override.
 
 | Field                   | Required | Default | Purpose                                                                                                                                  |
 | ----------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `codeReviewAutoFile`    | No       | `true`  | When `true`, the Epic finalize listener auto-files non-blocking code-review findings as follow-up issues routed by source classification. |
-| `auditResultsAutoFile`  | No       | `true`  | When `true`, the Epic finalize listener auto-files non-blocking audit-results findings as follow-up issues routed by source classification. |
+| `auditResultsAutoFile`  | No       | `true`  | When `true`, the Epic finalize listener auto-files non-blocking findings from the unified `verification-results` comment as follow-up issues routed by source classification. (The former `codeReviewAutoFile` key was retired with its graduator when Story #4411 unified the pass; a config carrying it fails validation.) |
+| `retroProposals`        | No       | `true`  | When `true`, the retro runner auto-files the retro's actionable routed proposals as GitHub follow-up issues (Story #4418). |
 
 ---
 

package/.agents/instructions.md

@@ -139,8 +139,12 @@ technology context is intentionally kept out of `.agentrc.json`.
 ### H. Observability & Friction Telemetry
 
 You MUST log telemetry about any operational difficulty or automation
-opportunity you encounter. Post friction details directly to the relevant
-GitHub Story (or Epic) ticket:
+opportunity you encounter. Friction is a **local NDJSON signal**:
+`diagnose-friction.js` appends one canonical `kind: friction` record to the
+per-Epic/per-Story `signals.ndjson` stream on local disk (validated
+write-time against `signal-event.schema.json`; the retro roll-up reads it
+back). It is not posted to the GitHub ticket at capture time — the retro
+phase is what surfaces the aggregated friction as routed proposals.
 
 - **Command**:
   `node .agents/scripts/diagnose-friction.js --story [STORY_ID] --cmd [FAILED_COMMAND]`
@@ -149,10 +153,12 @@ GitHub Story (or Epic) ticket:
   command failures, or ambiguity requiring explicit self-correction. Also
   after repetitive sequences of commands or boilerplate-heavy steps that
   could be simplified by a workflow or skill.
-- **No-ticket fallback**: If you hit friction outside an Epic/Story
-  loop, write a JSON record to `temp/friction-<timestamp>.json` with the
-  same fields, and mention the file in your final summary so a human can
-  route it later. Do not silently drop the signal.
+- **No-Epic context**: Outside an Epic/Story loop there is no per-Epic
+  stream to anchor to, so the record lands on the **standalone signal
+  stream** (`temp/standalone/stories/story-<sid>/signals.ndjson`) under the
+  same canonical schema. The signal is never silently dropped — a
+  best-effort write failure is logged, not swallowed into a promise of a
+  side-file that no reader consumes.
 
 #### Log Level Control
 
@@ -260,26 +266,37 @@ budget grounds.
 
 1. **Context First:** Before proposing any solution, understand the
    repository's tech stack, historical context, and structure.
-   - **Mandatory Reading (planning & interactive tasks)**: For planning
-     (`/plan`) and interactive tasks, before starting ANY work you MUST read
-     every file listed in `project.docsContextFiles` in `.agentrc.json`.
-     This list is the project's authoritative reference set (architecture,
-     data dictionary, decisions log, patterns, etc.) and replaces any
-     hardcoded filename list. Resolve each entry against
-     `project.paths.docsRoot` (default `docs/`) and skip silently
-     when an entry's file is absent. The decisions log (`decisions.md`) may
-     be either a single-file dated-entry log or an **index** into a
-     `decisions/` ADR directory — both are first-class layouts (see
+   - **Digest-first Reading (planning & interactive tasks, Story #4433)**:
+     For planning (`/plan`) and interactive tasks, read the project's **docs
+     digest** before reading any full doc file — do not read every file
+     listed in `project.docsContextFiles` up front. The epic planning path
+     ensures (generates or reuses) a per-Epic docs digest — a single compact
+     outline (path, byte size, heading outline with line numbers, and the
+     first paragraph under each `##`) built from `project.docsContextFiles`
+     — at `temp/epic-<epicId>/docs-digest.md` (`epic-plan-spec.js
+     --emit-context`, via the shared generator in
+     `.agents/scripts/lib/orchestration/docs-digest.js`; the same file the
+     `/deliver` story sub-agents below already consume). Use the digest to
+     decide which docs bear on the task at hand, then **pull the full file
+     on demand** (jump to the section at the line number the digest names)
+     when a section actually bears on the decision. The decisions log
+     (`decisions.md`) may be either a single-file dated-entry log or an
+     **index** into a `decisions/` ADR directory — both are first-class
+     layouts (see
      [`skills/core/documentation-and-adrs`](skills/core/documentation-and-adrs/SKILL.md)).
-     When it is an index, only the index is the mandatory-read; the
-     per-ADR bodies under `decisions/` are link-followed on demand
-     (index-only by default), not auto-loaded into every task's context.
+     When it is an index, treat the index like any other digested doc —
+     link-follow the per-ADR bodies under `decisions/` on demand, not
+     auto-loaded into every task's context. When no digest exists yet for
+     the task at hand (an ad hoc interactive task with no Epic in scope, or
+     `project.docsContextFiles` unset) there is no mandatory docs read —
+     read a full doc only when the task itself points you at one. This is a
+     hard cutover: there is no read-every-`docsContextFiles`-file branch
+     retained.
    - **Digest-first Reading (`/deliver` story sub-agents)**: A `/deliver`
      Story delivery sub-agent (dispatched via `helpers/epic-deliver-story` or
      `helpers/single-story-deliver`) does **not** re-read the full
      `project.docsContextFiles` set per Story. Instead it reads the **per-Epic
-     docs digest** — a single compact outline (path, byte size, heading
-     outline with line numbers, and the first paragraph under each `##`) that
+     docs digest** — the same file and shape described above — that
      `epic-deliver-prepare.js` writes to
      `temp/epic-<epicId>/docs-digest.md` and the parent threads into the
      child prompt as `docsDigestPath`. Use the digest to decide which docs are
@@ -291,6 +308,19 @@ budget grounds.
      points you at one. This is the hard cutover from the former
      read-every-file-per-Story rule: delivery children no longer ingest the
      whole docs set up front.
+   - **Standalone-Story planning path (`story-plan.js --emit-context`)**:
+     The standalone counterpart to `/plan` for Stories that do not attach
+     to an Epic does not write a `docs-digest.md` file at all — there is
+     no per-Epic directory to anchor one. Instead `buildCorpusContext`
+     (`.agents/scripts/lib/planning-corpus.js`) builds the same compact
+     digest shape in memory and threads it inline as
+     `corpusContext.docsDigest` on the `--emit-context` envelope, next to
+     `corpusContext.relevantSections` (ranked excerpts from existing
+     Epics' Tech Spec sections). Treat `corpusContext.docsDigest` exactly
+     like the file-based digest above — decide relevance from the outline,
+     then pull the full file on demand — the only difference is the
+     delivery mechanism (inline JSON field vs. a temp file path), not the
+     content or the digest-first discipline.
    - **Conditional Reads**: When the task touches UI copy, layout, or
      routing and the corresponding file is present in the project, also
      read `docs/style-guide.md` and `docs/web-routes.md`. Skip both when