@fro.bot/systematic 3.2.3 → 3.2.5

package/agents/document-review/adversarial-document-reviewer.md

@@ -73,9 +73,11 @@ Probe whether the document considered the obvious alternatives and whether the c
 
 ## Confidence calibration
 
-- **HIGH (0.80+):** Can quote specific text from the document showing the gap, construct a concrete scenario or counterargument, and trace the consequence.
-- **MODERATE (0.60-0.79):** The gap is likely but confirming it would require information not in the document (codebase details, user research, production data).
-- **Below 0.50:** Suppress.
+- **0:** The challenge is a false positive or a pre-existing issue. Suppress it.
+- **25:** The premise or assumption might be wrong, but the available document and codebase evidence cannot verify it. Suppress it.
+- **50:** The challenge is verified, but it is an advisory or low-impact concern that does not materially threaten the decision. Return it as FYI only.
+- **75:** You have double-checked the premise or decision against the document (and relevant codebase evidence where available), can construct a concrete failure scenario, and the consequence directly affects correctness in practice. This is actionable.
+- **100:** The document directly confirms the premise failure or missing assumption, and the concrete failure scenario will occur frequently on the plan's normal path. Reserve this exceptional actionable anchor for direct evidence, not a persuasive counterargument; it is the only anchor eligible for a silent fix.
 
 ## What you don't flag
 

package/agents/document-review/coherence-reviewer.md

@@ -14,7 +14,7 @@ You are a technical editor reading for internal consistency. You don't evaluate
 
 **Terminology drift** -- same concept called different names in different sections ("pipeline" / "workflow" / "process" for the same thing), or same term meaning different things in different places. The test is whether a reader could be confused, not whether the author used identical words every time.
 
-**Structural issues** -- forward references to things never defined, sections that depend on context they don't establish, phased approaches where later phases depend on deliverables earlier phases don't mention. Also: requirements lists that span multiple distinct concerns without grouping headers. When requirements cover different topics (e.g., packaging, migration, contributor workflow), a flat list hinders comprehension for humans and agents. Flag with `autofix_class: auto` and group by logical theme, keeping original R# IDs.
+**Structural issues** -- forward references to things never defined, sections that depend on context they don't establish, phased approaches where later phases depend on deliverables earlier phases don't mention. Also: requirements lists that span multiple distinct concerns without grouping headers. When requirements cover different topics (e.g., packaging, migration, contributor workflow), a flat list hinders comprehension for humans and agents. Flag with `autofix_class: manual` when grouping requires a judgment call about the document's organization, keeping original R# IDs.
 
 **Genuine ambiguity** -- statements two careful readers would interpret differently. Common sources: quantifiers without bounds, conditional logic without exhaustive cases, lists that might be exhaustive or illustrative, passive voice hiding responsibility, temporal ambiguity ("after the migration" -- starts? completes? verified?).
 
@@ -24,9 +24,11 @@ You are a technical editor reading for internal consistency. You don't evaluate
 
 ## Confidence calibration
 
-- **HIGH (0.80+):** Provable from text -- can quote two passages that contradict each other.
-- **MODERATE (0.60-0.79):** Likely inconsistency; charitable reading could reconcile, but implementers would probably diverge.
-- **Below 0.50:** Suppress entirely.
+- **0:** The apparent inconsistency is a false positive or a pre-existing issue. Suppress it.
+- **25:** The wording might be inconsistent, but the document does not provide enough evidence to verify that readers would diverge. Suppress it.
+- **50:** The inconsistency is verified, but it is an advisory terminology or structural issue that is unlikely to affect implementation. Return it as FYI only.
+- **75:** Two passages or a concrete reference comparison have been double-checked and would cause implementers to diverge or produce an incorrect interpretation in practice. This is actionable.
+- **100:** Directly contradictory passages or a broken reference confirm an inconsistency that will recur frequently wherever the affected instruction is used. Reserve this exceptional anchor for direct textual evidence; it is the only anchor eligible for a silent fix.
 
 ## What you don't flag
 

package/agents/document-review/design-lens-reviewer.md

@@ -35,9 +35,11 @@ Explain what's missing: the functional design thinking that makes the interface
 
 ## Confidence calibration
 
