thoth-agents 0.3.3 → 0.3.5

package/skills/plan-reviewer/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: plan-reviewer
+description: Review a ready Accelerated or Full SDD artifact set for execution blockers after the user chooses the optional Oracle plan review. Use only for the pre-implementation plan-review phase; return exact [OKAY] or [REJECT] semantics while keeping final verification separate.
+metadata:
+  author: thoth-agents
+  version: '1.0'
+---
+
+# Plan Reviewer
+
+Review whether an accepted SDD plan can be implemented safely as written. Focus
+on true execution blockers, not stylistic preferences or redesign ideas.
+
+## Activation
+
+Use this skill only after all of these conditions hold:
+
+- The selected route is Accelerated or Full.
+- The route's `ready` validator gate has passed.
+- The user chose `Review plan with Oracle (Recommended)` instead of
+  `Proceed without review`.
+
+Do not activate automatically, and do not use it for Direct work. The user may
+proceed without this review. Skipping it means there is no pre-implementation
+Oracle review; mandatory final Oracle verify still applies.
+
+## Ownership and inputs
+
+Root coordinates the phase and dispatches Oracle. Oracle remains read-only: it
+must not edit source, SDD artifacts, or coordination state. Root persists the
+returned review at `openspec/changes/<change>/plan-review.md` using
+`templates/plan-review.md`.
+
+Review these canonical inputs:
+
+- `spec.md`
+- `plan.md`
+- `tasks.md`
+- an active requirements checklist, when present
+- `openspec/memory/constitution.md`, when governance applies
+
+OpenSpec is the only SDD artifact store. Do not mirror `plan-review.md` or its
+payload into provider memory.
+
+## Review method
+
+Judge the artifact set on five dimensions:
+
+1. Completeness: every in-scope requirement and success criterion maps to work.
+2. Correctness: named files, symbols, commands, and public contracts are real or
+   explicitly created by the plan.
+3. Coherence: artifacts agree on scope, sequencing, dependencies, and ownership.
+4. Buildability: a competent implementer can execute without guessing about
+   critical paths or hidden prerequisites.
+5. Outcome coverage: verification tasks can demonstrate the requested result.
+
+Respect TDD ordering and the repository constitution when they apply. Report
+non-blocking cautions separately so they do not become artificial gates.
+
+## Decision contract
+
+Default to `[OKAY]`. Return `[REJECT]` only when execution is genuinely blocked.
+A rejection contains at most 3 actionable blockers. For each blocker, state why
+it blocks execution and the smallest concrete repair. Preserve the exact
+`[OKAY]` and `[REJECT]` tokens across every harness.
+
+After `[REJECT]`, Root repairs the canonical artifacts and offers the user the
+review-or-proceed choice again. Do not silently approve a changed plan.
+
+## Freshness and persistence
+
+Root computes SHA-256 digests for every reviewed artifact and records them in
+the persisted review. Treat a stored approval as fresh only while every recorded
+digest matches. A stale review has no gate value; rerun it only if the user still
+chooses review.
+
+The persisted artifact records the status, Oracle role, timestamp, route,
+comments, non-blocking notes, blockers, any explicit override, and source
+digests. Oracle returns this payload; Root is the only writer that persists it.
+
+## Handoff
+
+After `[OKAY]`, Root summarizes the approved plan and must ask whether to implement or stop.
+Approval is not implementation authorization. Choosing
+`Proceed without review` at the earlier choice does authorize implementation.
+
+Plan review never replaces mandatory final Oracle verify. Every route still
+requires independent post-implementation verification by a non-writer.
+
+## Output
+
+For an executable plan:
+
+```text
+[OKAY]
+- Brief evidence that the plan is complete, coherent, and executable.
+- Optional non-blocking cautions.
+```
+
+For a blocked plan:
+
+```text
+[REJECT]
+1. <blocker, impact, and smallest repair>
+2. <optional blocker>
+3. <optional blocker>
+```

package/skills/plan-reviewer/templates/plan-review.md

@@ -0,0 +1,65 @@
+---
+schema: thoth-agents/sdd-plan-review/v1
+artifact: plan-review
+change: <change-name>
+gate: oracle-review
+status: "[OKAY|REJECT]"
+reviewer_role: oracle
+reviewed_at: <ISO-8601 timestamp>
+pipeline: <accelerated|full>
+persistence_mode: openspec
+override:
+  occurred: false
+  at: null
+  surface: null
+  context: null
+reviewed_artifacts:
+  - role: spec
+    path: openspec/changes/<change-name>/spec.md
+    required: true
+    sha256: sha256:<digest>
+  - role: plan
+    path: openspec/changes/<change-name>/plan.md
+    required: true
+    sha256: sha256:<digest>
+  - role: tasks
+    path: openspec/changes/<change-name>/tasks.md
+    required: true
+    sha256: sha256:<digest>
+---
+
+# Plan Review: <change title>
+
+**Status**: [OKAY|REJECT]
+
+## Oracle Result
+
+<[OKAY] or [REJECT]>
+
+## Comments
+
+- <coverage and executability evidence>
+
+## Non-Blocking Notes
+
+- None.
+
+## Blockers
+
+- None, or at most 3 actionable blockers with the smallest repair.
+
+## User Override Context
+
+None.
+
+## Source SHA-256
+
+- `openspec/changes/<change-name>/spec.md`: `sha256:<digest>`
+- `openspec/changes/<change-name>/plan.md`: `sha256:<digest>`
+- `openspec/changes/<change-name>/tasks.md`: `sha256:<digest>`
+- Add every active checklist and constitution source reviewed by Oracle.
+
+## Recovery Decision
+
+This result satisfies only optional plan review while all source digests remain
+unchanged. It does not authorize implementation or satisfy final Oracle verify.

package/skills/thoth-constitution/templates/constitution.md

@@ -24,6 +24,7 @@ infrastructure without a current requirement is prohibited.
 
 Delivery MUST use the smallest coherent design that satisfies accepted
 requirements. Non-goals MUST be named, and scope cannot expand silently.
+SDD route selection MUST remain user-owned after an evidence-based recommendation.
 
 ### III. Testable contracts
 
@@ -32,8 +33,7 @@ changes MUST use test-first execution at an agreed public seam when practical.
 
 ### IV. Independent assurance
 
-The implementation writer cannot approve its own work. Analyze and verify MUST
-be performed by an independent read-only reviewer.
+The implementation writer cannot approve its own work. Pre-implementation plan review is optional and user-selected. When selected, it uses an independent read-only reviewer. Every final verify MUST use an independent read-only reviewer.
 
 ### V. Traceable delivery
 

package/skills/thoth-init/SKILL.md

@@ -13,7 +13,7 @@ script by absolute path:
 node "<skill-dir>/scripts/init.mjs" --project <project-root> --harness <opencode|codex|claude> --json
 ```
 
-- OpenCode materializes the four thoth-owned workflow skills under
+- OpenCode materializes the five thoth-owned workflow skills under
   `.agents/skills/`.
 - Codex init creates project governance only. Codex plugin manifests cannot
   install custom agents or global instructions; first run the mandatory

package/skills/thoth-init/scripts/init.mjs

@@ -20,6 +20,7 @@ const OWNED_SKILL_NAMES = [
   'thoth-sdd',
   'thoth-constitution',
   'thoth-archive',
+  'plan-reviewer',
 ];
 
 function parseArgs(argv) {

package/skills/thoth-sdd/SKILL.md

@@ -5,32 +5,35 @@ description: Run thoth-agents Direct, Accelerated, or Full specification-driven
 
 # Thoth SDD
 
-Select the lightest route that preserves correctness:
+Assess the work, recommend the lightest route that preserves correctness, and
+let the user select:
 
 - **Direct**: `implement -> verify`
 - **Accelerated**: `specify -> plan -> tasks -> implement -> verify -> archive`
-- **Full**: `explore -> specify -> plan -> tasks -> analyze -> implement -> verify -> archive`
+- **Full**: `explore -> specify -> plan -> tasks -> implement -> verify -> archive`
 
-Conditional phases are `clarify`, `checklist`, and `converge`. Direct creates no
+Conditional phases are `clarify`, `checklist`, `plan-review`, and `converge`. Direct creates no
 SDD artifacts and may cover multiple documentation or mechanical files when the
 intent is clear and risk is low.
 
 Accelerated is a **fast-forward** route: root writes `spec.md`, `plan.md`, and
-`tasks.md` in one uninterrupted pass, validates structure without a routine user
-pause, and creates optional artifacts only for a concrete risk. Full uses
-phase-by-phase gates because uncertainty or failure cost justifies them.
+`tasks.md` in one uninterrupted pass and creates optional artifacts only for a
+concrete risk. After `ready`, both artifact-backed routes pause once to offer
+`Review plan with Oracle (Recommended)` or `Proceed without review`. Full uses
+separate planning gates because uncertainty or failure cost justifies them.
 
-An explicitly named route wins. A generic request to “use SDD” sets Accelerated
-as the minimum; it does not force Full. User input is requested only for a
-material decision that evidence and safe assumptions cannot resolve.
+An explicitly named route counts as the user's selection. Otherwise assess and
+recommend Direct, Accelerated, or Full, then wait for the user to choose; the
+recommendation is not the decision. A generic request to “use SDD” makes
+Accelerated the minimum recommendation but does not force it.
 
 ## Ownership
 
 - Root owns sequential coordination artifacts, gate execution, and archive.
 - Explorer owns Full-route repository discovery.
 - Designer, quick, deep, or root may implement according to scope.
-- Oracle always owns `analyze` and **every** `verify`. The implementation writer
-  never approves its own work.
+- Oracle owns `plan-review` when the user selects it and **every** `verify`. The
+  implementation writer never approves its own work.
 
 ## Progressive loading
 
@@ -49,7 +52,7 @@ Read only the current phase contract:
 | plan | `references/phases/plan.md` |
 | checklist | `references/phases/checklist.md` |
 | tasks | `references/phases/tasks.md` |
-| analyze | `references/phases/analyze.md` |
+| plan-review | bundled `plan-reviewer` skill |
 | implement | `references/phases/implement.md` |
 | verify | `references/phases/verify.md` |
 | converge | `references/phases/converge.md` |
@@ -66,12 +69,15 @@ node scripts/validate.mjs --change openspec/changes/<feature> --route <accelerat
 - **Accelerated**: `specify`, then `ready` after the fast-forward planning pass,
   then `closeout` after independent verification and an archive report marked
   `READY`.
-- **Full**: `specify`, `plan`, `tasks`, then `ready` before oracle analysis, and
-  `closeout` after independent verification.
+- **Full**: `specify`, `plan`, `tasks`, then `ready` before the optional review
+  choice or implementation, and `closeout` after independent verification.
 - **Checklist**: run only when activated; the later `ready` gate includes it if
   present.
 
-`ready` validates the artifacts needed before analysis/implementation.
+`ready` validates the artifacts needed before the user chooses
+`Review plan with Oracle (Recommended)` or `Proceed without review`. Review
+approval remains separate from implementation confirmation and never satisfies
+final verification.
 `closeout` additionally requires completed tasks, independent oracle PASS,
 complete FR/buildable-SC evidence, an observed PASS or explicit residual RISK
 for every outcome SC, and an archive report ready for the transactional archive

package/plugin/skills/thoth-sdd/references/phases/analyze.md

@@ -1,21 +0,0 @@
-# Analyze contract
-
-**Owner**: oracle (read-only, independent)<br>
-**Applies to**: Full
-
-Review `spec.md`, `plan.md`, `tasks.md`, the constitution, and any activated
-checklist across three separate dimensions:
-
-- **Completeness**: all accepted scope, FRs, buildable SCs, stories, failures,
-  and constraints have downstream coverage.
-- **Correctness**: requirements and technical choices are testable, feasible,
-  and consistent with repository evidence and the constitution.
-- **Coherence**: spec, plan, tasks, dependencies, and verification seams do not
-  contradict or duplicate one another.
-
-Buildable SCs require tasks; outcome SCs require measurable validation intent,
-not fake implementation tasks. Report stable finding IDs with
-CRITICAL/HIGH/MEDIUM/LOW severity, coverage percentages, checklist status, and a
-`ready` or `blocked` verdict. Any CRITICAL finding, constitution violation, or
-FR/buildable SC with zero task coverage blocks implementation. Never edit
-artifacts; root owns remediation.

package/skills/thoth-sdd/references/phases/analyze.md

@@ -1,21 +0,0 @@
-# Analyze contract
-
-**Owner**: oracle (read-only, independent)<br>
-**Applies to**: Full
-
-Review `spec.md`, `plan.md`, `tasks.md`, the constitution, and any activated
-checklist across three separate dimensions:
-
-- **Completeness**: all accepted scope, FRs, buildable SCs, stories, failures,
-  and constraints have downstream coverage.
-- **Correctness**: requirements and technical choices are testable, feasible,
-  and consistent with repository evidence and the constitution.
-- **Coherence**: spec, plan, tasks, dependencies, and verification seams do not
-  contradict or duplicate one another.
-
-Buildable SCs require tasks; outcome SCs require measurable validation intent,
-not fake implementation tasks. Report stable finding IDs with
-CRITICAL/HIGH/MEDIUM/LOW severity, coverage percentages, checklist status, and a
-`ready` or `blocked` verdict. Any CRITICAL finding, constitution violation, or
-FR/buildable SC with zero task coverage blocks implementation. Never edit
-artifacts; root owns remediation.