@fro.bot/systematic 3.11.0 → 3.12.0

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

@@ -10,7 +10,7 @@ You are a systems architect evaluating whether this plan can actually be built a
 
 ## What you check
 
-**"What already exists?"** -- Does the plan acknowledge existing code, services, and infrastructure? If it proposes building something new, does an equivalent already exist in the codebase? Does it assume greenfield when reality is brownfield? This check requires reading the codebase alongside the plan.
+**"What already exists?"** -- Does the plan acknowledge existing code, services, and infrastructure? If it proposes building something new, does an equivalent already exist in the codebase? Does it assume greenfield when reality is brownfield? When the plan carries a Prior-Art Survey, verify that every named candidate resolves to real code, spot-check that its stated ownership matches what the code actually does, and confirm that a `build-new-within-scope` verdict's insufficiency reasons hold. Treat an absence claim as limited to the survey's stated scope and budget, not as repository-wide evidence. If the survey reports an equivalent, does the plan name the corresponding requirement or implementation-unit change? Citing an equivalent under related work without changing the design is a finding. This check requires reading the codebase alongside the plan.
 
 **Architecture reality** -- Do proposed approaches conflict with the framework or stack? Does the plan assume capabilities the infrastructure doesn't have? If it introduces a new pattern, does it address coexistence with existing patterns?
 

package/agents/research/repo-research-analyst.md

@@ -23,6 +23,7 @@ Valid scopes and the phases they control:
 | `conventions` | Documentation and Guidelines Review: contribution guidelines, coding standards, review processes | Documentation Insights |
 | `issues` | GitHub Issue Pattern Analysis: formatting patterns, label conventions, issue structures | Issue Conventions |
 | `templates` | Template Discovery: issue templates, PR templates, RFC templates | Templates Found |
+| `prior-art` | Concern-Anchored Prior-Art Survey: search for what currently handles the concern | Prior-Art Survey |
 
 **Scoping rules:**
 
@@ -150,6 +151,53 @@ This context informs all subsequent research phases -- use it to focus documenta
 
 ---
 
+**Prior-Art Survey (run for `prior-art` scope)**
+
+Run this survey for every software-work concern, including shallow plans. Skip it only when the work is explicitly non-software or mechanical with no behavior change. Scale the survey's depth with plan depth, but do not make existence of the survey conditional on plan depth.
+
+1. Treat the input as a concern, not a proposed solution or design. Restate it in terms of its **trigger**, **effect**, **state**, and **integration boundary** before searching. Do not let a named implementation, component, or desired mechanism substitute for that concern.
+2. Bound the search to a workspace or subtree using the existing Phase 0.1 and 0.1b detection logic above. For a monorepo, use the named workspace or service when the concern identifies one; otherwise report the workspace map and choose the smallest defensible subtree. State a finite search budget before searching, covering the search passes and candidate inspection depth you will use.
+3. Search the bounded scope for source, registrations, tests, schemas, and configuration that currently handle the trigger, effect, state, or integration boundary. Use the concern's synonyms and nearby domain terms, including terms discovered from filenames, symbols, registrations, and schemas.
+4. Collect every plausible candidate before assigning any disposition. For each candidate, describe what it owns in the vocabulary the code itself uses: use its symbols, module names, events, records, states, or boundaries rather than translating it into the request's vocabulary.
+5. Only after the candidate inventory is complete, disposition candidates and identify the strongest evidence. Preserve the stated scope and budget in the result, including whether the budget was exhausted.
+
+The prior-art output must report the concern framing, surveyed workspace or subtree, freshness record, search budget, candidate inventory, and dispositions. Emit exactly one machine-checkable result using `skills/ce-plan/references/prior-art-survey-schema.json` as the contract. Use `schema_version: 1`. The `freshness` object must include at least one of `vcs_reference` (the current VCS reference for the surveyed scope, when available) or `scope_baseline` (a portable digest or compact baseline for the surveyed scope when VCS is unavailable); include both when both are available. Do not replace this record with prose.
+
+```json
+{
+  "schema_version": 1,
+  "verdict": "reuse | extend | build-new-within-scope | unscoped | unresolved",
+  "scope": "<workspace or subtree searched>",
+  "freshness": {
+    "vcs_reference": "<current VCS reference for the surveyed scope, when available>",
+    "scope_baseline": "<portable digest or baseline for the surveyed scope when VCS is unavailable>"
+  },
+  "budget": {
+    "max_search_passes": 3,
+    "max_candidate_inspections": 10,
+    "exhausted": false
+  },
+  "candidates": [
+    {
+      "path_or_symbol": "<repository-relative path or source symbol>",
+      "description": "<what it owns in the code's vocabulary>",
+      "disposition": "reuse | extend | insufficient | undispositioned",
+      "insufficiency_reason": "<required for build-new-within-scope candidates>"
+    }
+  ],
+  "scopes_considered": ["<required for an unscoped verdict>"],
+  "acceptance": {
+    "accepted_by_user": true,
+    "accepted_verdict": "unscoped | unresolved",
+    "reason": "<what the user accepted>"
+  }
+}
+```
+
+Use exactly one verdict. `build-new-within-scope` requires at least one candidate, every candidate must have disposition `insufficient`, and every candidate must include `insufficiency_reason`. `unscoped` requires a non-empty `scopes_considered` list. `unresolved` requires at least one `undispositioned` candidate and must retain every disposition already reached. Include `acceptance` only when a user accepts an `unscoped` or `unresolved` verdict. An empty candidate list is the only representation of absence: keep it alongside the searched `scope` and `budget`, and never claim that no equivalent exists anywhere.
+
+---
+
 **Core Responsibilities:**
 
 1. **Architecture and Structure Analysis**