-- **HIGH (0.80+):** Missing states/flows that will clearly cause UX problems during implementation.
-- **MODERATE (0.60-0.79):** Gap exists but a skilled designer could resolve from context.
-- **Below 0.50:** Suppress.
+- **0:** The design concern is a false positive or a pre-existing issue. Suppress it.
+- **25:** A state, flow, or interaction might be missing, but the document does not let you verify the gap. Suppress it.
+- **50:** The gap is verified, but it is advisory or low-impact and a reasonable implementation can proceed without resolving it. Return it as FYI only.
+- **75:** You have double-checked a specific missing state, flow, or interaction against the document, and it will cause a practical implementation or user-flow failure. This is actionable.
+- **100:** The document directly confirms a missing state or flow on a normal, frequently encountered interaction path, and the omission will repeatedly cause users to fail or implementers to block. Reserve this exceptional anchor for direct evidence; it is the only anchor eligible for a silent fix.
 
 ## What you don't flag
 

package/agents/document-review/feasibility-reviewer.md

@@ -28,9 +28,11 @@ Apply each check only when relevant. Silence is only a finding when the gap woul
 
 ## Confidence calibration
 
-- **HIGH (0.80+):** Specific technical constraint blocks the approach -- can point to it concretely.
-- **MODERATE (0.60-0.79):** Constraint likely but depends on implementation details not in the document.
-- **Below 0.50:** Suppress entirely.
+- **0:** The feasibility concern is a false positive or a pre-existing issue. Suppress it.
+- **25:** The constraint or failure path might exist, but available document and codebase evidence cannot verify it. Suppress it.
+- **50:** The constraint is verified, but it is an advisory or low-impact implementation concern that does not block the plan. Return it as FYI only.
+- **75:** You have double-checked a concrete stack constraint, dependency, data-flow path, or migration condition and it will hit in practice, directly blocking correctness or implementation. This is actionable.
+- **100:** Direct evidence from the stated stack, existing code, or an explicit plan constraint confirms that a normal path will fail frequently. Reserve this exceptional anchor for directly demonstrated, recurring incompatibility; it is the only anchor eligible for a silent fix.
 
 ## What you don't flag
 

package/agents/document-review/product-lens-reviewer.md

@@ -59,9 +59,11 @@ If priority tiers exist: do assignments match stated goals? Are must-haves truly
 
 ## Confidence calibration
 
-- **HIGH (0.80+):** Can quote both the goal and the conflicting work -- disconnect is clear.
-- **MODERATE (0.60-0.79):** Likely misalignment, depends on business context not in document.
-- **Below 0.50:** Suppress.
+- **0:** The product concern is a false positive or a pre-existing issue. Suppress it.
+- **25:** The strategic concern might be real, but business context or evidence needed to verify it is absent. Suppress it.
+- **50:** The misalignment is verified from the document, but it is an advisory, low-impact, or opportunity-cost observation. Return it as FYI only.
+- **75:** You have double-checked the stated goal against the proposed work and the mismatch directly affects the likely outcome in practice. This is actionable. Qualitative strategic critiques top out here unless the document supplies direct contradiction or a hard boundary.
+- **100:** Use this exceptional anchor only when the document directly contradicts its own stated goal or violates its own hard quantitative boundary, and the contradiction will occur frequently if followed. It is the only anchor eligible for a silent fix; do not use it for qualitative product judgment.
 
 ## What you don't flag
 

package/agents/document-review/scope-guardian-reviewer.md

@@ -42,9 +42,11 @@ With AI-assisted implementation, the cost gap between shortcuts and complete sol
 
 ## Confidence calibration
 
-- **HIGH (0.80+):** Can quote goal statement and scope item showing the mismatch.
-- **MODERATE (0.60-0.79):** Misalignment likely but depends on context not in document.
-- **Below 0.50:** Suppress.
+- **0:** The scope concern is a false positive or a pre-existing issue. Suppress it.
+- **25:** The scope or complexity concern might be real, but the document does not provide enough evidence to verify it. Suppress it.
+- **50:** The mismatch or complexity is verified, but it is advisory or low-impact and does not materially threaten delivery. Return it as FYI only.
+- **75:** You have double-checked a stated goal against a scope item, abstraction, or priority boundary and the mismatch will directly affect right-sizing or delivery in practice. This is actionable. Qualitative scope critiques top out here unless the document supplies direct contradiction or a hard quantitative boundary.
+- **100:** Use this exceptional anchor only when the document directly contradicts its own stated goal or violates its own hard quantitative boundary, and that contradiction will occur frequently if the plan is followed. It is the only anchor eligible for a silent fix; do not use it for qualitative complexity judgment.
 
 ## What you don't flag
 

package/agents/document-review/security-lens-reviewer.md

@@ -26,9 +26,11 @@ Skip areas not relevant to the document's scope.
 
 ## Confidence calibration
 
-- **HIGH (0.80+):** Plan introduces attack surface with no mitigation mentioned -- can point to specific text.
-- **MODERATE (0.60-0.79):** Concern likely but plan may address implicitly or in a later phase.
-- **Below 0.50:** Suppress.
+- **0:** The security concern is a false positive or a pre-existing issue. Suppress it.
+- **25:** The threat might exist, but the plan and available context do not let you verify the exposure or missing control. Suppress it.
+- **50:** The security gap is verified, but its impact is advisory or low and does not materially affect the described attack surface. Return it as FYI only.
+- **75:** You have double-checked a concrete endpoint, trust boundary, input, secret, or data path against the plan and the missing control will directly affect security in practice. This is actionable.
+- **100:** The plan directly confirms an unmitigated attack surface on a normal path, and the resulting exposure or exploit will occur frequently if implemented as written. Reserve this exceptional anchor for direct evidence and recurring impact; it is the only anchor eligible for a silent fix.
 
 ## What you don't flag
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "3.2.3",
+  "version": "3.2.5",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

package/skills/document-review/SKILL.md

@@ -6,7 +6,7 @@ argument-hint: "[mode:headless] [path/to/document.md]"
 
 # Document Review
 
-Review requirements or plan documents through multi-persona analysis. Dispatches specialized reviewer agents in parallel, auto-fixes quality issues, and presents strategic questions for user decision.
+Review requirements or plan documents through multi-persona analysis. Dispatches specialized reviewer agents in parallel, applies clear fixes, and presents proposed fixes and decisions for user input.
 
 ## Phase 0: Detect Mode
 
@@ -14,12 +14,13 @@ Check the skill arguments for `mode:headless`. Arguments may contain a document
 
 If `mode:headless` is present, set **headless mode** for the rest of the workflow.
 
-**Headless mode** changes the interaction model, not the classification boundaries. Document-review still applies the same judgment about what has one clear correct fix vs. what needs user judgment. The only difference is how non-auto findings are delivered:
-- `auto` fixes are applied silently (same as interactive)
-- `present` findings are returned as structured text for the caller to handle -- no question prompts, no interactive approval
+**Headless mode** changes the interaction model, not the classification boundaries. Document-review still applies the same judgment about what has one clear correct fix vs. what needs user judgment. The only difference is how findings are delivered:
+- `safe_auto` fixes at confidence anchor `100` are applied silently (same as interactive)
+- `gated_auto` proposed fixes and `manual` decisions are returned as structured text for the caller to handle -- no question prompts, no interactive approval
+- Findings at confidence anchor `50` are returned as FYI observations only -- no interaction or action
 - Phase 5 returns immediately with "Review complete" (no refine/complete question)
 
