thoth-agents 0.3.3 → 0.3.5

package/dist/harness/core/sdd.d.ts

@@ -22,7 +22,7 @@ export interface SddRoutingDecision {
     requiresUserInput: boolean;
     reasons: string[];
 }
-export type SddPhaseId = 'explore' | 'specify' | 'clarify' | 'plan' | 'checklist' | 'tasks' | 'analyze' | 'implement' | 'verify' | 'converge' | 'archive';
+export type SddPhaseId = 'explore' | 'specify' | 'clarify' | 'plan' | 'checklist' | 'tasks' | 'plan-review' | 'implement' | 'verify' | 'converge' | 'archive';
 export type SddPhaseActivation = 'required' | 'conditional';
 export interface SddPhaseContract {
     id: SddPhaseId;
@@ -58,7 +58,7 @@ export interface SddPhaseDispatchInput {
     verification?: string[];
     memory: MemoryDispatchContract;
 }
-export type SddArtifactId = 'spec' | 'plan' | 'tasks' | 'requirements-checklist' | 'research' | 'data-model' | 'contracts' | 'quickstart' | 'verify-report' | 'archive-report';
+export type SddArtifactId = 'spec' | 'plan' | 'tasks' | 'requirements-checklist' | 'research' | 'data-model' | 'contracts' | 'quickstart' | 'plan-review' | 'verify-report' | 'archive-report';
 export interface SddArtifactContract {
     id: SddArtifactId;
     path: string;
@@ -151,23 +151,24 @@ export declare const SDD_PHASES: readonly [{
     readonly eligibleAgentRoles: ["orchestrator"];
     readonly reason: "Produce dependency-ordered implementation slices with verification.";
 }, {
-    readonly id: "analyze";
+    readonly id: "plan-review";
     readonly order: 6;
-    readonly availableFor: ["full"];
-    readonly requiredFor: ["full"];
-    readonly activation: "required";
-    readonly prerequisites: ["specify", "plan", "tasks"];
-    readonly producesArtifact: false;
+    readonly availableFor: ["accelerated", "full"];
+    readonly requiredFor: [];
+    readonly activation: "conditional";
+    readonly prerequisites: ["tasks"];
+    readonly producesArtifact: true;
     readonly defaultAgentRole: "oracle";
     readonly eligibleAgentRoles: ["oracle"];
-    readonly reason: "Independently check cross-artifact consistency before high-risk implementation.";
+    readonly reason: "Offer independent blocker-only plan review when the user selects it after planning passes ready.";
+    readonly condition: "Activate only after ready when the user chooses Review plan with Oracle (Recommended).";
 }, {
     readonly id: "implement";
     readonly order: 7;
     readonly availableFor: ["direct", "accelerated", "full"];
     readonly requiredFor: ["direct", "accelerated", "full"];
     readonly activation: "required";
-    readonly prerequisites: ["tasks", "analyze"];
+    readonly prerequisites: ["tasks"];
     readonly producesArtifact: false;
     readonly defaultAgentRole: "orchestrator";
     readonly eligibleAgentRoles: ["orchestrator", "designer", "quick", "deep"];
@@ -255,6 +256,12 @@ export declare const SDD_ARTIFACT_GRAPH: readonly [{
     readonly producedBy: "plan";
     readonly consumes: ["spec", "plan"];
     readonly requiredFor: [];
+}, {
+    readonly id: "plan-review";
+    readonly path: "plan-review.md";
+    readonly producedBy: "plan-review";
+    readonly consumes: ["spec", "plan", "tasks"];
+    readonly requiredFor: [];
 }, {
     readonly id: "verify-report";
     readonly path: "verify-report.md";
@@ -280,14 +287,14 @@ export declare const SDD_ROUTE_EXECUTION_POLICIES: readonly [{
     readonly planningMode: "fast-forward";
     readonly validationGates: ["specify", "ready", "closeout"];
     readonly optionalArtifactsByDefault: false;
-    readonly routineUserPauses: false;
+    readonly routineUserPauses: true;
     readonly artifactRevisionPolicy: "revalidate-affected-downstream";
 }, {
     readonly route: "full";
     readonly planningMode: "gated";
     readonly validationGates: ["specify", "plan", "tasks", "ready", "closeout"];
     readonly optionalArtifactsByDefault: false;
-    readonly routineUserPauses: false;
+    readonly routineUserPauses: true;
     readonly artifactRevisionPolicy: "revalidate-affected-downstream";
 }];
 export declare const SDD_PHASE_PROTOCOLS: readonly [{
@@ -349,17 +356,17 @@ export declare const SDD_PHASE_PROTOCOLS: readonly [{
     readonly outputSchema: ["tasks.md path", "requirement coverage", "dependency order"];
     readonly doneWhen: ["Every FR and buildable SC has executable task coverage and every task has a verification step."];
     readonly blockingConditions: ["A task requires an unresolved requirement, architecture choice, or hidden prerequisite."];
-    readonly handoff: ["Pass spec.md, plan.md, tasks.md, dependencies, and verification commands to analyze or implement."];
-}, {
-    readonly id: "analyze";
-    readonly objective: "Perform read-only cross-artifact consistency and readiness analysis before full SDD implementation.";
-    readonly requiredInputs: ["spec.md", "plan.md", "tasks.md", "Project constitution"];
-    readonly instructions: ["Detect contradictions, ambiguity, duplication, scope drift, orphan tasks, and uncovered requirements.", "Challenge artifact completeness, requirement correctness, and cross-artifact coherence as separate review dimensions.", "Require task coverage for every FR and buildable SC; assess outcome SC as measurable verification targets without manufacturing implementation tasks.", "Report requirement coverage as a percentage and classify findings as CRITICAL, HIGH, MEDIUM, or LOW.", "Treat constitution violations and baseline requirements with zero task coverage as blocking."];
-    readonly allowedWrites: ["None; analysis is read-only and returns its report in-session."];
-    readonly outputSchema: ["findings table with stable IDs and severity", "requirement coverage percentage", "constitution alignment", "readiness verdict: ready | blocked"];
-    readonly doneWhen: ["Every high-signal cross-artifact inconsistency has a severity and remediation anchor."];
-    readonly blockingConditions: ["Any unresolved CRITICAL finding or constitution violation blocks implementation."];
-    readonly handoff: ["On ready, pass the reviewed artifact set and cautions to implement; on blocked, return findings to the owning coordination phase."];
+    readonly handoff: ["After ready, pass spec.md, plan.md, tasks.md, dependencies, and verification commands to the user-selected plan-review path or implement."];
+}, {
+    readonly id: "plan-review";
+    readonly objective: "Perform the user-selected read-only blocker review before Accelerated or Full implementation.";
+    readonly requiredInputs: ["spec.md", "plan.md", "tasks.md", "Optional active requirements checklist", "Project constitution", "Explicit user choice to review after the ready gate"];
+    readonly instructions: ["Load the bundled plan-reviewer skill and review executability, completeness, correctness, and coherence without redesigning the plan.", "Require task coverage for every FR and buildable SC; assess outcome SC as measurable verification targets without manufacturing implementation tasks.", "Return exact [OKAY] or [REJECT] semantics, default to [OKAY], and report at most three true blockers with the smallest fixes.", "Provide the reviewed artifact set so root can persist plan-review.md with SHA-256 freshness evidence; Oracle never writes it.", "Keep plan-review approval separate from implementation confirmation and mandatory final verify."];
+    readonly allowedWrites: ["None; Oracle is read-only. Root persists plan-review.md when review runs."];
+    readonly outputSchema: ["status: [OKAY] or [REJECT]", "zero to three blocker findings with smallest fixes", "non-blocking cautions", "requirement coverage percentage", "constitution alignment", "reviewed artifact freshness manifest input"];
+    readonly doneWhen: ["Oracle has returned an exact status and every true blocker has a concrete remediation anchor."];
+    readonly blockingConditions: ["[REJECT] blocks the review path until root repairs planning blockers, the user explicitly proceeds without review, or an explicit override is recorded."];
+    readonly handoff: ["On [OKAY], root persists review evidence, presents the approved-plan overview, and asks whether to implement or stop.", "A plan-review result never satisfies mandatory final verify."];
 }, {
     readonly id: "implement";
     readonly objective: "Execute the accepted task slice with one writer and focused verification.";

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   renderOpenCodeAgentConfigs,
   spawn,
   spawnSync
-} from "./chunk-YUCGIJPP.js";
+} from "./chunk-6GQYMWWT.js";
 import {
   POLL_INTERVAL_BACKGROUND_MS,
   context7,
@@ -12,7 +12,7 @@ import {
   grep_app,
   loadPluginConfig,
   stripJsonComments
-} from "./chunk-XO74DXBZ.js";
+} from "./chunk-F2K4CS5J.js";
 
 // src/index.ts
 import { fileURLToPath as fileURLToPath3 } from "url";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thoth-agents",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Adaptive multi-harness orchestration with seven roles, runtime-autonomous Spec Kit-compatible SDD routes, and external provider boundaries.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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.5",
   "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.5",
   "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.