thoth-agents 0.3.3 → 0.3.4

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "thoth-agents",
       "description": "Adaptive root orchestration, six specialist subagents, and a runtime-autonomous Spec Kit-compatible SDD bundle.",
-      "version": "0.3.3",
+      "version": "0.3.4",
       "author": {
         "name": "thoth-agents maintainers"
       },

package/README.md

@@ -23,7 +23,10 @@ parallelism creates a net gain.
 The plugin ships the seven-role contract and thoth-owned SDD
 contracts that combine Spec Kit-grade traceability with OpenSpec-style durable
 deltas. Accelerated planning fast-forwards without routine pauses; structural
-`ready`/`closeout` gates and independent oracle review retain rigor. During
+`ready`/`closeout` gates and independent oracle review retain rigor. Root
+recommends Direct, Accelerated, or Full and the user selects the route. After
+`ready`, artifact-backed routes offer optional Oracle plan review or proceeding
+without it; every final verification remains mandatory. During
 installation, the CLI obtains four mandatory external skills
 from their canonical repositories with `npx skills add` and invokes the official
 provider-owned thoth-mem setup for the selected harness. During an SDD, agents
@@ -58,10 +61,12 @@ Restart OpenCode and initialize the current repository:
 /thoth-init
 ```
 
-This copies the four thoth-owned workflow skills into `.agents/skills/` and
+This copies the five thoth-owned workflow skills into `.agents/skills/` and
 creates missing `openspec/` governance files. The external skills are already in
-OpenCode's global skill root and thoth-mem has completed its own provider setup
-from the CLI step. Existing project-owned files are preserved.
+one of the OpenCode global discovery roots managed here,
+`~/.config/opencode/skills/` or `~/.agents/skills/`, and thoth-mem has completed
+its own provider setup from the CLI step. Existing project-owned files are
+preserved.
 
 ### Codex
 
@@ -113,7 +118,7 @@ Restart Claude Code or run `/reload-plugins`, then initialize the repository:
 /thoth-agents:thoth-init
 ```
 
-Claude discovers the packaged orchestrator, six namespaced subagents, and four
+Claude discovers the packaged orchestrator, six namespaced subagents, and five
 thoth-owned skills from the plugin. The CLI installs the external skills into
 Claude's global skill root and requires thoth-mem's own setup result to be
 complete. Init creates only the missing project governance files; it never edits
@@ -141,8 +146,8 @@ correctness-critical work.
       <br>
       <i>Adaptive root and final synthesis.</i>
       <br><br>
-      Keeps task ownership and synthesis, chooses the route, coordinates SDD
-      artifacts, and implements bounded work directly.
+      Keeps task ownership and synthesis, recommends a route for the user's
+      selection, coordinates SDD artifacts, and implements bounded work directly.
       <br><br>
       <b>Mode:</b> <code>adaptive-root</code>
     </td>
@@ -195,7 +200,7 @@ correctness-critical work.
       <br>
       <i>Independent analysis and verification.</i>
       <br><br>
-      Challenges plans, owns Full analysis, and independently verifies every
+      Reviews plans when the user requests it and independently verifies every
       implementation.
       <br><br>
       <b>Mode:</b> <code>read-only</code>
@@ -267,29 +272,33 @@ Accelerated work.
 ```text
 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
 ```
 
 | Route | Use when | Artifacts |
 | --- | --- | --- |
 | Direct | Clear, bounded, low-risk work, including multi-file documentation/mechanical edits | None; oracle returns its verdict in-session. |
 | Accelerated | Generic SDD request, partial clarity, moderate risk, multi-surface behavior, or architecture | Canonical artifacts with fast-forward specification/planning/tasks. |
-| Full | Material uncertainty, cross-cutting behavior/architecture, high contract risk, or high failure cost | Accelerated artifacts plus exploration and independent pre-implementation analysis. |
+| Full | Material uncertainty, cross-cutting behavior/architecture, high contract risk, or high failure cost | Accelerated artifacts plus exploration and separate planning gates. |
 
 The root loads only the current phase contract from the bundled `thoth-sdd`
 skill. It owns specification, clarification, planning, requirements checklists,
 task decomposition, convergence, report persistence, and archive. `explorer`