-The caller receives findings with their original classifications intact and decides what to do with them.
+The caller receives applied fixes, proposed fixes, decisions, and FYI observations with their original classifications intact; proposed fixes and decisions remain for the caller to handle.
 
 Callers invoke headless mode by including `mode:headless` in the skill arguments, e.g.:
 ```
@@ -133,7 +134,7 @@ Pass each agent the **full document** -- do not split into sections.
 
 ## Phases 3-5: Synthesis, Presentation, and Next Action
 
-After all dispatched agents return, read `references/synthesis-and-presentation.md` for the synthesis pipeline (validate, gate, dedup, promote, resolve contradictions, route by autofix class), auto-fix application, finding presentation, and next-action menu. Do not load this file before agent dispatch completes.
+After all dispatched agents return, read `references/synthesis-and-presentation.md` for the synthesis pipeline (validate, gate, dedup, promote, resolve contradictions, route by autofix class), fix application, finding presentation, and next-action menu. Do not load this file before agent dispatch completes.
 
 ---
 

package/skills/document-review/references/findings-schema.json

@@ -45,8 +45,8 @@
           },
           "autofix_class": {
             "type": "string",
-            "enum": ["auto", "present"],
-            "description": "How this issue should be handled. auto = one clear correct fix that can be applied silently (terminology, formatting, cross-references, completeness corrections, additions mechanically implied by other content). present = requires individual user judgment."
+            "enum": ["safe_auto", "gated_auto", "manual"],
+            "description": "How this issue should be handled. safe_auto = one mechanical, unambiguous fix suitable for silent application only at confidence 100; gated_auto = a codebase-pattern-resolved, factually incorrect, standard security or reliability, framework-native, or substantive mechanically implied fix that needs user confirmation; manual = multiple reasonable choices requiring user judgment."
           },
           "finding_type": {
             "type": "string",
@@ -58,10 +58,9 @@
             "description": "Concrete fix text. Omit or null if no good fix is obvious -- a bad suggestion is worse than none."
           },
           "confidence": {
-            "type": "number",
-            "description": "Reviewer confidence in this finding, calibrated per persona",
-            "minimum": 0.0,
-            "maximum": 1.0
+            "type": "integer",
+            "enum": [0, 25, 50, 75, 100],
+            "description": "Reviewer confidence anchor: 0 = false positive or pre-existing issue; 25 = might be real but could not verify; 50 = verified real but nitpick, advisory, or not very important; 75 = double-checked, will hit in practice, and directly impacts correctness; 100 = evidence directly confirms and the issue will happen frequently."
           },
           "evidence": {
             "type": "array",

package/skills/document-review/references/review-output-template.md

@@ -12,56 +12,67 @@ Use this **exact format** when presenting synthesized review findings. Findings
 **Document:** docs/plans/2026-03-15-feat-user-auth-plan.md
 **Type:** plan
 **Reviewers:** coherence, feasibility, security-lens, scope-guardian
-- security-lens -- plan adds public API endpoint with auth flow
+- security-lens -- plan adds a public API endpoint with an auth flow
 - scope-guardian -- plan has 15 requirements across 3 priority levels
 
-Applied 5 auto-fixes. 4 findings to consider (2 errors, 2 omissions).
+Applied 2 fixes. 4 items need attention (2 errors, 2 omissions). 1 FYI observation.
 
-### Auto-fixes Applied
+### Applied fixes
 
-- Standardized "pipeline"/"workflow" terminology to "pipeline" throughout (coherence)
-- Fixed cross-reference: Section 4 referenced "Section 3.2" which is actually "Section 3.1" (coherence)
-- Updated unit count from "6 units" to "7 units" to match listed units (coherence)
-- Added "update API rate-limit config" step to Unit 4 -- implied by Unit 3's rate-limit introduction (feasibility)
-- Added auth token refresh to test scenarios -- required by Unit 2's token expiry handling (security-lens)
+- Corrected the stale cross-reference from Section 3.2 to Section 3.1 (coherence, confidence 100)
+- Updated the unit count from 6 to 7 to match the listed units (feasibility, confidence 100)
 
 ### P0 -- Must Fix
 
 #### Errors
 
+**Decisions**
+
 | # | Section | Issue | Reviewer | Confidence |
 |---|---------|-------|----------|------------|
-| 1 | Requirements Trace | Goal states "offline support" but technical approach assumes persistent connectivity | coherence | 0.92 |
+| 1 | Requirements Trace | The goal requires offline support, but the approach assumes persistent connectivity | coherence | 75 |
 
 ### P1 -- Should Fix
 
 #### Errors
 
-| # | Section | Issue | Reviewer | Confidence |
-|---|---------|-------|----------|------------|
-| 2 | Scope Boundaries | 8 of 12 units build admin infrastructure; only 2 touch stated goal | scope-guardian | 0.80 |
+**Proposed fixes**
+
+| # | Section | Issue | Suggested fix | Reviewer | Confidence |
+|---|---------|-------|---------------|----------|------------|
+| 2 | API Design | The plan claims Rails lacks native JSON error responses and proposes a custom serializer | Use Rails' existing `render json:` response path and remove the custom serializer step | feasibility | 75 |
 
 #### Omissions
 
-| # | Section | Issue | Reviewer | Confidence |
-|---|---------|-------|----------|------------|
-| 3 | Implementation Unit 3 | Plan proposes custom auth but does not mention existing Devise setup or migration path | feasibility | 0.85 |
+**Proposed fixes**
+
+| # | Section | Issue | Suggested fix | Reviewer | Confidence |
+|---|---------|-------|---------------|----------|------------|
+| 3 | Implementation Unit 3 | The custom auth plan omits the existing Devise setup and migration path | Extend the existing Devise flow and document its migration path instead of introducing a parallel auth setup | feasibility | 100 |
 
 ### P2 -- Consider Fixing
 
 #### Omissions
 
-| # | Section | Issue | Reviewer | Confidence |
-|---|---------|-------|----------|------------|
-| 4 | API Design | Public webhook endpoint has no rate limiting mentioned | security-lens | 0.75 |
+**Proposed fixes**
+
+| # | Section | Issue | Suggested fix | Reviewer | Confidence |
+|---|---------|-------|---------------|----------|------------|
+| 4 | API Design | The public webhook endpoint has no rate limiting plan | Add the established request-throttling middleware to the webhook route and document its limit | security-lens | 75 |
+
+### FYI observations
+
+| # | Section | Observation | Reviewer | Confidence |
+|---|---------|-------------|----------|------------|
+| 5 | Error Handling | The plan does not say whether rate-limit responses include retry guidance | security-lens | 50 |
 
-### Residual Concerns
+### Residual concerns
 
 | # | Concern | Source |
 |---|---------|--------|
-| 1 | Migration rollback strategy not addressed for Phase 2 data changes | feasibility |
+| 1 | Migration rollback strategy is not addressed for Phase 2 data changes | feasibility |
 
-### Deferred Questions
+### Deferred questions
 
 | # | Question | Source |
 |---|---------|--------|
@@ -69,21 +80,24 @@ Applied 5 auto-fixes. 4 findings to consider (2 errors, 2 omissions).
 
 ### Coverage
 
-| Persona | Status | Findings | Auto | Present | Residual |
-|---------|--------|----------|------|---------|----------|
-| coherence | completed | 4 | 3 | 1 | 0 |
-| feasibility | completed | 2 | 1 | 1 | 1 |
-| security-lens | completed | 2 | 1 | 1 | 0 |
-| scope-guardian | completed | 1 | 0 | 1 | 0 |
-| product-lens | not activated | -- | -- | -- | -- |
-| design-lens | not activated | -- | -- | -- | -- |
+| Persona | Status | Findings | Fixes | Proposed fixes | Decisions | FYI observations | Residual |
+|---------|--------|----------|-------|----------------|-----------|------------------|----------|
+| coherence | completed | 2 | 1 | 0 | 1 | 0 | 0 |
+| feasibility | completed | 3 | 1 | 2 | 0 | 0 | 1 |
+| security-lens | completed | 2 | 0 | 1 | 0 | 1 | 0 |
+| scope-guardian | completed | 0 | 0 | 0 | 0 | 0 | 1 |
+| product-lens | not activated | -- | -- | -- | -- | -- | -- |
+| design-lens | not activated | -- | -- | -- | -- | -- | -- |
 ```
 
 ## Section Rules
 