@@ -190,7 +238,7 @@ This context informs all subsequent research phases -- use it to focus documenta
 2. Start with high-level documentation to understand project context
 3. Progressively drill down into specific areas based on findings
 4. Cross-reference discoveries across different sources
-5. Prioritize official documentation over inferred patterns
+5. Apply authority by claim type: source, tests, registrations, and schemas establish what exists; documentation and history explain why it exists and what constrains it; orientation prose is a lead requiring verification and never establishes absence.
 6. Note any inconsistencies or areas lacking documentation
 
 **Output Format:**
@@ -232,6 +280,18 @@ Structure your findings as:
 - Naming conventions
 - Project-specific practices
 
+### Prior-Art Survey
+- Concern framing: trigger, effect, state, and integration boundary
+- A structured result conforming to `skills/ce-plan/references/prior-art-survey-schema.json`
+- `schema_version: 1` and a `freshness` record with at least one of `vcs_reference` or `scope_baseline`
+- Exactly one verdict: `reuse`, `extend`, `build-new-within-scope`, `unscoped`, or `unresolved`
+- The searched workspace or subtree in `scope`, plus bounded `budget` fields and whether the budget was exhausted
+- A complete `candidates` inventory with each path or symbol, code-vocabulary ownership description, and disposition
+- For `build-new-within-scope`, a non-empty candidate list whose candidates all explain their insufficiency
+- For `unscoped`, a non-empty `scopes_considered` list; for `unresolved`, at least one `undispositioned` candidate while preserving reached dispositions
+- An optional `acceptance` record only when a user accepted an `unscoped` or `unresolved` verdict
+- Absence represented only by the searched scope, budget, and an empty candidate list; never assert an unbounded absence
+
 ### Recommendations
 - How to best align with project conventions
 - Areas needing clarification

package/dist/index.js

@@ -13201,7 +13201,7 @@ var initializePlugin = async ({
       };
     })()
   });
-  return {
+  const hooks = {
     config: configHandler,
     tool: {
       systematic_skill: createSkillTool({
@@ -13271,6 +13271,7 @@ var initializePlugin = async ({
       } catch {}
     }
   };
+  return hooks;
 };
 var SystematicPlugin = async (input) => {
   return initializePlugin(input);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

package/skills/ce-plan/SKILL.md

@@ -226,15 +226,18 @@ Prepare a concise planning context summary (a paragraph or two) to pass as input
 
 Run these agents in parallel:
 
-- Dispatch `systematic:research:repo-research-analyst` — scope: technology, architecture, patterns; pass the planning context summary.
+- Dispatch `systematic:research:repo-research-analyst` — scope: technology, architecture, patterns, prior-art; pass the planning context summary to the technology, architecture, and patterns scopes. For the prior-art scope, pass only the independently stated concern — its trigger, effect, state, and integration boundary — plus the classified plan depth, rather than the planning context summary or proposed solution. Skip the prior-art scope for explicitly non-software planning and mechanical work that changes no behavior; make that exemption decision here at dispatch.
 - Dispatch `systematic:research:learnings-researcher` — pass the planning context summary.
 Collect:
 - Technology stack and versions (used in section 1.2 to make sharper external research decisions)
 - Architectural patterns and conventions to follow
 - Implementation patterns, relevant files, modules, and tests
+- Prior-art survey result: schema version, verdict, surveyed scope and freshness record, bounded budget, candidate ownership and dispositions, and any recorded acceptance
 - AGENTS.md guidance that materially affects the plan, with AGENTS.md used only as compatibility fallback when present
 - Institutional learnings from `docs/solutions/`
 
+When the prior-art scope runs, apply its verdict before continuing planning: an `unscoped` or `unresolved` result stops planning until the scope narrows, the budget rises, or the user explicitly accepts the uncertainty. Record that acceptance in the Prior-Art Survey section. In a run with no user present, either verdict fails the run rather than proceeding.
+
 **Slack context** (opt-in) — never auto-dispatch. Route by condition:
 
 - **Tools available + user asked**: Dispatch `systematic:research:slack-researcher` with the planning context summary in parallel with other Phase 1.1 agents. If the origin document has a Slack context section, pass it verbatim so the researcher focuses on gaps. Include findings in consolidation.
@@ -552,6 +555,43 @@ deepened: YYYY-MM-DD  # optional, set when the confidence check substantively st
 
 - [Relevant external docs or best-practice source, if used]
 
+## Prior-Art Survey
+
+Include this section for every qualifying software-work or behavior-changing plan. Omit it only when Phase 1.1 explicitly applies the non-software or mechanical-no-behavior-change exemption. The section must contain exactly one fenced `json` block, and that block must validate against `references/prior-art-survey-schema.json`. Preserve the survey's schema-conforming structured result, including the schema version, verdict, surveyed scope, freshness record, bounded budget, candidate ownership and dispositions, and the acceptance record when present. A plan containing prose, placeholders, a missing block, multiple blocks, or a malformed/schema-invalid block is not compliant.
+
+Omit `scopes_considered` unless the verdict is `unscoped`, and omit `acceptance` unless the user has accepted an `unscoped` or `unresolved` verdict.
+
+```json
+{
+  "schema_version": 1,
+  "verdict": "reuse | extend | build-new-within-scope | unscoped | unresolved",
+  "scope": "<workspace or subtree searched>",
+  "freshness": {
+    "vcs_reference": "<VCS reference for the surveyed scope, when available>",
+    "scope_baseline": "<portable digest or baseline for the surveyed scope when VCS is unavailable>"
+  },
+  "budget": {
+    "max_search_passes": 1,
+    "max_candidate_inspections": 1,
+    "exhausted": false
+  },
+  "candidates": [
+    {
+      "path_or_symbol": "<repository-relative path or source symbol>",
+      "description": "<what it owns in the code's vocabulary>",
+      "disposition": "reuse | extend | insufficient | undispositioned",
+      "insufficiency_reason": "<required when verdict is build-new-within-scope>"
+    }
+  ],
+  "scopes_considered": ["<required for an unscoped verdict>"],
+  "acceptance": {
+    "accepted_by_user": true,
+    "accepted_verdict": "unscoped | unresolved",
+    "reason": "<what the user accepted and why planning may proceed>"
+  }
+}
+```
+
 ## Key Technical Decisions
 
 - [Decision]: [Rationale]
@@ -697,7 +737,7 @@ For larger `Deep` plans, extend the core template only when useful with sections
 
 Compose the plan using two paired references:
 
-- `references/plan-sections.md` — the section contract. Describes what the plan contains: the outcome the plan must enable for downstream consumers, the hard floor (Summary, Problem Frame, Requirements, KTDs, Implementation Units), the include-when-material catalog (HTD, Scope Boundaries, Open Questions, System-Wide Impact, Risks & Dependencies, Acceptance Examples, Documentation/Operational Notes, Sources & Research), the agency-driven escape hatch (introduce new sections when content warrants), and the ID/content rules.
+- `references/plan-sections.md` — the section contract. Describes what the plan contains: the outcome the plan must enable for downstream consumers, the hard floor (Summary, Problem Frame, Requirements, Prior-Art Survey, KTDs, Implementation Units), the include-when-material catalog (HTD, Scope Boundaries, Open Questions, System-Wide Impact, Risks & Dependencies, Acceptance Examples, Documentation/Operational Notes, Sources & Research), the agency-driven escape hatch (introduce new sections when content warrants), and the ID/content rules.
 - `references/markdown-rendering.md` — how to present the sections in markdown (table-vs-prose by content shape, ID prefix format, diagram rendering, etc.).
 
 The section catalog is the same regardless of plan depth. Format-specific principles live in the rendering reference. The Core Plan Template above (Section 4.2) is the canonical content authority — `plan-sections.md` is a rendering/ordering layer that describes how sections present, not which sections exist.

package/skills/ce-plan/references/plan-sections.md

@@ -19,6 +19,14 @@ A great plan enables three audiences to act:
 
 Sections earn their place by serving one of these audiences. Omit padding.
 
+## Section ordering
+
+Render the `Prior-Art Survey` as a top-level section after `Context & Research` and before `Key Technical Decisions`. Keep it addressable and separate from general research so downstream review and execution checks can locate the result without interpreting surrounding prose. For qualifying software-work or behavior-changing plans, the section is part of the hard floor; omit it only when planning explicitly records the non-software or mechanical-no-behavior-change exemption.
+
+## Prior-Art Survey rendering
+
+The section must contain exactly one fenced `json` block and no alternate survey result in prose or another code block. Parse that block as JSON and validate it against `skills/ce-plan/references/prior-art-survey-schema.json`; a missing, malformed, schema-invalid, or placeholder block is not a survey result. Preserve the contract's field names, including `schema_version`, `verdict`, `scope`, `freshness`, `budget`, and `candidates`. Each candidate must name what it owns in the code's vocabulary and its disposition. Include `scopes_considered` for an `unscoped` verdict and `acceptance` only when the user accepts an `unscoped` or `unresolved` verdict. An `unscoped` or `unresolved` result without that acceptance record remains a planning blocker, not explanatory prose.
+
 ## Decide whether a plan doc is warranted at all
 
 Not every invocation of `ce:plan` should produce a plan document. For

package/skills/ce-plan/references/prior-art-survey-schema.json

@@ -0,0 +1,307 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Prior-Art Survey",
+  "description": "Machine-checkable output contract for a bounded prior-art survey.",
+  "$ref": "#/definitions/survey",
+  "definitions": {
+    "verdict": {
+      "type": "string",
+      "enum": [
+        "reuse",
+        "extend",
+        "build-new-within-scope",
+        "unscoped",
+        "unresolved"
+      ]
+    },
+    "budget": {
+      "type": "object",
+      "required": [
+        "max_search_passes",
+        "max_candidate_inspections",
+        "exhausted"
+      ],
+      "properties": {
+        "max_search_passes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 32,
+          "description": "Maximum number of bounded search passes permitted."
+        },
+        "max_candidate_inspections": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "description": "Maximum number of candidate inspections permitted."
+        },
+        "exhausted": {
+          "type": "boolean",
+          "description": "Whether the stated search budget was exhausted."
+        }
+      },
+      "additionalProperties": false
+    },
+    "freshness": {
+      "type": "object",
+      "properties": {
+        "vcs_reference": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "pattern": "\\S",
+          "description": "VCS revision or equivalent reference for the surveyed scope, when available."
+        },
+        "scope_baseline": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048,
+          "pattern": "\\S",
+          "description": "Portable digest or compact baseline for the surveyed scope when VCS history is unavailable."
+        }
+      },
+      "additionalProperties": false,
+      "anyOf": [
+        {
+          "required": ["vcs_reference"]
+        },
+        {
+          "required": ["scope_baseline"]
+        }
+      ]
+    },
+    "candidate": {
+      "type": "object",
+      "required": ["path_or_symbol", "description", "disposition"],
+      "properties": {
+        "path_or_symbol": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "pattern": "\\S",
+          "description": "Repository-relative path or source symbol identifying the candidate."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500,
+          "pattern": "\\S",
+          "description": "What the candidate owns, described in the code's own vocabulary."
+        },
+        "disposition": {
+          "type": "string",
+          "enum": ["reuse", "extend", "insufficient", "undispositioned"],
+          "description": "The survey's disposition of this candidate."
+        },
+        "insufficiency_reason": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500,
+          "pattern": "\\S",
+          "description": "Why this candidate cannot satisfy the concern within the surveyed scope."
+        }
+      },
+      "additionalProperties": false
+    },
+    "acceptance": {
+      "type": "object",
+      "required": ["accepted_by_user", "accepted_verdict", "reason"],
+      "properties": {
+        "accepted_by_user": {
+          "const": true,
+          "description": "Explicit marker that a user accepted the unresolved survey state."
+        },
+        "accepted_verdict": {
+          "type": "string",
+          "enum": ["unscoped", "unresolved"],
+          "description": "The unscoped or unresolved verdict the user accepted."
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500,
+          "pattern": "\\S",
+          "description": "What the user accepted and why planning may proceed."
+        }
+      },
+      "additionalProperties": false
+    },
+    "survey": {
+      "type": "object",
+      "required": [
+        "schema_version",
+        "verdict",
+        "scope",
+        "freshness",
+        "budget",
+        "candidates"
+      ],
+      "properties": {
+        "schema_version": {
+          "const": 1,
+          "description": "Version discriminator for this survey contract."
+        },
+        "verdict": {
+          "$ref": "#/definitions/verdict"
+        },
+        "scope": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "pattern": "\\S",
+          "description": "Workspace or subtree searched by this survey."
+        },
+        "freshness": {
+          "$ref": "#/definitions/freshness"
+        },
+        "budget": {
+          "$ref": "#/definitions/budget"
+        },
+        "candidates": {
+          "type": "array",
+          "maxItems": 32,
+          "items": {
+            "$ref": "#/definitions/candidate"
+          },
+          "description": "Complete candidate inventory collected before dispositioning. Empty is the only absence representation."
+        },
+        "scopes_considered": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 8,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256,
+            "pattern": "\\S"
+          },
+          "description": "Alternative scopes considered when no defensible survey scope could be selected."
+        },
+        "acceptance": {
+          "$ref": "#/definitions/acceptance"
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "verdict": {
+                "const": "build-new-within-scope"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "candidates": {
+                "minItems": 1,
+                "items": {
+                  "allOf": [
+                    {
+                      "required": ["insufficiency_reason"]
+                    },
+                    {
+                      "properties": {
+                        "disposition": {
+                          "const": "insufficient"
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "verdict": {
+                "const": "unscoped"
+              }
+            }
+          },
+          "then": {
+            "required": ["scopes_considered"]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "verdict": {
+                "const": "unresolved"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "candidates": {
+                "contains": {
+                  "properties": {
+                    "disposition": {
+                      "const": "undispositioned"
+                    }
+                  },
+                  "required": ["disposition"]
+                }
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "required": ["acceptance"]
+          },
+          "then": {
+            "properties": {
+              "verdict": {
+                "enum": ["unscoped", "unresolved"]
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "required": ["verdict", "acceptance"],
+            "properties": {
+              "verdict": {
+                "const": "unscoped"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "acceptance": {
+                "properties": {
+                  "accepted_verdict": {
+                    "const": "unscoped"
+                  }
+                }
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "required": ["verdict", "acceptance"],
+            "properties": {
+              "verdict": {
+                "const": "unresolved"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "acceptance": {
+                "properties": {
+                  "accepted_verdict": {
+                    "const": "unresolved"
+                  }
+                }
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/skills/ce-work/SKILL.md

@@ -53,6 +53,12 @@ Determine how to proceed based on what was provided in `<input_document>`.
    - Check for a `Deferred to Implementation` or `Implementation-Time Unknowns` section — these are questions the planner intentionally left for you to resolve during execution. Note them before starting so they inform your approach rather than surprising you mid-task
    - Check for a `Scope Boundaries` section — these are explicit non-goals. Refer back to them if implementation starts pulling you toward adjacent work
    - Review any references or links provided in the plan
+   - If the plan has no `Prior-Art Survey` section at all, it predates this contract — proceed without rejecting it. Otherwise validate the section before environment setup: it must contain exactly one fenced `json` block, and that block must validate against `skills/ce-plan/references/prior-art-survey-schema.json`. Stop before setup when any of these conditions applies:
+     1. **Empty or non-unique survey block:** the section is present but empty, or contains zero or multiple fenced `json` blocks. Resolve it by rerunning planning and recording exactly one schema-conforming structured survey block.
+     2. **Malformed or schema-invalid survey block:** the sole block is not valid JSON or fails schema validation. Resolve it by replacing the block with one valid survey payload; prose or placeholder values do not satisfy the contract.
+     3. **Unaccepted failure verdict:** the validated verdict is `unscoped` or `unresolved` and the block has no recorded user acceptance for that same verdict. Resolve it by narrowing the scope, increasing the bounded budget, or getting the user to accept the uncertainty and recording matching acceptance.
+     4. **Stale surveyed scope:** the recorded scope has changed since the survey ran. Check only the workspace or subtree in `scope`, not the whole repository. When `freshness.vcs_reference` is present and usable VCS data is available, compare the current VCS reference or scoped diff; otherwise compare the current portable digest/baseline with `freshness.scope_baseline`. If neither comparison can be performed, stop and request a fresh survey or explicit re-baselining rather than assuming the result is fresh. Resolve a stale result by rerunning the survey against the current scope and updating the plan.
+   - When refusing execution for a survey condition, name the condition that fired and the concrete resolution required; do not fail opaquely.
    - If the user explicitly asks for TDD, test-first, or characterization-first execution in this session, honor that request even if the plan has no `Execution note`
    - If anything is unclear or ambiguous, ask clarifying questions now
    - Get user approval to proceed