thoth-agents 0.2.4 → 0.2.6

package/dist/{chunk-YZNH23HZ.js → chunk-5DHG5II4.js}

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

package/dist/{chunk-HFZAL6NE.js → chunk-76DARQOT.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.",
@@ -1261,7 +1266,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 +1282,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.

package/dist/{chunk-PDKLWORW.js → chunk-DAZFSPN4.js}

@@ -35,7 +35,7 @@ import {
   renderRolePrompt,
   writeConfig,
   writeLiteConfig
-} from "./chunk-HFZAL6NE.js";
+} from "./chunk-76DARQOT.js";
 
 // src/cli/codex-paths.ts
 import { homedir } from "os";
@@ -1480,8 +1480,11 @@ function renderCodexRootInstructions(config) {
     codexInternalHandoffGuidance(),
     "<codex-runtime>",
     "- The ambient Codex root session is the root/main orchestrator; orchestrator-only and root-owned instructions apply to it because Codex does not generate a selectable orchestrator agent TOML.",
-    '- On each new root session, when thoth-mem tools are installed and session/project identity is known, call mem_session(action="start") as step 0 before any other thoth-mem call, then save the real user prompt with mem_save(kind="prompt") before later delegation.',
-    "- If thoth-mem tools or identity values are unavailable, disclose that memory bootstrap could not run and continue without claiming memory was saved.",
+    '- On each new root session, first resolve the stable root session identity from Codex request metadata in this order: `nodeRepl.requestMeta["x-codex-turn-metadata"].session_id`, then `nodeRepl.requestMeta["x-codex-turn-metadata"].thread_id`, then `nodeRepl.requestMeta.threadId`. Do not use `nodeRepl.requestMeta["x-codex-turn-metadata"].turn_id` as the stable session id.',
+    '- `nodeRepl.requestMeta["x-codex-turn-metadata"].turn_id` is per-turn metadata only, not the stable root session id.',
+    "- If `nodeRepl.requestMeta` is not yet visible and `tool_search` is available, load/discover the `node_repl` MCP tool before concluding metadata is unavailable.",
+    '- When thoth-mem tools are installed and stable root session identity is resolved, call mem_session(action="start") as step 0 before any other thoth-mem call, then save the real user prompt with mem_save(kind="prompt") before later delegation.',
+    "- If metadata tooling is unavailable, or the required fields are missing, disclose that memory bootstrap could not run and continue without claiming memory was saved.",
     '- Before delegating after meaningful context changes, save or refresh the handoff body with root-owned mem_session(action="summary") or mem_save(kind="session_summary") when available; if unavailable, disclose that root-owned compaction could not be persisted.',
     "- Use the ambient Codex root session as the delegate-first root coordinator; do not generate or select an orchestrator TOML.",
     "- Delegate by invoking `multi_agent_v1.spawn_agent` for the installed Codex role agents: explorer, librarian, oracle, designer, quick, and deep.",

package/dist/cli/index.js

@@ -4,7 +4,7 @@ import {
   getOpenCodeVersion,
   isOpenCodeInstalled,
   opencodeAdapter
-} from "../chunk-YZNH23HZ.js";
+} from "../chunk-5DHG5II4.js";
 import {
   CODEX_ROLE_NAMES,
   RECOMMENDED_SKILLS,
@@ -36,7 +36,7 @@ import {
   getOperationHarness,
   installRecommendedSkill,
   listOperationHarnesses
-} from "../chunk-PDKLWORW.js";
+} from "../chunk-DAZFSPN4.js";
 import {
   ALL_AGENT_NAMES,
   CUSTOM_SKILLS,
@@ -48,7 +48,7 @@ import {
   getExistingLiteConfigPath,
   installCustomSkills,
   writeLiteConfig
-} from "../chunk-HFZAL6NE.js";
+} from "../chunk-76DARQOT.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-PDKLWORW.js";
+} from "../../chunk-DAZFSPN4.js";
 import {
   ALL_AGENT_NAMES,
   DEFAULT_MODELS,
   getExistingLiteConfigPath,
   parseConfig
-} from "../../chunk-HFZAL6NE.js";
+} from "../../chunk-76DARQOT.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-5DHG5II4.js";
 import {
   DEFAULT_THOTH_COMMAND,
   POLL_INTERVAL_BACKGROUND_MS,
@@ -14,7 +14,7 @@ import {
   installCustomSkills,
   loadPluginConfig,
   stripJsonComments
-} from "./chunk-HFZAL6NE.js";
+} from "./chunk-76DARQOT.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.4",
+  "version": "0.2.6",
   "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