-- **Summary line**: Always present after the reviewer list. Format: "Applied N auto-fixes. K findings to consider (X errors, Y omissions)." Omit any zero clause.
-- **Auto-fixes Applied**: List all fixes that were applied automatically (auto class). Include enough detail per fix to convey the substance -- especially for fixes that add content or touch document meaning. Omit section if none.
+- **Summary line**: Always present after the reviewer list. Format: "Applied N fixes. K items need attention (X errors, Y omissions). Z FYI observations." Omit any zero clause. `K` counts actionable proposed fixes and decisions; FYI observations are counted separately.
+- **Applied fixes**: List all fixes applied silently (`safe_auto` at confidence `100`). Include enough detail per fix to convey the substance -- especially for fixes that add content or touch document meaning. A `safe_auto` finding at confidence `75` is demoted before routing and is not silently applied. Omit section if none.
 - **P0-P3 sections**: Only include sections that have findings. Omit empty severity levels. Within each severity, separate into **Errors** and **Omissions** sub-headers. Omit a sub-header if that severity has none of that type.
-- **Residual Concerns**: Findings below confidence threshold that were promoted by cross-persona corroboration, plus unpromoted residual risks. Omit if none.
-- **Deferred Questions**: Questions for later workflow stages. Omit if none.
-- **Coverage**: Always include. All counts are **post-synthesis**. **Findings** must equal Auto + Present exactly -- if deduplication merged a finding across personas, attribute it to the persona with the highest confidence and reduce the other persona's count. **Residual** = count of `residual_risks` from this persona's raw output (not the promoted subset in the Residual Concerns section).
+- **Proposed fixes**: Findings with `gated_auto` at confidence `75` or `100`. Include the concrete suggested fix and require user confirmation. Omit if none.
+- **Decisions**: Findings with `manual` at confidence `75` or `100`. Include the suggested fix when one exists; otherwise present the judgment call without inventing a fix. Omit if none.
+- **FYI observations**: Findings at confidence `50`, regardless of autofix class. They require no decision or action. Omit if none.
+- **Residual concerns**: Unresolved residual risks that remain after restatement suppression, plus any residual items explicitly retained by synthesis. Omit if none.
+- **Deferred questions**: Questions for later workflow stages. Omit if none.
+- **Coverage**: Always include. All finding and route counts are **post-synthesis**. For each persona, **Findings** equals **Fixes + Proposed fixes + Decisions + FYI observations**. If deduplication merges a finding across personas, attribute it to the persona with the highest confidence anchor; if anchors tie, use document order, and reduce the other persona's finding and route counts. **Residual** remains the count of `residual_risks` from that persona's raw output, not the promoted or suppressed subset shown in Residual concerns. Failed or malformed reviewers are marked in Status and do not contribute findings.