-owns Full discovery; `oracle` always owns `analyze` and `verify`.
+owns Full discovery; `oracle` owns user-selected plan review and every `verify`.
 
-An explicitly named route wins. A generic request to use SDD sets Accelerated as
-the minimum. Accelerated writes `spec.md -> plan.md -> tasks.md` in one
-uninterrupted root pass and does not pause for routine approval between phases.
+An explicitly named route is the user's selection and wins. Otherwise root
+recommends one of all three routes and waits for the user's choice. A generic
+request to use SDD sets Accelerated as the minimum recommendation. Accelerated
+writes `spec.md -> plan.md -> tasks.md` in one uninterrupted root pass and does
+not pause for routine approval between those planning phases.
 
 Conditional phases remain deliberately narrow:
 
 - `clarify` runs only for a material ambiguity and updates canonical `spec.md`;
 - `checklist` audits high-risk requirement quality with `CHK###` taxonomy and a
   separate revalidation pass;
+- `plan-review` is offered after `ready` on Accelerated and Full; the user chooses
+  `Review plan with Oracle (Recommended)` or `Proceed without review`;
 - `converge` appends tasks only after failed artifact-backed verification; and
 - `architectural-grilling` runs before specification only when explicitly
   requested or a material human-owned decision remains unresolved.
@@ -314,6 +323,7 @@ Every harness package includes the workflow contracts owned by thoth-agents:
 | `thoth-sdd` | Route rules, phase contracts, templates, and structural validator. |
 | `thoth-constitution` | Explicit governance SemVer lifecycle; routine plans only read principles. |
 | `thoth-archive` | Passing closeout, transactional durable-spec sync, audit report, and dated move. |
+| `plan-reviewer` | Optional read-only Oracle plan review with exact `[OKAY]`/`[REJECT]` results and freshness evidence. |
 
 The installer obtains these mandatory external skills from their single source
 of truth:

package/dist/{chunk-YUCGIJPP.js → chunk-6GQYMWWT.js}

@@ -14,7 +14,7 @@ import {
   getStepBudgetPromptSection,
   loadAgentPrompt,
   renderRolePrompt
-} from "./chunk-XO74DXBZ.js";
+} from "./chunk-F2K4CS5J.js";
 
 // src/agents/deep.ts
 var DEEP_PROMPT = renderRolePrompt(

package/dist/{chunk-XO74DXBZ.js → chunk-F2K4CS5J.js}

@@ -797,7 +797,7 @@ var AGENT_ROLES = [
       "keeps requirements, decisions, and final synthesis in the root thread"
     ],
     verification: [
-      "delegates analyze and every verify phase to oracle, including Direct and Accelerated routes",
+      "delegates selected plan-review and every verify phase to oracle; plan review stays optional and final verification stays mandatory",
       "consolidates summarized evidence returned by child agents"
     ]
   },
@@ -832,8 +832,8 @@ var AGENT_ROLES = [
     mode: "read-only",
     dispatch: "synchronous-task-only",
     canMutateWorkspace: false,
-    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.",
     toolGovernance: [
       "performs read-only analysis and independent review and is never the implementer of the work it judges",
       "does not implement, persist artifacts, or delegate further"
@@ -1017,16 +1017,17 @@ var SDD_PHASES = [
     reason: "Produce dependency-ordered implementation slices with verification."
   },
   {
-    id: "analyze",
+    id: "plan-review",
     order: 6,
-    availableFor: ["full"],
-    requiredFor: ["full"],
-    activation: "required",
-    prerequisites: ["specify", "plan", "tasks"],
-    producesArtifact: false,
+    availableFor: ["accelerated", "full"],
+    requiredFor: [],
+    activation: "conditional",
+    prerequisites: ["tasks"],
+    producesArtifact: true,
     defaultAgentRole: "oracle",
     eligibleAgentRoles: ["oracle"],
-    reason: "Independently check cross-artifact consistency before high-risk implementation."
+    reason: "Offer independent blocker-only plan review when the user selects it after planning passes ready.",
+    condition: "Activate only after ready when the user chooses Review plan with Oracle (Recommended)."
   },
   {
     id: "implement",
@@ -1034,7 +1035,7 @@ var SDD_PHASES = [
     availableFor: ["direct", "accelerated", "full"],
     requiredFor: ["direct", "accelerated", "full"],
     activation: "required",
-    prerequisites: ["tasks", "analyze"],
+    prerequisites: ["tasks"],
     producesArtifact: false,
     defaultAgentRole: "orchestrator",
     eligibleAgentRoles: ["orchestrator", "designer", "quick", "deep"],
@@ -1135,6 +1136,13 @@ var SDD_ARTIFACT_GRAPH = [
     consumes: ["spec", "plan"],
     requiredFor: []
   },
+  {
+    id: "plan-review",
+    path: "plan-review.md",
+    producedBy: "plan-review",
+    consumes: ["spec", "plan", "tasks"],
+    requiredFor: []
+  },
   {
     id: "verify-report",
     path: "verify-report.md",
@@ -1164,7 +1172,7 @@ var SDD_ROUTE_EXECUTION_POLICIES = [
     planningMode: "fast-forward",
     validationGates: ["specify", "ready", "closeout"],
     optionalArtifactsByDefault: false,
-    routineUserPauses: false,
+    routineUserPauses: true,
     artifactRevisionPolicy: "revalidate-affected-downstream"
   },
   {
@@ -1172,7 +1180,7 @@ var SDD_ROUTE_EXECUTION_POLICIES = [
     planningMode: "gated",
     validationGates: ["specify", "plan", "tasks", "ready", "closeout"],
     optionalArtifactsByDefault: false,
-    routineUserPauses: false,
+    routineUserPauses: true,
     artifactRevisionPolicy: "revalidate-affected-downstream"
   }
 ];
@@ -1184,25 +1192,25 @@ var SDD_WORKFLOW_CONTRACT = {
     validationGates: [...policy.validationGates]
   })),
   routingRules: [
-    "An explicitly requested direct, accelerated, or full route wins; a generic SDD request sets accelerated as the minimum route.",
+    "The root recommends direct, accelerated, or full from risk evidence, but the user selects the route; an explicitly requested route already counts as selection.",
     "Direct work is the default for clear, bounded, low-risk changes; documentation and mechanical work may remain direct across multiple files.",
     "Accelerated SDD is used for multi-surface behavior, architecture, partial clarity, moderate risk, or broad non-behavioral coordination.",
-    "Accelerated planning fast-forwards specify, plan, and tasks in one uninterrupted root pass without routine user pauses.",
+    "Accelerated planning fast-forwards specify, plan, and tasks without pauses between those artifacts, then offers the user optional oracle plan review after ready.",
     "Full SDD is used for unresolved scope, cross-cutting behavior or architecture, high contract risk, or high failure cost.",
     "Use architectural-grilling before specification only when the user explicitly requests it or material product or architecture decisions remain human-owned and unresolved; never require it merely because the route is Full.",
-    "User input is requested only when a material unresolved decision would change the result."
+    "Route selection and the post-ready plan-review choice are explicit user decisions; other input is requested only when a material unresolved decision changes the result."
   ],
   artifactRules: [
     "Spec Kit artifact semantics are preserved inside the governed openspec store.",
     "Accelerated and full routes require spec.md, plan.md, tasks.md, verify-report.md, and archive-report.md.",
-    "Research, data model, contracts, quickstart, and requirements checklist are created only when useful.",
+    "Research, data model, contracts, quickstart, requirements checklist, and plan-review.md are optional and created only when useful or selected.",
     "The adaptive root writes coordination artifacts after loading the matching bundled phase contract; implementation ownership stays with the root or one writer role.",
     "After oracle PASS, archive transactionally synchronizes only explicitly declared durable ADDED, MODIFIED, REMOVED, and RENAMED requirement deltas into openspec/specs; INTERNAL requirements and undeclared prose never update permanent specifications.",
     "Archive stages and backs up writes so handled failures roll back within the active process; forced process or operating-system termination is not crash-atomic."
   ],
   verificationRules: [
     "Every route delegates focused verification to read-only oracle; the implementation writer never verifies its own work.",
-    "Full SDD delegates independent cross-artifact analysis to oracle before implementation.",
+    "Accelerated and Full offer read-only oracle plan review after ready; it runs only when the user selects it and never replaces final verification.",
     "Accelerated and full verification persists verify-report.md with a pass or fail verdict and requirement compliance matrix.",
     "An artifact-backed fail verdict routes through append-only convergence, implementation, and verification again; direct work returns straight to implementation.",
     "A pass verdict is required before accelerated or full work can archive."
@@ -1383,7 +1391,7 @@ ${renderRoleDirectory()}
 </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 \`{{userQuestionTool}}\`, 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. ${renderSddRoute("direct")}.
 - 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. ${renderSddRoute("accelerated")}.
@@ -1391,12 +1399,13 @@ ${renderRoleDirectory()}
 - Its thoth-sdd validator gates are ${accelerated.validationGates.join(" -> ")}; optional artifacts are off by default.
 - Full SDD: uncertain scope, cross-cutting behavior or architecture, high contract risk, or high failure cost. ${renderSddRoute("full")}.
 - Full gates are ${full.validationGates.join(" -> ")}; checklist remains conditional.
+- After \`ready\` on Accelerated/Full, ask with \`{{userQuestionTool}}\`: \`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 ${roleTemplate("oracle")}, including Direct and Accelerated work. The implementation writer must never review itself.
+- Delegate each user-selected plan review and every verify phase to ${roleTemplate("oracle")}. The implementation writer must never review itself.
 </sdd-routing>
 
 <external-skills>
@@ -1425,7 +1434,7 @@ ${renderRoleDirectory()}
 
 <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.
-- ${roleTemplate("oracle")} always provides independent verification and also owns Full SDD analysis. Root and implementation writers never self-approve.
+- ${roleTemplate("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>
@@ -1452,7 +1461,7 @@ var ROLE_SPECIFIC_RULES = {
   oracle: [
     "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."
   ],
   designer: [

package/dist/{chunk-UQOCEMU3.js → chunk-W5GCMYA3.js}

@@ -31,7 +31,7 @@ import {
   updateOpenCodeMainConfig,
   writeConfig,
   writeLiteConfig
-} from "./chunk-XO74DXBZ.js";
+} from "./chunk-F2K4CS5J.js";
 
 // src/cli/codex-paths.ts
 import { homedir } from "os";
@@ -2496,10 +2496,13 @@ var SKILLS_CLI_AGENT = {
   codex: "codex",
   claude: "claude-code"
 };
-var GLOBAL_SKILL_ROOT = {
-  opencode: [".config", "opencode", "skills"],
-  codex: [".codex", "skills"],
-  claude: [".claude", "skills"]
+var GLOBAL_SKILL_ROOTS = {
+  opencode: [
+    [".config", "opencode", "skills"],
+    [".agents", "skills"]
+  ],
+  codex: [[".agents", "skills"]],
+  claude: [[".claude", "skills"]]
 };
 var REQUIRED_SKILLS = [
   {
@@ -2527,16 +2530,22 @@ var REQUIRED_SKILLS = [
     description: "Conditional product and architecture decision interview"
   }
 ];
-function getRequiredSkillPath(skill, harness, homeDir = homedir2()) {
-  return join3(
-    homeDir,
-    ...GLOBAL_SKILL_ROOT[harness],
-    skill.skillName,
-    "SKILL.md"
+function getRequiredSkillPaths(skill, harness, homeDir = homedir2()) {
+  return GLOBAL_SKILL_ROOTS[harness].map(
+    (root) => join3(homeDir, ...root, skill.skillName, "SKILL.md")
   );
 }
-function isRequiredSkillInstalled(skill, harness, options = {}) {
-  return existsSync6(getRequiredSkillPath(skill, harness, options.homeDir));
+function getRequiredSkillPath(skill, harness, homeDir = homedir2()) {
+  const [primaryPath] = getRequiredSkillPaths(skill, harness, homeDir);
+  if (!primaryPath) {
+    throw new Error(`No global skill root is configured for ${harness}.`);
+  }
+  return primaryPath;
+}
+function getInstalledRequiredSkillPath(skill, harness, homeDir = homedir2()) {
+  return getRequiredSkillPaths(skill, harness, homeDir).find(
+    (path) => existsSync6(path)
+  );
 }
 function getRequiredSkillInstallCommand(skill, harness, options = {}) {
   return getNpxCommand(
@@ -2557,8 +2566,18 @@ function getRequiredSkillInstallCommand(skill, harness, options = {}) {
 }
 function installRequiredSkill(skill, harness, options = {}) {
   const skillPath = getRequiredSkillPath(skill, harness, options.homeDir);
-  if (isRequiredSkillInstalled(skill, harness, options)) {
-    return { skill, harness, status: "already-installed", skillPath };
+  const installedPath = getInstalledRequiredSkillPath(
+    skill,
+    harness,
+    options.homeDir
+  );
+  if (installedPath) {
+    return {
+      skill,
+      harness,
+      status: "already-installed",
+      skillPath: installedPath
+    };
   }
   const { command, args } = getRequiredSkillInstallCommand(
     skill,
@@ -2568,10 +2587,25 @@ function installRequiredSkill(skill, harness, options = {}) {
   try {
     const result = spawnSync2(command, args, { stdio: "inherit" });
     if (result.status === 0) {
-      return { skill, harness, status: "installed", skillPath };
+      return {
+        skill,
+        harness,
+        status: "installed",
+        skillPath: getInstalledRequiredSkillPath(skill, harness, options.homeDir) ?? skillPath
+      };
     }
-    if (isRequiredSkillInstalled(skill, harness, options)) {
-      return { skill, harness, status: "already-installed", skillPath };
+    const recoveredPath = getInstalledRequiredSkillPath(
+      skill,
+      harness,
+      options.homeDir
+    );
+    if (recoveredPath) {
+      return {
+        skill,
+        harness,
+        status: "already-installed",
+        skillPath: recoveredPath
+      };
     }
     return { skill, harness, status: "failed", skillPath, error: result.error };
   } catch (error) {
@@ -4015,8 +4049,13 @@ function homeDirFromContext(context2) {
 function openCodeSkillTargets(context2) {
   const homeDir = homeDirFromContext(context2);
   const requiredTargets = REQUIRED_SKILLS.map((skill) => {
-    const path = getRequiredSkillPath(skill, "opencode", homeDir);
-    const installed = existsSync9(path);
+    const installedPath = getInstalledRequiredSkillPath(
+      skill,
+      "opencode",
+      homeDir
+    );
+    const path = installedPath ?? getRequiredSkillPath(skill, "opencode", homeDir);
+    const installed = installedPath !== void 0;
     return {
       kind: "skill",
       path,

package/dist/cli/index.js

@@ -4,7 +4,7 @@ import {
   getOpenCodeVersion,
   isOpenCodeInstalled,
   opencodeAdapter
-} from "../chunk-YUCGIJPP.js";
+} from "../chunk-6GQYMWWT.js";
 import {
   CODEX_ROLE_NAMES,
   REQUIRED_SKILLS,
@@ -43,7 +43,7 @@ import {
   installRequiredSkill,
   listOperationHarnesses,
   normalizeEffortSelection
-} from "../chunk-UQOCEMU3.js";
+} from "../chunk-W5GCMYA3.js";
 import {
   ALL_AGENT_NAMES,
   detectCurrentConfig,
@@ -53,7 +53,7 @@ import {
   getExistingLiteConfigPath,
   updateOpenCodeMainConfig,
   writeLiteConfig
-} from "../chunk-XO74DXBZ.js";
+} from "../chunk-F2K4CS5J.js";
 
 // src/cli/index.ts
 import { pathToFileURL } from "url";

package/dist/cli/skills.d.ts

@@ -19,7 +19,9 @@ interface InstallRequiredSkillOptions extends NpxCommandOptions {
     homeDir?: string;
 }
 export declare const REQUIRED_SKILLS: readonly RequiredSkill[];
+export declare function getRequiredSkillPaths(skill: RequiredSkill, harness: SkillInstallHarness, homeDir?: string): string[];
 export declare function getRequiredSkillPath(skill: RequiredSkill, harness: SkillInstallHarness, homeDir?: string): string;
+export declare function getInstalledRequiredSkillPath(skill: RequiredSkill, harness: SkillInstallHarness, homeDir?: string): string | undefined;
 export declare function isRequiredSkillInstalled(skill: RequiredSkill, harness: SkillInstallHarness, options?: InstallRequiredSkillOptions): boolean;
 export declare function getRequiredSkillInstallCommand(skill: RequiredSkill, harness: SkillInstallHarness, options?: NpxCommandOptions): NpxCommand;
 /** Install one mandatory skill into the selected harness's global skill root. */

package/dist/cli/tui/index.js

@@ -2,8 +2,8 @@ import {
   defaultTuiOperations,
   effortChoicesForModel,
   listOperationHarnesses
-} from "../../chunk-UQOCEMU3.js";
-import "../../chunk-XO74DXBZ.js";
+} from "../../chunk-W5GCMYA3.js";
+import "../../chunk-F2K4CS5J.js";
 
 // src/cli/tui/index.tsx
 import { render } from "ink";

package/dist/harness/core/agent-pack.d.ts

@@ -32,7 +32,7 @@ export declare const AGENT_ROLES: readonly [{
     readonly scope: "requirements, SDD coordination, routing, bounded direct work, decisions, and synthesis";
     readonly responsibility: "Keep the task coherent, own sequential specification, planning, task, convergence, and archive coordination, act directly when work is clear and bounded, and delegate only for net gain.";
     readonly toolGovernance: ["may inspect and edit bounded direct work, but every verification is delegated to oracle", "loads the matching thoth-sdd phase contract on demand instead of carrying every phase protocol in its prompt", "owns governed coordination writes under openspec/ and uses append-only tasks.md updates during convergence", "delegates independent or specialist work only when it produces a net gain", "keeps requirements, decisions, and final synthesis in the root thread"];
-    readonly verification: ["delegates analyze and every verify phase to oracle, including Direct and Accelerated routes", "consolidates summarized evidence returned by child agents"];
+    readonly verification: ["delegates selected plan-review and every verify phase to oracle; plan review stays optional and final verification stays mandatory", "consolidates summarized evidence returned by child agents"];
 }, {
     readonly name: "explorer";
     readonly mode: "read-only";
@@ -56,8 +56,8 @@ export declare const AGENT_ROLES: readonly [{
     readonly mode: "read-only";
     readonly dispatch: "synchronous-task-only";
     readonly canMutateWorkspace: false;
-    readonly scope: "diagnosis, architecture, analysis, and independent verification";
-    readonly responsibility: "Independently analyze plans and perform every implementation verification, exposing correctness risks and judging whether results satisfy their contracts.";
+    readonly scope: "diagnosis, architecture, optional plan review, and independent verification";
+    readonly responsibility: "Independently review plans when the user requests it and perform every implementation verification, exposing correctness risks and judging whether results satisfy their contracts.";
     readonly toolGovernance: ["performs read-only analysis and independent review and is never the implementer of the work it judges", "does not implement, persist artifacts, or delegate further"];
     readonly verification: ["separates observations, risks, and recommendations"];
 }, {

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