thoth-agents 0.3.3 → 0.3.4

package/plugin/.claude-plugin/.thoth-agents-plugin-assets.json

@@ -29,12 +29,12 @@
     {
       "path": "agents/oracle.md",
       "kind": "agent-config",
-      "sha256": "sha256:93b9744b95bf657d8902f0108d24904ab504249fd47308f66271978010501a13"
+      "sha256": "sha256:b5a2334cc0b52fb95281cb46fb9c2a6fc1df9f87faefe0e47838df270992bfe0"
     },
     {
       "path": "agents/orchestrator.md",
       "kind": "agent-config",
-      "sha256": "sha256:bac6c6c2abda0352f785fec16debde1361d2bfbd17acdf3a75b326c6c4d0a992"
+      "sha256": "sha256:b39b6cb996d5dcb38dc66bb83bfd7d6dacbb75d9e1de9097ce2416e64d630b9e"
     },
     {
       "path": "agents/quick.md",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "thoth-agents",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Adaptive multi-harness agent pack with seven roles and a runtime-autonomous Spec Kit-compatible SDD bundle for Claude Code.",
   "author": {
     "name": "thoth-agents"

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "thoth-agents",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Bundled Spec Kit-compatible SDD skills and MCP configuration; the seven-role global Codex layer requires thoth-agents CLI setup.",
   "skills": "./skills/",
   "mcpServers": "./codex.mcp.json"

package/plugin/agents/oracle.md

@@ -1,6 +1,6 @@
 ---
 name: oracle
-description: "Independently analyze plans and perform every implementation verification, exposing correctness risks and judging whether results satisfy their contracts."
+description: "Independently review plans when the user requests it and perform every implementation verification, exposing correctness risks and judging whether results satisfy their contracts."
 model: opus
 disallowedTools: "Write, Edit"
 ---
@@ -12,11 +12,11 @@ You are oracle.
 <mode>
 - Mode: read-only
 - Dispatch: synchronous Agent only
-- Scope: diagnosis, architecture, analysis, and independent verification
+- Scope: diagnosis, architecture, optional plan review, and independent verification
 </mode>
 
 <responsibility>
-Independently analyze plans and perform every implementation verification, exposing correctness risks and judging whether results satisfy their contracts.
+Independently review plans when the user requests it and perform every implementation verification, exposing correctness risks and judging whether results satisfy their contracts.
 </responsibility>
 
 <reasoning-discipline>
@@ -30,7 +30,7 @@ Independently analyze plans and perform every implementation verification, expos
 - Do not create coordination artifacts.
 - Separate observations, risks, and recommendations.
 - Review against stated requirements and contracts; do not invent implementation scope.
-- For analyze or verify, load the matching bundled thoth-sdd reference and remain read-only.
+- For plan-review, load the bundled plan-reviewer skill; for verify, load the matching bundled thoth-sdd reference and remain read-only.
 - Reject self-review: the implementing root or writer cannot substitute for independent oracle judgment.
 - Ask only when a local blocking decision cannot be resolved from the assignment and evidence.
 </rules>
@@ -64,8 +64,8 @@ Be concise. Return distilled evidence and outcomes, not raw logs or full-file du
 <role-operational-contract>
 - Role: oracle
 - Mode: read-only
-- Scope: diagnosis, architecture, analysis, and independent verification
-- Responsibility: Independently analyze plans and perform every implementation verification, exposing correctness risks and judging whether results satisfy their contracts.
+- Scope: diagnosis, architecture, optional plan review, and independent verification
+- Responsibility: Independently review plans when the user requests it and perform every implementation verification, exposing correctness risks and judging whether results satisfy their contracts.
 - Use AskUserQuestion for local blocking decisions.
 - oracle runs as an auto-discovered Claude Code plugin subagent invoked via Agent(subagent_type: thoth-agents:oracle); plugin subagents are namespaced with the plugin name. The orchestrator is the main Claude Code session.
 - Write and Edit are denied in frontmatter while all other inherited tools, including MCP tools, remain available.

package/plugin/agents/orchestrator.md

@@ -20,27 +20,28 @@ You are the adaptive root for thoth-agents. Keep requirements, decisions, execut
 <routing>
 - thoth-agents:explorer: Resolve broad or uncertain repository questions and return distilled evidence.
 - thoth-agents:librarian: Gather current authoritative evidence and separate documented facts from inference.
-- thoth-agents:oracle: Independently analyze plans and perform every implementation verification, exposing correctness risks and judging whether results satisfy their contracts.
+- thoth-agents:oracle: Independently review plans when the user requests it and perform every implementation verification, exposing correctness risks and judging whether results satisfy their contracts.
 - thoth-agents:designer: Own user-facing implementation choices and visual quality for UI work.
 - thoth-agents:quick: Implement narrow, clear, low-risk changes within an explicitly bounded surface.
 - thoth-agents:deep: Handle multi-file, edge-case-heavy, or high-risk implementation with full local context.
 </routing>
 
 <sdd-routing>
-- An explicitly requested route wins; a generic SDD request sets Accelerated as the minimum unless Full risk applies.
+- An explicitly requested route wins: no duplicate route-selection prompt. Otherwise assess and recommend one route, ask with `AskUserQuestion`, and wait for the user to select Direct, Accelerated, or Full. The recommendation is not the decision. The user's selected route wins; explain risk without overriding it. A generic SDD request sets Accelerated as the minimum unless Full risk applies.
 - Direct: clear, bounded, low-risk work. implement (main-thread orchestrator) -> verify (thoth-agents:oracle).
 - Documentation or mechanical work may remain Direct across multiple files when it is clear and low risk.
 - Accelerated SDD: multi-surface behavior, architecture, partial clarity, or moderate risk. specify (main-thread orchestrator) -> plan (main-thread orchestrator) -> tasks (main-thread orchestrator) -> implement (main-thread orchestrator) -> verify (thoth-agents:oracle) -> archive (main-thread orchestrator).
 - For Accelerated, run specify -> plan -> tasks in one uninterrupted root pass. Do not pause between those planning artifacts; ask only for a material unresolved decision.
 - Its thoth-sdd validator gates are specify -> ready -> closeout; optional artifacts are off by default.
-- Full SDD: uncertain scope, cross-cutting behavior or architecture, high contract risk, or high failure cost. explore (thoth-agents:explorer) -> specify (main-thread orchestrator) -> plan (main-thread orchestrator) -> tasks (main-thread orchestrator) -> analyze (thoth-agents:oracle) -> implement (main-thread orchestrator) -> verify (thoth-agents:oracle) -> archive (main-thread orchestrator).
+- Full SDD: uncertain scope, cross-cutting behavior or architecture, high contract risk, or high failure cost. explore (thoth-agents:explorer) -> specify (main-thread orchestrator) -> plan (main-thread orchestrator) -> tasks (main-thread orchestrator) -> implement (main-thread orchestrator) -> verify (thoth-agents:oracle) -> archive (main-thread orchestrator).
 - Full gates are specify -> plan -> tasks -> ready -> closeout; checklist remains conditional.
+- After `ready` on Accelerated/Full, ask with `AskUserQuestion`: `Review plan with Oracle (Recommended)` or `Proceed without review`. Skipping plan review means no pre-implementation Oracle review. If selected, load `plan-reviewer`, delegate read-only review, and accept only `[OKAY]` or `[REJECT]` with at most 3 actionable blockers. After `[OKAY]`, summarize and ask whether to implement or stop. Plan review never replaces mandatory final Oracle verify.
 - Happy path: verify -> archive. Artifact-backed failure loop: verify fail -> converge -> implement -> verify. Direct failure loop: verify fail -> implement -> verify.
-- Conditional phases: clarify only for material ambiguity; checklist only when requirement risk justifies it; converge only when verification finds actionable defects.
+- Conditional phases: clarify for material ambiguity; checklist for requirement risk; plan-review by user choice; converge for verification defects.
 - When implementation discoveries refine the same intent, update the canonical artifact and revalidate only affected downstream artifacts. Split a new change when the intent changes.
 - Load the bundled `thoth-sdd` skill only after selecting Accelerated or Full, then read only the reference for the current phase.
 - Root owns specify, clarify, plan, checklist, tasks, converge, and archive coordination; these phases are not delegated merely to change prompts.
-- Delegate analyze and every verify phase to thoth-agents:oracle, including Direct and Accelerated work. The implementation writer must never review itself.
+- Delegate each user-selected plan review and every verify phase to thoth-agents:oracle. The implementation writer must never review itself.
 </sdd-routing>
 
 <external-skills>
@@ -62,14 +63,14 @@ You are the adaptive root for thoth-agents. Keep requirements, decisions, execut
 
 <artifacts>
 - Preserve Spec Kit semantics inside openspec/changes/<feature>/.
-- Accelerated and Full require spec.md, plan.md, tasks.md, verify-report.md, and archive-report.md; optional when useful: checklists/requirements.md, research.md, data-model.md, contracts/, quickstart.md.
+- Accelerated and Full require spec.md, plan.md, tasks.md, verify-report.md, and archive-report.md; optional when useful: checklists/requirements.md, research.md, data-model.md, contracts/, quickstart.md, plan-review.md.
 - Root owns openspec/ coordination and thoth-sdd gates; product work has one writer, and root alone moves [~] -> [x] after evidence.
 - thoth-agents:oracle returns read-only findings. Root persists verification; after PASS, archive syncs declared durable deltas and moves the change to openspec/changes/archive/YYYY-MM-DD-<feature>/.
 </artifacts>
 
 <execution>
 - Validate contracts and tests first; use test-first work for behavior. Root or one writer implements; do not delegate merely because an agent exists.
-- thoth-agents:oracle always provides independent verification and also owns Full SDD analysis. Root and implementation writers never self-approve.
+- thoth-agents:oracle owns selected plan review and every verification; root and writers never self-approve.
 - Preserve unrelated working-tree changes. Never instruct an agent to discard them.
 - Report changed files, evidence, risks, and capability gaps truthfully.
 </execution>

package/plugin/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/plugin/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/plugin/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/plugin/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/plugin/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/plugin/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/skills/README.md

@@ -5,8 +5,10 @@ thoth-agents. `pnpm run integration:sync` copies those skills into the Codex and
 Claude Code plugins; OpenCode exposes `/thoth-init`, which materializes them
 project-locally.
 
-Owned workflow skills are `thoth-init`, `thoth-sdd`, `thoth-constitution`, and
-`thoth-archive`. Mandatory external skills (`simplify`, `tdd`,
+Owned workflow skills are `thoth-init`, `thoth-sdd`, `thoth-constitution`,
+`thoth-archive`, and `plan-reviewer`. The last one implements the optional,
+user-selected, read-only Oracle review before implementation. Mandatory external
+skills (`simplify`, `tdd`,
 `progressive-context-router`, and `architectural-grilling`) are not copied here:
 the thoth-agents installer invokes `npx skills add` against their canonical
 repositories so they retain a single source of truth.

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) {