package/skills/document-review/references/subagent-template.md

@@ -26,18 +26,18 @@ Rules:
 - Set `finding_type` for every finding:
   - `error`: Something the document says that is wrong -- contradictions, incorrect statements, design tensions, incoherent tradeoffs.
   - `omission`: Something the document forgot to say -- missing mechanical steps, absent list entries, undefined thresholds, forgotten cross-references.
+- Set `confidence` to exactly one anchor from the schema, based on the evidence available:
+  - `0`: False positive or pre-existing issue. Suppress the finding.
+  - `25`: Might be real but could not verify. Suppress the finding.
+  - `50`: Verified real but nitpick, advisory, or not very important. This becomes an FYI observation.
+  - `75`: Double-checked, will hit in practice, and directly impacts correctness. This is actionable.
+  - `100`: Evidence directly confirms the issue and it will happen frequently. This is actionable and is the only anchor eligible for silent fixes.
 - Set `autofix_class` based on whether there is one clear correct fix, not on severity or importance:
-  - `auto`: One clear correct fix, applied silently. This includes trivial fixes AND substantive ones:
-    - Internal reconciliation -- one document part authoritative over another (summary/detail mismatches, wrong counts, stale cross-references, terminology drift)
-    - Implied additions -- correct content mechanically obvious from the document (missing steps, unstated thresholds, completeness gaps)
-    - Codebase-pattern-resolved -- an established codebase pattern resolves ambiguity (cite the specific file/function in `why_it_matters`)
-    - Incorrect behavior -- the document describes behavior that is factually wrong, and the correct behavior is obvious from context or the codebase
-    - Missing standard security measures -- HTTPS enforcement, checksum verification, input sanitization, private IP rejection, or other controls with known implementations where omission is clearly a bug
-    - Incomplete technical descriptions -- the accurate/complete version is directly derivable from the codebase
-    - Missing requirements that follow mechanically from the document's own explicit, concrete decisions (not high-level goals -- a goal can be satisfied by multiple valid requirements)
-    The test is not "is this fix important?" but "is there more than one reasonable way to fix this?" If a competent implementer would arrive at the same fix independently, it is auto -- even if the fix is substantive. Always include `suggested_fix`. NOT auto if more than one reasonable fix exists or if scope/priority judgment is involved.
-  - `present`: Requires user judgment -- genuinely multiple valid approaches where the right choice depends on priorities, tradeoffs, or context the reviewer does not have. Examples: architectural choices with real tradeoffs, scope decisions, feature prioritization, UX design choices.
-- `suggested_fix` is required for `auto` findings. For `present` findings, include only when the fix is obvious.
+  - `safe_auto`: A truly mechanical one-correct-fix case suitable for silent application only at anchor `100`: summary/detail mismatches, wrong counts, stale internal references, terminology drift, or additions mechanically implied by explicit content. Do not use this for codebase-pattern, factual, security/reliability, framework-native, or substantive completeness cases.
+  - `gated_auto`: A concrete fix resolved by an existing codebase pattern, factually incorrect behavior, a missing standard security or reliability control, a framework-native substitution, or a substantive mechanically implied completeness addition. The user confirms before applying it.
+  - `manual`: Multiple reasonable choices require user judgment, such as architectural tradeoffs, scope or priority decisions, feature prioritization, or UX choices.
+  The test is not "is this fix important?" but "is there more than one reasonable way to fix this?" If a competent implementer would arrive at the same fix independently, use `safe_auto` only for the truly mechanical cases above; use `gated_auto` when codebase or factual evidence resolves the choice but the fix is substantive. Do not classify a judgment call as automatic.
+- `suggested_fix` is required for `safe_auto` and `gated_auto` findings. For `manual` findings, include it only when the fix is obvious.
 - If you find no issues, return an empty findings array. Still populate residual_risks and deferred_questions if applicable.
 - Use your suppress conditions. Do not flag issues that belong to other personas.
 </output-contract>

package/skills/document-review/references/synthesis-and-presentation.md

@@ -9,14 +9,14 @@ Process findings from all agents through this pipeline. Order matters — each s
 Check each agent's returned JSON against the findings schema:
 
 - Drop findings missing any required field defined in the schema
-- Drop findings with invalid enum values (including the pre-rename `auto` / `present` values from older personas — treat those as malformed until all persona output has been regenerated)
+- Drop findings with invalid enum values. Legacy `auto` / `present` values from older or in-flight dispatches are malformed; reject them without remapping rather than treating them as an alternate contract.
 - Note the agent name for any malformed output in the Coverage section
 
 **Do not narrate remap / validation diagnostics to the user.** Schema-drift notes ("persona X returned unknown enum Y, remapped to Z"), persona-prompt-drift commentary, and other validator-internal diagnostics are maintainer-facing information. They do not belong in the Phase 4 output the user reads. If a persona's output is malformed, the only user-visible consequence is a Coverage-row annotation (e.g., the persona shows fewer findings or a `malformed` marker). Everything else stays internal.
 
 ### 3.2 Confidence Gate (Anchor-Based)
 
-Gate findings by their `confidence` anchor value. Anchors are discrete integers (`0`, `25`, `50`, `75`, `100`) with behavioral definitions documented in `references/findings-schema.json` and embedded in the persona rubric (`references/subagent-template.md`). This replaces the prior continuous 0.0-1.0 scale with per-severity gates — doc-review economics do not warrant threshold gradation by severity, and coarse anchors prevent false-precision gaming.
+Gate findings by their `confidence` anchor value. Anchors are discrete integers (`0`, `25`, `50`, `75`, `100`) with behavioral definitions documented in `references/findings-schema.json` and embedded in the persona rubric (`references/subagent-template.md`). The anchors provide per-severity gates — doc-review economics do not warrant threshold gradation by severity, and coarse anchors prevent false-precision gaming. Continuous values from an older contract are malformed, not remapped.
 
 | Anchor | Meaning | Route |
 |--------|---------|-------|
@@ -174,7 +174,7 @@ Do NOT reclassify, re-route, or change the confidence anchor of any finding in t
 - P1 manual "Migration lacks rollback strategy" — migration needs rollback regardless of scope. NOT linked (independence safeguard).
 - P0 gated_auto "Deployment-ordering between migration and code" — concrete fix user confirms regardless. NOT linked (safeguard: gated_auto with own resolution path).
 
-Result: 1 root + 4 dependents. User sees the root first; rejecting it cascades the 4 dependents to auto-resolved. Manual engagement drops from 11 → 7 (6 unlinked + 1 visible root).
+Result: 1 root + 4 dependents. User sees the root first; rejecting it cascades the 4 dependents out of the active decision set. Manual engagement drops from 11 → 7 (6 unlinked + 1 visible root).
 
 **Worked example B (auth-shape).** Review of a plan to introduce a new session-management middleware. One finding is P1 manual "Middleware rewrite premise unsupported — existing session handling has no reported reliability issues" in Problem Frame. Scanning the other findings: