@fro.bot/systematic 3.2.2 → 3.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "3.2.2",
+  "version": "3.2.4",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",
@@ -90,8 +90,8 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.4",
     "@earendil-works/pi-coding-agent": "0.80.7",
-    "@opencode-ai/plugin": "1.18.2",
-    "@opencode-ai/sdk": "1.18.2",
+    "@opencode-ai/plugin": "1.18.3",
+    "@opencode-ai/sdk": "1.18.3",
     "@semantic-release/exec": "7.1.0",
     "@types/bun": "latest",
     "@types/js-yaml": "4.0.9",
@@ -101,7 +101,7 @@
     "conventional-changelog-conventionalcommits": "9.3.1",
     "markdownlint-cli": "0.48.0",
     "rimraf": "6.1.3",
-    "semantic-release": "25.0.7",
+    "semantic-release": "25.0.8",
     "semantic-release-export-data": "1.2.0",
     "typebox": "1.3.6",
     "typescript": "6.0.3"

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: