thoth-agents 0.2.5 → 0.2.7

package/dist/agents/prompt-sections.d.ts

@@ -12,6 +12,9 @@ export interface SubagentRulesSection {
     progressConcept: 'progress';
     userQuestionConcept: 'userQuestion';
 }
+export interface ReasoningDisciplineSection {
+    kind: 'reasoning-discipline';
+}
 export interface ResponseBudgetSection {
     kind: 'response-budget';
 }
@@ -28,13 +31,14 @@ export interface RoleTextSection {
     kind: 'role-text';
     template: string;
 }
-export type PromptSection = QuestionProtocolSection | SubagentRulesSection | ResponseBudgetSection | StepBudgetSection | ModelFamilySection | RoleTextSection;
+export type PromptSection = QuestionProtocolSection | SubagentRulesSection | ReasoningDisciplineSection | ResponseBudgetSection | StepBudgetSection | ModelFamilySection | RoleTextSection;
 export type RolePromptSection = PromptSection;
 export interface PromptSectionRenderer<TSection extends PromptSection> {
     render(section: TSection, dialect: HarnessPromptDialect): string;
 }
 export declare function createQuestionProtocolSection(): QuestionProtocolSection;
 export declare function createSubagentRulesSection(memoryAccess?: SemanticMemoryAccess): SubagentRulesSection;
+export declare function createReasoningDisciplineSection(): ReasoningDisciplineSection;
 export declare function createResponseBudgetSection(): ResponseBudgetSection;
 export declare function createStepBudgetSection(steps?: number): StepBudgetSection | undefined;
 export declare function detectModelFamilyFromModel(model?: string | ModelEntry[]): ModelFamily | undefined;

package/dist/{chunk-C3VQMXQL.js → chunk-32672NLJ.js}

@@ -35,7 +35,7 @@ import {
   renderRolePrompt,
   writeConfig,
   writeLiteConfig
-} from "./chunk-HFZAL6NE.js";
+} from "./chunk-N7GFXGFJ.js";
 
 // src/cli/codex-paths.ts
 import { homedir } from "os";

package/dist/{chunk-YZNH23HZ.js → chunk-4AC2TTUO.js}

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

package/dist/{chunk-HFZAL6NE.js → chunk-N7GFXGFJ.js}

@@ -921,11 +921,14 @@ var SDD_PHASES = [
     order: 8,
     requiredFor: ["accelerated", "full"],
     prerequisites: ["tasks"],
-    producesArtifact: false,
+    producesArtifact: true,
     gate: "oracle-review",
     owner: "oracle",
+    artifactSkill: "plan-reviewer",
+    artifactMeaning: "durable-plan-review-result",
     defaultAgentRole: "oracle",
-    delegationReason: "Independent read-only executability review of tasks before implementation."
+    persistenceAgentRole: "quick",
+    delegationReason: "Independent read-only executability review of tasks before implementation; quick persists the durable review artifact when writes are required."
   },
   {
     id: "implementation-confirmation",
@@ -986,12 +989,14 @@ var SDD_WORKFLOW_CONTRACT = {
   artifactRules: [
     "SDD delegation defaults are phase-specific: sdd-propose, sdd-spec, and sdd-design default to deep.",
     "sdd-tasks defaults to quick with deep as fallback when the task plan is complex.",
+    "plan-reviewer defaults to oracle for independent read-only review; quick persists the plan-review artifact when repository or memory writes are required.",
     "sdd-verify defaults to oracle for independent review; quick persists the report when repository or memory writes are required.",
     "sdd-archive defaults to quick for mechanical closeout.",
     "OpenSpec design.md is technical solution design, not UI/UX design; sdd-design itself never routes to designer.",
     "Designer participates during apply only for user-facing UI, visual work, screenshots, or visual QA.",
     "Full-pipeline tasks require proposal, spec, and design artifacts.",
-    "Oracle is read-only and performs plan review plus independent verification review; it does not persist artifacts."
+    "Oracle is read-only and performs plan review plus independent verification review; it does not persist artifacts.",
+    "A fresh persisted plan-review approval satisfies only the plan-review gate; user implementation confirmation remains separate."
   ],
   verificationRules: [
     "Plan review must complete before implementation confirmation.",
@@ -1031,6 +1036,9 @@ function createSubagentRulesSection(memoryAccess = "base") {
     userQuestionConcept: "userQuestion"
   };
 }
+function createReasoningDisciplineSection() {
+  return { kind: "reasoning-discipline" };
+}
 function createResponseBudgetSection() {
   return { kind: "response-budget" };
 }
@@ -1135,6 +1143,9 @@ You are ${role}.
 ${responsibility}
 </responsibility>
 
+`),
+    createReasoningDisciplineSection(),
+    roleText(`
 <rules>`),
     createSubagentRulesSection(memoryAccess),
     roleText(`${rules.join("\n")}
@@ -1158,7 +1169,8 @@ the harness does not name this agent "orchestrator".
 <style>
 Respond in the user's language. Be warm, direct, evidence-led, and concise.
 Push back when context, risk, or assumptions are weak. Avoid verbosity.
-</style>
+</style>`),
+    roleText(`
 
 <core-rules>
 - Mode: primary coordinator. Mutation: coordination artifacts only.
@@ -1178,10 +1190,11 @@ Push back when context, risk, or assumptions are weak. Avoid verbosity.
 </core-rules>
 
 <epistemic-rigor>
-- Verify material user or agent claims before relying on them when they affect implementation, architecture, verification, safety, or guidance.
-- Use the cheapest reliable evidence: bounded direct check, delegated local discovery, or authoritative external documentation.
-- If evidence disproves a user or agent assumption, correct it plainly with the evidence, explain relevant tradeoffs, and offer viable alternatives.
-- Allow low-risk assumptions only when brief and not correctness-critical. Stay warm, direct, concise, and evidence-led.
+- Verify material user/agent claims before relying on them in implementation, architecture, verification, safety, or guidance.
+- Before solving/editing, post one short commentary update naming reasoning/root-cause check.
+- Do thought experiments: test competing explanations, edge cases, failure modes, root-cause fit.
+- Do not stop at first plausible explanation/superficial answer; validate with evidence, edge cases, tests, or fitting check.
+- If evidence disproves an assumption, correct it plainly, explain tradeoffs, and offer alternatives.
 </epistemic-rigor>
 
 <session-bootstrap>
@@ -1261,7 +1274,7 @@ ${renderSddDelegationMatrix()}
 Hard gates:
 - Use the SDD delegation matrix as canonical phase routing.
 - Load the matching skill when a phase has one.
-- {{role.oracle}} is read-only for plan-reviewer and sdd-verify review; {{role.quick}} persists verify reports when writes are required.
+- {{role.oracle}} is read-only for plan-reviewer and sdd-verify review; {{role.quick}} persists plan-review and verify artifacts when writes are required.
 - Never skip artifacts or jump from requirements-interview to implementation when SDD is selected.
 - Before SDD execution, load \`executing-plans\`; then track progress in {{progressTool}} plus the persistent artifact.
 - If openspec persistence is selected and openspec/ is missing or stale (partial structure or missing mechanism sections), dispatch sdd-init first.
@@ -1277,9 +1290,9 @@ Artifact governance handoff:
 - Root thoth-mem ownership stays with you; sub-agents must not own session memory, prompts, or progress checkpoints.
 
 Plan gate: after tasks, ask with \`{{userQuestionTool}}\`: "Review plan with {{role.oracle}} before executing (Recommended)" or "Proceed to execution".
-If reviewed, the review loop is complete only after [OKAY].
-If {{role.oracle}} returns [OKAY], give a deep approved-plan overview, then ask with \`{{userQuestionTool}}\` whether to implement or stop. Cover goals, scope, sequence, key decisions, verification, risks/trade-offs, and uncertainty so the user has full context.
-Do not dispatch \`sdd-apply\` after oracle approval until the user confirms implementation.
+Plan review is complete only after fresh [OKAY] evidence in \`plan-review.md\` or \`sdd/{change-name}/plan-review\`; missing, stale, rejected, or unparsable evidence reruns oracle unless a user override is logged.
+Fresh [OKAY] satisfies only plan-review. If {{role.oracle}} returns [OKAY], or recovery accepts it, give an approved-plan overview, then ask with \`{{userQuestionTool}}\` whether to implement or stop. Cover scope, sequence, decisions, verification, risks, and uncertainty.
+Do not dispatch \`sdd-apply\` until user confirmation; never treat plan-review recovery as implementation confirmation.
 Post-execution verify-loop (mirrors the plan-review loop's discipline; bounded to 3 rounds = initial apply->verify plus up to 2 fix->re-verify):
 - Dispatch \`sdd-verify\` as an iterative gate, not a single shot; round 1 is the first verify after apply. Treat the \`round N\` marker in the verify report as the source of truth for the round counter and surface it in {{progressTool}}.
 - On clean \`pass\`: proceed through the existing pre-archive user gate above, then delegate \`sdd-archive\`. Do not auto-advance to archive merely because a verify report exists.
@@ -1499,6 +1512,13 @@ function renderSubagentRules(section, dialect) {
   }
   return rules.join("\n");
 }
+function renderReasoningDiscipline() {
+  return `<reasoning-discipline>
+- Before solving/editing, post one short commentary update naming reasoning/root-cause check.
+- Do thought experiments: test competing explanations, edge cases, failure modes, root-cause fit.
+- Do not stop at first plausible explanation/superficial answer; validate with evidence, edge cases, tests, or fitting check.
+</reasoning-discipline>`;
+}
 function renderResponseBudget() {
   return "Return concise structured results: status, summary, files, verification/issues. Never return raw file dumps.";
 }
@@ -1579,6 +1599,8 @@ function renderPromptSection(section, dialect) {
       return renderQuestionProtocol(section, dialect);
     case "subagent-rules":
       return renderSubagentRules(section, dialect);
+    case "reasoning-discipline":
+      return renderReasoningDiscipline();
     case "response-budget":
       return renderResponseBudget();
     case "step-budget":

package/dist/cli/index.js

@@ -4,7 +4,7 @@ import {
   getOpenCodeVersion,
   isOpenCodeInstalled,
   opencodeAdapter
-} from "../chunk-YZNH23HZ.js";
+} from "../chunk-4AC2TTUO.js";
 import {
   CODEX_ROLE_NAMES,
   RECOMMENDED_SKILLS,
@@ -36,7 +36,7 @@ import {
   getOperationHarness,
   installRecommendedSkill,
   listOperationHarnesses
-} from "../chunk-C3VQMXQL.js";
+} from "../chunk-32672NLJ.js";
 import {
   ALL_AGENT_NAMES,
   CUSTOM_SKILLS,
@@ -48,7 +48,7 @@ import {
   getExistingLiteConfigPath,
   installCustomSkills,
   writeLiteConfig
-} from "../chunk-HFZAL6NE.js";
+} from "../chunk-N7GFXGFJ.js";
 
 // src/cli/index.ts
 import { pathToFileURL } from "url";

package/dist/cli/tui/index.js

@@ -25,13 +25,13 @@ import {
   listOperationHarnesses,
   parseRoleTomlModel,
   parseSubagentModel
-} from "../../chunk-C3VQMXQL.js";
+} from "../../chunk-32672NLJ.js";
 import {
   ALL_AGENT_NAMES,
   DEFAULT_MODELS,
   getExistingLiteConfigPath,
   parseConfig
-} from "../../chunk-HFZAL6NE.js";
+} from "../../chunk-N7GFXGFJ.js";
 
 // src/cli/tui/index.tsx
 import { render } from "ink";

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

@@ -123,11 +123,14 @@ export declare const SDD_PHASES: readonly [{
     readonly order: 8;
     readonly requiredFor: ["accelerated", "full"];
     readonly prerequisites: ["tasks"];
-    readonly producesArtifact: false;
+    readonly producesArtifact: true;
     readonly gate: "oracle-review";
     readonly owner: "oracle";
+    readonly artifactSkill: "plan-reviewer";
+    readonly artifactMeaning: "durable-plan-review-result";
     readonly defaultAgentRole: "oracle";
-    readonly delegationReason: "Independent read-only executability review of tasks before implementation.";
+    readonly persistenceAgentRole: "quick";
+    readonly delegationReason: "Independent read-only executability review of tasks before implementation; quick persists the durable review artifact when writes are required.";
 }, {
     readonly id: "implementation-confirmation";
     readonly order: 9;

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   renderOpenCodeAgentConfigs,
   spawn,
   spawnSync
-} from "./chunk-YZNH23HZ.js";
+} from "./chunk-4AC2TTUO.js";
 import {
   DEFAULT_THOTH_COMMAND,
   POLL_INTERVAL_BACKGROUND_MS,
@@ -14,7 +14,7 @@ import {
   installCustomSkills,
   loadPluginConfig,
   stripJsonComments
-} from "./chunk-HFZAL6NE.js";
+} from "./chunk-N7GFXGFJ.js";
 
 // src/index.ts
 import path4 from "path";

package/dist/sdd/artifact-governance/artifact-loader.d.ts

@@ -49,7 +49,82 @@ export interface ArtifactLoaderResult extends ArtifactGovernanceResult {
         openspec: ArtifactSnapshot | null;
     }>;
 }
+export type PlanReviewRecoveryDecision = 'fresh-approval' | 'missing' | 'unparsable' | 'non-approval-status' | 'stale';
+export interface PlanReviewReviewedArtifactInput {
+    role: string;
+    path: string;
+    required?: boolean;
+    content: string;
+}
+export interface PlanReviewReviewedArtifactDigest {
+    role: string;
+    path: string;
+    required: boolean;
+    sha256: string;
+}
+export interface PlanReviewOverride {
+    occurred: boolean;
+    at: string | null;
+    surface: string | null;
+    context: string | null;
+}
+export interface CreatePlanReviewArtifactInput {
+    changeName: string;
+    status: string;
+    reviewedAt: string;
+    pipeline: 'accelerated' | 'full';
+    persistenceMode: ArtifactGovernanceMode;
+    reviewerRole?: string;
+    comments?: readonly string[];
+    nonBlockingNotes?: readonly string[];
+    blockers?: readonly string[];
+    override?: PlanReviewOverride;
+    userOverrideContext?: string | null;
+    reviewedArtifacts: readonly PlanReviewReviewedArtifactInput[];
+}
+export interface PlanReviewArtifact {
+    schema: 'thoth-agents/sdd-plan-review/v1';
+    artifact: 'plan-review';
+    change: string;
+    gate: 'oracle-review';
+    status: string;
+    reviewerRole: string;
+    reviewedAt: string;
+    pipeline: 'accelerated' | 'full';
+    persistenceMode: ArtifactGovernanceMode;
+    memoryTopicKey: string;
+    reviewedArtifacts: readonly PlanReviewReviewedArtifactDigest[];
+    override: PlanReviewOverride;
+}
+export interface MaterializedPlanReviewArtifact {
+    descriptor: ArtifactLoaderDescriptor;
+    artifact: PlanReviewArtifact;
+    content: string;
+}
+export type ParsePlanReviewArtifactResult = {
+    ok: true;
+    artifact: PlanReviewArtifact;
+} | {
+    ok: false;
+    reason: 'unparsable';
+    message: string;
+};
+export interface EvaluatePlanReviewRecoveryInput {
+    content: string | null | undefined;
+    currentArtifacts: Readonly<Record<string, string>>;
+}
+export interface PlanReviewRecoveryResult {
+    gateSatisfied: boolean;
+    implementationConfirmed: false;
+    decision: PlanReviewRecoveryDecision;
+    status: string | null;
+    staleArtifacts: readonly string[];
+    message: string;
+}
 export declare function getArtifactTopicKey(changeName: string, artifact: string): string;
 export declare function getArtifactOpenSpecPath(changeName: string, artifact: string): string;
 export declare function loadArtifactSnapshot(request: ArtifactLoaderRequest, dependencies?: ArtifactLoaderDependencies): Promise<ArtifactLoaderResult>;
+export declare function createPlanReviewArtifact(input: CreatePlanReviewArtifactInput): MaterializedPlanReviewArtifact;
+export declare function parsePlanReviewArtifact(content: string): ParsePlanReviewArtifactResult;
+export declare function evaluatePlanReviewRecovery(input: EvaluatePlanReviewRecoveryInput): PlanReviewRecoveryResult;
 export {};

package/dist/sdd/artifact-governance/index.d.ts

@@ -1,5 +1,5 @@
-export type { ArtifactComparisonMetadata, ArtifactLoaderDependencies, ArtifactLoaderDescriptor, ArtifactLoaderRequest, ArtifactLoaderResult, ArtifactSnapshot, ArtifactSnapshotInput, ArtifactSnapshotSource, } from './artifact-loader';
-export { getArtifactOpenSpecPath, getArtifactTopicKey, loadArtifactSnapshot, } from './artifact-loader';
+export type { ArtifactComparisonMetadata, ArtifactLoaderDependencies, ArtifactLoaderDescriptor, ArtifactLoaderRequest, ArtifactLoaderResult, ArtifactSnapshot, ArtifactSnapshotInput, ArtifactSnapshotSource, CreatePlanReviewArtifactInput, EvaluatePlanReviewRecoveryInput, MaterializedPlanReviewArtifact, ParsePlanReviewArtifactResult, PlanReviewArtifact, PlanReviewOverride, PlanReviewRecoveryDecision, PlanReviewRecoveryResult, PlanReviewReviewedArtifactDigest, PlanReviewReviewedArtifactInput, } from './artifact-loader';
+export { createPlanReviewArtifact, evaluatePlanReviewRecovery, getArtifactOpenSpecPath, getArtifactTopicKey, loadArtifactSnapshot, parsePlanReviewArtifact, } from './artifact-loader';
 export type { ValidateTasksArtifactPersistence, ValidateTasksArtifactRequest, } from './tasks-validator';
 export { validateTasksArtifact } from './tasks-validator';
 export type { ArtifactGovernanceEnforcementMode, ArtifactGovernanceFinding, ArtifactGovernanceMetadataValue, ArtifactGovernanceMode, ArtifactGovernanceReport, ArtifactGovernanceResult, ArtifactGovernanceSeverity, ArtifactGovernanceSummary, CreateArtifactGovernanceReportOptions, CreateArtifactGovernanceResultOptions, } from './types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thoth-agents",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Delegate-first OpenCode plugin with seven agents, thoth-mem persistence, and bundled SDD skills.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/skills/_shared/openspec-convention.md

@@ -64,6 +64,7 @@ openspec/
         ├── contracts/                    # optional sub-artifact subdir (gated)
         ├── quickstart.md                 # optional sub-artifact (gated)
         ├── tasks.md
+        ├── plan-review.md
         └── verify-report.md
 ```
 
@@ -77,6 +78,7 @@ openspec/
 | Design | `openspec/changes/{change-name}/design.md` | Architecture and file plan; always produced |
 | Sub-artifacts (optional, gated) | `openspec/changes/{change-name}/{research.md,data-model.md,contracts/,quickstart.md}` | Optional design sub-artifacts; gated by `rules.design.sub_artifacts` + `complexity_threshold` |
 | Tasks | `openspec/changes/{change-name}/tasks.md` | Checkbox checklist updated by apply |
+| Plan review | `openspec/changes/{change-name}/plan-review.md` | Oracle plan-review result with status, notes, blockers, override context, and SHA-256 reviewed-artifact freshness data |
 | Verify report | `openspec/changes/{change-name}/verify-report.md` | Compliance matrix and evidence |
 | Requirements checklist | `openspec/changes/{change-name}/checklists/requirements.md` | Domain-typed requirement-quality gate, consumed before tasks |
 | Constitution | `openspec/memory/constitution.md` | Semver-versioned native principles + Sync-Impact Report |
@@ -85,6 +87,8 @@ openspec/
 primarily persisted through thoth-mem topic keys when the mode includes
 thoth-mem.
 
+A saved `plan-review.md` approval is reusable only when it contains `[OKAY]` and every recorded reviewed-artifact SHA-256 digest still matches the current planning artifacts. Missing, stale, rejected, or unparsable plan-review evidence fails closed and requires a fresh Oracle review unless a separate explicit user override is captured through the normal blocking-input surface. A fresh plan-review approval satisfies only the plan-review gate; implementation confirmation remains separate.
+
 The canonical OpenSpec copy is the filesystem representation of these artifacts
 for `openspec` and `hybrid` modes. thoth-mem topic keys are the memory
 representation when the mode includes thoth-mem; neither representation changes

package/src/skills/_shared/persistence-contract.md

@@ -118,6 +118,7 @@ context. Supplemental context does not replace the recall funnel.
 - `sdd-spec` persists `sdd/{change-name}/spec`
 - `sdd-design` persists `sdd/{change-name}/design`
 - `sdd-tasks` persists `sdd/{change-name}/tasks`
+- `plan-reviewer` returns a read-only result; the orchestrator or `quick` persistence helper persists `sdd/{change-name}/plan-review` and/or `openspec/changes/{change-name}/plan-review.md` according to the selected mode
 - `sdd-apply` persists `sdd/{change-name}/apply-progress` and re-persists
   updated `sdd/{change-name}/tasks`
 - `sdd-verify` persists `sdd/{change-name}/verify-report`
@@ -150,6 +151,7 @@ original intent, accepted scope, deferred areas, and justified exclusions.
 
 ## Recovery Notes
 
+- For plan-review recovery, accept saved approval only when canonical evidence contains `[OKAY]` and reviewed-artifact SHA-256 digests still match. Missing, stale, rejected, or unparsable evidence fails closed; user implementation confirmation remains a distinct later gate.
 - Prefer exact topic-key queries over broad natural-language recall.
 - Always apply the recall funnel (`mem_recall(mode="compact")` ->
   `mem_recall(mode="context")` -> `mem_get(...)`) before treating memory as

package/src/skills/_shared/thoth-mem-convention.md

@@ -46,6 +46,7 @@ Supported artifact names:
 - `design`
 - `design-brief`
 - `tasks`
+- `plan-review`
 - `apply-progress`
 - `verify-report`
 - `archive-report`
@@ -69,6 +70,7 @@ artifacts:
   spec: false       # always false in accelerated pipeline
   design: false     # always false in accelerated pipeline
   tasks: false
+  plan-review: false
   apply-progress: false
   verify-report: false
   archive-report: false

package/src/skills/plan-reviewer/SKILL.md

@@ -29,6 +29,9 @@ mode.
 The artifact governance validator is not part of this review. Plan-reviewer is
 only the pre-execution approval gate for the task plan; it does not run the
 validator, enforce its findings, or manage the future pre-`sdd-apply` handoff.
+Plan-reviewer remains read-only: it returns the durable review payload, while the
+orchestrator or `quick` persistence helper writes `plan-review.md` and/or
+`sdd/{change-name}/plan-review` when the selected persistence mode requires it.
 Invoke the semantic oracle role through the available role dispatch surface.
 
 Focus on whether the plan can be executed as written, not whether you would have
@@ -168,6 +171,17 @@ Check only what affects executability:
 
 ## Output Format
 
+Return the status token plus enough structured payload for durable persistence at
+`openspec/changes/{change-name}/plan-review.md` and topic key
+`sdd/{change-name}/plan-review` when the selected store includes those targets.
+The persisted payload must preserve status, reviewer role, timestamp, pipeline,
+persistence mode, comments, non-blocking notes, blockers, user override context
+when applicable, and reviewed artifact freshness data. Use SHA-256 freshness
+digests over reviewed artifact content when the coordinator asks for a concrete
+manifest. Missing, stale, rejected, or unparsable saved evidence fails closed on
+recovery. A fresh `[OKAY]` satisfies only plan-review; it is not implementation
+confirmation.
+
 If the plan is executable:
 
 ```text