thoth-agents 0.2.2 → 0.2.4

package/README.md

@@ -1,6 +1,7 @@
 <div align="center">
-  <img src="img/team.png" alt="thoth-agents agents" width="420">
-  <p><i>Seven specialized agents, one delegate-first workflow across supported harnesses.</i></p>
+<img src="img/team.png" alt="thoth-agents agents" width="420">
+
+<p><i>Seven specialized agents, one delegate-first workflow across supported harnesses.</i></p>
   <p><b>thoth-agents</b> - Multi-harness orchestration - Thoth-mem persistence - Bundled SDD pipeline</p>
   <p>
     <a href="https://github.com/EremesNG/thoth-agents/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/EremesNG/thoth-agents/ci.yml?branch=master&label=CI" alt="CI status"></a>
@@ -50,11 +51,12 @@ hooks, MCP, skills, and per-agent tool permissions.
 
 ## Harness Support
 
-| Harness | Status | Setup path | Notes |
-| --- | --- | --- | --- |
-| OpenCode | Stable default | `npx thoth-agents@latest install` or `npx thoth-agents@latest install --agent=opencode` | Native plugin config, native `task` delegation, optional tmux panes, OpenCode provider auth. |
-| Codex | Supported explicit path | `npx thoth-agents@latest install --agent=codex` | Installs ambient/root guidance, six role subagents, and a Personal plugin source. Requires `/plugins` and `/hooks` trust review. Some governance remains instruction-level. |
-| Claude Code | Supported first-class path | `npx thoth-agents@latest install --agent=claude` | Installs one Claude Code plugin: six specialist subagents (`Task(subagent_type: ...)`), an `orchestrator` agent activated as the main thread via `settings.json`, `.mcp.json`, and bundled skills. Role permissions are enforced by subagent `tools`. |
+
+| Harness     | Status                     | Setup path                                                                              | Notes                                                                                                                                                                                                                                                 |
+| ----------- | -------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| OpenCode    | Stable default             | `npx thoth-agents@latest install` or `npx thoth-agents@latest install --agent=opencode` | Native plugin config, native`task` delegation, optional tmux panes, OpenCode provider auth.                                                                                                                                                           |
+| Codex       | Supported explicit path    | `npx thoth-agents@latest install --agent=codex`                                         | Installs ambient/root guidance, six role subagents, and a Personal plugin source. Requires`/plugins` and `/hooks` trust review. Some governance remains instruction-level.                                                                            |
+| Claude Code | Supported first-class path | `npx thoth-agents@latest install --agent=claude`                                        | Installs one Claude Code plugin: six specialist subagents (`Task(subagent_type: ...)`), an `orchestrator` agent activated as the main thread via `settings.json`, `.mcp.json`, and bundled skills. Role permissions are enforced by subagent `tools`. |
 
 OpenCode can load the plugin with:
 
@@ -314,7 +316,7 @@ clarifies intent, assesses scope, asks for user approval when needed, and routes
 work into direct implementation, accelerated SDD, or full SDD.
 
 ```text
-propose -> [spec || design] -> tasks -> apply -> verify -> archive
+propose -> spec -> clarify -> design -> tasks -> apply -> verify -> archive
 ```
 
 For moderate work, the accelerated path usually runs `propose -> tasks`. For
@@ -323,14 +325,15 @@ artifacts before task execution.
 
 Artifacts can be persisted in four modes:
 
-| Mode | Writes to | Cost | Use when |
-| --- | --- | --- | --- |
-| `thoth-mem` | Memory only | Low | Fast iteration without repo planning files |
-| `openspec` | `openspec/` files only | Medium | Reviewable planning artifacts in the repo |
-| `hybrid` | Both | High | Maximum durability; default |
-| `none` | Neither | Lowest | Ephemeral iterations, no persistence |
 
-Thoth-mem is the local memory MCP used for durable observations, architectural
+| Mode        | Writes to              | Cost   | Use when                                   |
+| ----------- | ---------------------- | ------ | ------------------------------------------ |
+| `thoth-mem` | Memory only            | Low    | Fast iteration without repo planning files |
+| `openspec`  | `openspec/` files only | Medium | Reviewable planning artifacts in the repo  |
+| `hybrid`    | Both                   | High   | Maximum durability; default                |
+| `none`      | Neither                | Lowest | Ephemeral iterations, no persistence       |
+
+[Thoth-mem](https://github.com/EremesNG/thoth-mem) is the local memory MCP used for durable observations, architectural
 decisions, SDD artifacts, and session summaries. The core retrieval pattern is:
 
 1. `mem_recall(mode="compact")` for compact candidate records
@@ -355,12 +358,13 @@ planning/execution, verification, and archiving. It also registers MCP servers
 for docs research, public code search, and local memory where the harness
 supports that delivery surface.
 
-| Surface | Shared concept | OpenCode binding | Codex binding | Claude Code binding |
-| --- | --- | --- | --- | --- |
-| Skills | Requirements, SDD, review, execution workflows | Copied into the OpenCode skills directory when `--skills=yes` | Packaged as plugin-bundled skills for the Personal plugin source | Bundled in the plugin `skills/` directory |
-| MCPs | `exa`, `context7`, `grep_app`, `thoth_mem` | Registered by generated OpenCode plugin config | Packaged/configured only on validated Codex surfaces | Bundled in the plugin `.mcp.json` (`type: "http"` for URL servers) |
-| Delegation | Seven-role specialist workflow | Native `task` tool | Custom agents plus prompt/plugin guidance | Native `Task(subagent_type: ...)` over auto-discovered subagents |
-| Blocking choices | Use a structured question surface | OpenCode `question` tool | `request_user_input` when enabled and available | `AskUserQuestion` tool |
+
+| Surface          | Shared concept                                 | OpenCode binding                                             | Codex binding                                                    | Claude Code binding                                               |
+| ---------------- | ---------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Skills           | Requirements, SDD, review, execution workflows | Copied into the OpenCode skills directory when`--skills=yes` | Packaged as plugin-bundled skills for the Personal plugin source | Bundled in the plugin`skills/` directory                          |
+| MCPs             | `exa`, `context7`, `grep_app`, `thoth_mem`     | Registered by generated OpenCode plugin config               | Packaged/configured only on validated Codex surfaces             | Bundled in the plugin`.mcp.json` (`type: "http"` for URL servers) |
+| Delegation       | Seven-role specialist workflow                 | Native`task` tool                                            | Custom agents plus prompt/plugin guidance                        | Native`Task(subagent_type: ...)` over auto-discovered subagents   |
+| Blocking choices | Use a structured question surface              | OpenCode`question` tool                                      | `request_user_input` when enabled and available                  | `AskUserQuestion` tool                                            |
 
 See [docs/skills-and-mcps.md](docs/skills-and-mcps.md) for the detailed matrix.
 
@@ -400,16 +404,17 @@ corepack prepare pnpm@11.2.2 --activate
 pnpm install
 ```
 
-| Command | Purpose |
-| --- | --- |
-| `pnpm run build` | Build TypeScript into `dist/` and generate declarations/schema |
-| `pnpm run typecheck` | Run TypeScript type checking without emit |
-| `pnpm test` | Run the Vitest suite |
-| `pnpm run lint` | Run Biome linter |
-| `pnpm run format` | Run Biome formatter |
-| `pnpm run check` | Run Biome check with auto-fix |
-| `pnpm run check:ci` | Run Biome check without writes |
-| `pnpm run dev` | Build and launch the OpenCode plugin in local dev mode |
+
+| Command              | Purpose                                                       |
+| -------------------- | ------------------------------------------------------------- |
+| `pnpm run build`     | Build TypeScript into`dist/` and generate declarations/schema |
+| `pnpm run typecheck` | Run TypeScript type checking without emit                     |
+| `pnpm test`          | Run the Vitest suite                                          |
+| `pnpm run lint`      | Run Biome linter                                              |
+| `pnpm run format`    | Run Biome formatter                                           |
+| `pnpm run check`     | Run Biome check with auto-fix                                 |
+| `pnpm run check:ci`  | Run Biome check without writes                                |
+| `pnpm run dev`       | Build and launch the OpenCode plugin in local dev mode        |
 
 ## License
 

package/dist/{chunk-3NOVCFN7.js → chunk-HFZAL6NE.js}

@@ -804,6 +804,7 @@ var CLAUDE_CODE_PROMPT_DIALECT = {
 };
 
 // src/harness/core/sdd.ts
+var SDD_VERIFY_MAX_ROUNDS = 3;
 var SDD_PHASES = [
   {
     id: "requirements-interview",
@@ -822,7 +823,7 @@ var SDD_PHASES = [
     producesArtifact: true,
     owner: "write-capable-agent",
     artifactSkill: "sdd-init",
-    condition: "Only when OpenSpec persistence is selected and openspec/ is missing.",
+    condition: "Only when OpenSpec persistence is selected and openspec/ is missing or stale (partial structure or missing mechanism sections).",
     defaultAgentRole: "quick",
     supportingAgentRoles: ["explorer"],
     delegationReason: "Fast mechanical bootstrap, with explorer supplying repository facts when needed."
@@ -848,7 +849,11 @@ var SDD_PHASES = [
     artifactSkill: "sdd-propose",
     defaultAgentRole: "deep",
     supportingAgentRoles: ["oracle"],
-    delegationReason: "Structured technical reasoning and trade-off synthesis before implementation."
+    delegationReason: "Structured technical reasoning and trade-off synthesis before implementation.",
+    handoffHints: [
+      "Preserve accepted scope and explicit non-goals downstream.",
+      "Carry deferred or discovery affected areas forward as follow-up."
+    ]
   },
   {
     id: "spec",
@@ -860,24 +865,48 @@ var SDD_PHASES = [
     artifactSkill: "sdd-spec",
     defaultAgentRole: "deep",
     supportingAgentRoles: ["oracle"],
-    delegationReason: "High-quality requirement contract work where ambiguity propagates downstream."
+    delegationReason: "High-quality requirement contract work where ambiguity propagates downstream.",
+    handoffHints: [
+      "Preserve recorded Assumptions and any [NEEDS CLARIFICATION] resolutions.",
+      "Keep the requirements-quality checklist resolved before tasks."
+    ]
   },
   {
-    id: "design",
+    id: "clarify",
     order: 5,
     requiredFor: ["full"],
-    prerequisites: ["proposal", "spec"],
+    prerequisites: ["spec"],
+    producesArtifact: false,
+    owner: "write-capable-agent",
+    artifactSkill: "sdd-clarify",
+    defaultAgentRole: "deep",
+    supportingAgentRoles: ["oracle"],
+    delegationReason: "Resolve residual spec ambiguity in place before design consumes it.",
+    handoffHints: [
+      "Preserve clarified resolutions written back into the spec.",
+      "Keep the requirements-quality checklist re-validated before design."
+    ]
+  },
+  {
+    id: "design",
+    order: 6,
+    requiredFor: ["full"],
+    prerequisites: ["proposal", "clarify"],
     producesArtifact: true,
     owner: "write-capable-agent",
     artifactSkill: "sdd-design",
     artifactMeaning: "technical-solution-design",
     defaultAgentRole: "deep",
     supportingAgentRoles: ["designer"],
-    delegationReason: "Technical architecture and file-change design; designer only supports UI/UX concerns."
+    delegationReason: "Technical architecture and file-change design; designer only supports UI/UX concerns.",
+    handoffHints: [
+      "Preserve coverage decisions and architecture constraints in tasks.",
+      "Honor the Constitution Check outcome recorded during design."
+    ]
   },
   {
     id: "tasks",
-    order: 6,
+    order: 7,
     requiredFor: ["accelerated", "full"],
     prerequisites: ["proposal", "spec", "design"],
     producesArtifact: true,
@@ -889,7 +918,7 @@ var SDD_PHASES = [
   },
   {
     id: "plan-review",
-    order: 7,
+    order: 8,
     requiredFor: ["accelerated", "full"],
     prerequisites: ["tasks"],
     producesArtifact: false,
@@ -900,7 +929,7 @@ var SDD_PHASES = [
   },
   {
     id: "implementation-confirmation",
-    order: 8,
+    order: 9,
     requiredFor: ["accelerated", "full"],
     prerequisites: ["plan-review"],
     producesArtifact: false,
@@ -910,7 +939,7 @@ var SDD_PHASES = [
   },
   {
     id: "apply",
-    order: 9,
+    order: 10,
     requiredFor: ["direct", "accelerated", "full"],
     prerequisites: ["implementation-confirmation"],
     producesArtifact: false,
@@ -921,10 +950,12 @@ var SDD_PHASES = [
   },
   {
     id: "verify",
-    order: 10,
+    order: 11,
     requiredFor: ["accelerated", "full"],
     prerequisites: ["apply"],
     producesArtifact: true,
+    gate: "iterative-verify",
+    maxRounds: SDD_VERIFY_MAX_ROUNDS,
     owner: "oracle",
     artifactSkill: "sdd-verify",
     defaultAgentRole: "oracle",
@@ -933,7 +964,7 @@ var SDD_PHASES = [
   },
   {
     id: "archive",
-    order: 11,
+    order: 12,
     requiredFor: ["accelerated", "full"],
     prerequisites: ["verify"],
     producesArtifact: true,
@@ -950,7 +981,7 @@ var SDD_WORKFLOW_CONTRACT = {
     "Scope-faithful invariant: accepted user intent/scope is preserved; unresolved affected areas remain explicit as deferred/discovery follow-up.",
     "Direct implementation is reserved for low-complexity work.",
     "Accelerated SDD follows explore -> proposal -> tasks before execution.",
-    "Full SDD follows explore -> proposal -> spec -> design -> tasks before execution."
+    "Full SDD follows explore -> proposal -> spec -> clarify -> design -> tasks before execution."
   ],
   artifactRules: [
     "SDD delegation defaults are phase-specific: sdd-propose, sdd-spec, and sdd-design default to deep.",
@@ -965,7 +996,8 @@ var SDD_WORKFLOW_CONTRACT = {
   verificationRules: [
     "Plan review must complete before implementation confirmation.",
     "User confirmation is required after plan-review approval and before apply.",
-    "Apply is followed by verify and archive for SDD pipelines."
+    "Apply is followed by verify and archive for SDD pipelines.",
+    "Verify runs as a bounded iterative gate of at most SDD_VERIFY_MAX_ROUNDS rounds; on exhausted failure escalate to the user."
   ]
 };
 function getSddWorkflowContract() {
@@ -975,7 +1007,8 @@ function getSddWorkflowContract() {
       requiredFor: [...phase.requiredFor],
       prerequisites: [...phase.prerequisites],
       alternateAgentRoles: phase.alternateAgentRoles ? [...phase.alternateAgentRoles] : void 0,
-      supportingAgentRoles: phase.supportingAgentRoles ? [...phase.supportingAgentRoles] : void 0
+      supportingAgentRoles: phase.supportingAgentRoles ? [...phase.supportingAgentRoles] : void 0,
+      handoffHints: phase.handoffHints ? [...phase.handoffHints] : void 0
     })),
     routingRules: [...SDD_WORKFLOW_CONTRACT.routingRules],
     artifactRules: [...SDD_WORKFLOW_CONTRACT.artifactRules],
@@ -1072,7 +1105,7 @@ function persistenceSddRole(id) {
 function renderSddDelegationMatrix() {
   return `<sdd-delegation-matrix>
 - sdd-init -> ${primarySddRole("init")} (+${supportSddRoles("init")}, if openspec/ missing); sdd-explore -> ${primarySddRole("explore")} (+${supportSddRoles("explore")})
-- sdd-propose/sdd-spec/sdd-design -> ${primarySddRole("proposal")}; sdd-tasks -> ${primarySddRole("tasks")} (fallback: ${alternateSddRoles("tasks")})
+- sdd-propose/sdd-spec/sdd-design -> ${primarySddRole("proposal")}; sdd-clarify -> ${primarySddRole("clarify")}; sdd-tasks -> ${primarySddRole("tasks")} (fallback: ${alternateSddRoles("tasks")})
 - plan-reviewer -> ${primarySddRole("plan-review")}; sdd-apply -> ${primarySddRole("apply")} (fallback: ${alternateSddRoles("apply")}); sdd-verify -> ${primarySddRole("verify")} (persistence: ${persistenceSddRole("verify")}); sdd-archive -> ${primarySddRole("archive")}
 </sdd-delegation-matrix>`;
 }
@@ -1221,7 +1254,7 @@ Scope-faithful invariant: accepted user intent and scope must not be silently na
 Routes:
 - Direct implementation for low-complexity work.
 - Accelerated SDD: explore -> propose -> tasks.
-- Full SDD: explore -> propose -> spec -> design -> tasks.
+- Full SDD: explore -> propose -> spec -> clarify -> design -> tasks.
 
 ${renderSddDelegationMatrix()}
 
@@ -1231,7 +1264,7 @@ Hard gates:
 - {{role.oracle}} is read-only for plan-reviewer and sdd-verify review; {{role.quick}} persists verify reports 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, dispatch sdd-init first.
+- If openspec persistence is selected and openspec/ is missing or stale (partial structure or missing mechanism sections), dispatch sdd-init first.
 - During SDD execution, batch compatible implementation work.
 - Group consecutive ready SDD tasks for the same execution agent into one dispatch when dependencies, scope, and verification can be handled together. Keep per-task tracking and evidence; do not split a compatible {{role.designer}}/{{role.quick}}/{{role.deep}} run into one delegation per checkbox.
 
@@ -1247,7 +1280,12 @@ Plan gate: after tasks, ask with \`{{userQuestionTool}}\`: "Review plan with {{r
 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.
-Post-execution: delegate sdd-verify, then sdd-archive when verification passes.
+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.
+- On \`fail\` with rounds remaining (round < 3): dispatch a TARGETED \`sdd-apply\` re-run scoped by the verify report's Critical Issue remediation anchors (file and/or scenario), then re-dispatch \`sdd-verify\` as round N+1. Do not expand a scoped fix into a full unscoped re-apply when anchors are present, and do not advance to archive while the verdict is \`fail\`.
+- On \`fail\` at the bound (round 3 still failing): escalate the unresolved failure to the user with \`{{userQuestionTool}}\`. Do not run another apply/verify round and do not silently abandon or auto-archive. If the harness lacks a blocking user-input primitive, report this as an unsupported-capability limitation instead of auto-advancing or looping.
+- On \`pass with warnings\`: escalate with \`{{userQuestionTool}}\` an advance-vs-iterate choice (advance to \`sdd-archive\` vs re-iterate to clear warnings). Never auto-advance and never auto-loop. If the user chooses re-iterate, dispatch a targeted \`sdd-apply\` scoped by the warning remediation anchors and re-verify, subject to the 3-round bound.
 </sdd>
 
 <progress-memory>
@@ -1711,6 +1749,14 @@ var BUNDLED_SKILL_REGISTRY = [
     kind: "skill",
     purpose: "sdd"
   },
+  {
+    name: "sdd-clarify",
+    description: "Resolve residual spec ambiguity in place before design, with a bounded taxonomy-driven clarification pass.",
+    allowedRoles: ORCHESTRATOR_ONLY,
+    sourcePath: "src/skills/sdd-clarify",
+    kind: "skill",
+    purpose: "sdd"
+  },
   {
     name: "sdd-design",
     description: "Create technical solution design artifacts for changes",
@@ -1758,6 +1804,14 @@ var BUNDLED_SKILL_REGISTRY = [
     sourcePath: "src/skills/sdd-archive",
     kind: "skill",
     purpose: "sdd"
+  },
+  {
+    name: "sdd-constitution",
+    description: "Guide a semver constitution amendment and Sync-Impact Report entry.",
+    allowedRoles: ORCHESTRATOR_ONLY,
+    sourcePath: "src/skills/sdd-constitution",
+    kind: "skill",
+    purpose: "sdd"
   }
 ];
 var SKILL_REGISTRY = [

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

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

package/dist/{chunk-3SQ4ZQ57.js → chunk-YZNH23HZ.js}

@@ -13,7 +13,7 @@ import {
   getStepBudgetPromptSection,
   loadAgentPrompt,
   renderRolePrompt
-} from "./chunk-3NOVCFN7.js";
+} from "./chunk-HFZAL6NE.js";
 
 // src/agents/deep.ts
 var DEEP_PROMPT = renderRolePrompt(
@@ -587,6 +587,7 @@ function spawnSync(command, options = {}) {
 // src/cli/system.ts
 import { statSync } from "fs";
 var cachedOpenCodePath = null;
+var OPENCODE_PROBE_TIMEOUT_MS = 1500;
 function quoteWindowsShellCommand(command) {
   if (!/[\s&()^<>"|]/.test(command)) {
     return command;
@@ -674,10 +675,30 @@ async function isOpenCodeInstalled() {
     try {
       const invocation = getOpenCodeVersionInvocation(opencodePath);
       const proc = spawn(invocation.command, invocation.options);
-      await proc.exited;
-      if (proc.exitCode === 0) {
-        cachedOpenCodePath = opencodePath;
-        return true;
+      let timer;
+      const timedOut = /* @__PURE__ */ Symbol("timeout");
+      try {
+        const outcome = await Promise.race([
+          proc.exited.then(() => proc.exitCode),
+          new Promise((resolve) => {
+            timer = setTimeout(
+              () => resolve(timedOut),
+              OPENCODE_PROBE_TIMEOUT_MS
+            );
+          })
+        ]);
+        if (outcome === timedOut) {
+          proc.kill();
+          continue;
+        }
+        if (outcome === 0) {
+          cachedOpenCodePath = opencodePath;
+          return true;
+        }
+      } finally {
+        if (timer) {
+          clearTimeout(timer);
+        }
       }
     } catch {
     }

package/dist/cli/index.js

@@ -4,7 +4,7 @@ import {
   getOpenCodeVersion,
   isOpenCodeInstalled,
   opencodeAdapter
-} from "../chunk-3SQ4ZQ57.js";
+} from "../chunk-YZNH23HZ.js";
 import {
   CODEX_ROLE_NAMES,
   RECOMMENDED_SKILLS,
@@ -36,7 +36,7 @@ import {
   getOperationHarness,
   installRecommendedSkill,
   listOperationHarnesses
-} from "../chunk-FRZZ25ND.js";
+} from "../chunk-PDKLWORW.js";
 import {
   ALL_AGENT_NAMES,
   CUSTOM_SKILLS,
@@ -48,7 +48,7 @@ import {
   getExistingLiteConfigPath,
   installCustomSkills,
   writeLiteConfig
-} from "../chunk-3NOVCFN7.js";
+} from "../chunk-HFZAL6NE.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-FRZZ25ND.js";
+} from "../../chunk-PDKLWORW.js";
 import {
   ALL_AGENT_NAMES,
   DEFAULT_MODELS,
   getExistingLiteConfigPath,
   parseConfig
-} from "../../chunk-3NOVCFN7.js";
+} from "../../chunk-HFZAL6NE.js";
 
 // src/cli/tui/index.tsx
 import { render } from "ink";

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

@@ -1,13 +1,14 @@
 import type { AgentRoleName } from './agent-pack';
 export type SddPipelineType = 'direct' | 'accelerated' | 'full';
-export type SddPhaseId = 'requirements-interview' | 'init' | 'explore' | 'proposal' | 'spec' | 'design' | 'tasks' | 'plan-review' | 'implementation-confirmation' | 'apply' | 'verify' | 'archive';
+export type SddPhaseId = 'requirements-interview' | 'init' | 'explore' | 'proposal' | 'spec' | 'clarify' | 'design' | 'tasks' | 'plan-review' | 'implementation-confirmation' | 'apply' | 'verify' | 'archive';
 export interface SddPhaseContract {
     id: SddPhaseId;
     order: number;
     requiredFor: SddPipelineType[];
     prerequisites: SddPhaseId[];
     producesArtifact: boolean;
-    gate?: 'oracle-review' | 'user-confirmation';
+    gate?: 'oracle-review' | 'user-confirmation' | 'iterative-verify';
+    maxRounds?: number;
     owner: 'orchestrator' | 'read-only-agent' | 'write-capable-agent' | 'oracle' | 'user';
     artifactSkill?: string;
     artifactMeaning?: string;
@@ -17,6 +18,7 @@ export interface SddPhaseContract {
     supportingAgentRoles?: AgentRoleName[];
     persistenceAgentRole?: AgentRoleName;
     delegationReason?: string;
+    handoffHints?: string[];
 }
 export interface SddWorkflowContract {
     phases: SddPhaseContract[];
@@ -24,7 +26,8 @@ export interface SddWorkflowContract {
     artifactRules: string[];
     verificationRules: string[];
 }
-export declare const FULL_SDD_PHASE_ORDER: readonly ["requirements-interview", "explore", "proposal", "spec", "design", "tasks", "plan-review", "implementation-confirmation", "apply", "verify", "archive"];
+export declare const FULL_SDD_PHASE_ORDER: readonly ["requirements-interview", "explore", "proposal", "spec", "clarify", "design", "tasks", "plan-review", "implementation-confirmation", "apply", "verify", "archive"];
+export declare const SDD_VERIFY_MAX_ROUNDS = 3;
 export declare const SDD_PHASES: readonly [{
     readonly id: "requirements-interview";
     readonly order: 0;
@@ -41,7 +44,7 @@ export declare const SDD_PHASES: readonly [{
     readonly producesArtifact: true;
     readonly owner: "write-capable-agent";
     readonly artifactSkill: "sdd-init";
-    readonly condition: "Only when OpenSpec persistence is selected and openspec/ is missing.";
+    readonly condition: "Only when OpenSpec persistence is selected and openspec/ is missing or stale (partial structure or missing mechanism sections).";
     readonly defaultAgentRole: "quick";
     readonly supportingAgentRoles: ["explorer"];
     readonly delegationReason: "Fast mechanical bootstrap, with explorer supplying repository facts when needed.";
@@ -66,6 +69,7 @@ export declare const SDD_PHASES: readonly [{
     readonly defaultAgentRole: "deep";
     readonly supportingAgentRoles: ["oracle"];
     readonly delegationReason: "Structured technical reasoning and trade-off synthesis before implementation.";
+    readonly handoffHints: ["Preserve accepted scope and explicit non-goals downstream.", "Carry deferred or discovery affected areas forward as follow-up."];
 }, {
     readonly id: "spec";
     readonly order: 4;
@@ -77,11 +81,24 @@ export declare const SDD_PHASES: readonly [{
     readonly defaultAgentRole: "deep";
     readonly supportingAgentRoles: ["oracle"];
     readonly delegationReason: "High-quality requirement contract work where ambiguity propagates downstream.";
+    readonly handoffHints: ["Preserve recorded Assumptions and any [NEEDS CLARIFICATION] resolutions.", "Keep the requirements-quality checklist resolved before tasks."];
 }, {
-    readonly id: "design";
+    readonly id: "clarify";
     readonly order: 5;
     readonly requiredFor: ["full"];
-    readonly prerequisites: ["proposal", "spec"];
+    readonly prerequisites: ["spec"];
+    readonly producesArtifact: false;
+    readonly owner: "write-capable-agent";
+    readonly artifactSkill: "sdd-clarify";
+    readonly defaultAgentRole: "deep";
+    readonly supportingAgentRoles: ["oracle"];
+    readonly delegationReason: "Resolve residual spec ambiguity in place before design consumes it.";
+    readonly handoffHints: ["Preserve clarified resolutions written back into the spec.", "Keep the requirements-quality checklist re-validated before design."];
+}, {
+    readonly id: "design";
+    readonly order: 6;
+    readonly requiredFor: ["full"];
+    readonly prerequisites: ["proposal", "clarify"];
     readonly producesArtifact: true;
     readonly owner: "write-capable-agent";
     readonly artifactSkill: "sdd-design";
@@ -89,9 +106,10 @@ export declare const SDD_PHASES: readonly [{
     readonly defaultAgentRole: "deep";
     readonly supportingAgentRoles: ["designer"];
     readonly delegationReason: "Technical architecture and file-change design; designer only supports UI/UX concerns.";
+    readonly handoffHints: ["Preserve coverage decisions and architecture constraints in tasks.", "Honor the Constitution Check outcome recorded during design."];
 }, {
     readonly id: "tasks";
-    readonly order: 6;
+    readonly order: 7;
     readonly requiredFor: ["accelerated", "full"];
     readonly prerequisites: ["proposal", "spec", "design"];
     readonly producesArtifact: true;
@@ -102,7 +120,7 @@ export declare const SDD_PHASES: readonly [{
     readonly delegationReason: "Mechanical conversion of settled design into dependency-ordered execution tasks.";
 }, {
     readonly id: "plan-review";
-    readonly order: 7;
+    readonly order: 8;
     readonly requiredFor: ["accelerated", "full"];
     readonly prerequisites: ["tasks"];
     readonly producesArtifact: false;
@@ -112,7 +130,7 @@ export declare const SDD_PHASES: readonly [{
     readonly delegationReason: "Independent read-only executability review of tasks before implementation.";
 }, {
     readonly id: "implementation-confirmation";
-    readonly order: 8;
+    readonly order: 9;
     readonly requiredFor: ["accelerated", "full"];
     readonly prerequisites: ["plan-review"];
     readonly producesArtifact: false;
@@ -121,7 +139,7 @@ export declare const SDD_PHASES: readonly [{
     readonly delegationReason: "Human approval gate after reviewed tasks and before workspace implementation.";
 }, {
     readonly id: "apply";
-    readonly order: 9;
+    readonly order: 10;
     readonly requiredFor: ["direct", "accelerated", "full"];
     readonly prerequisites: ["implementation-confirmation"];
     readonly producesArtifact: false;
@@ -131,10 +149,12 @@ export declare const SDD_PHASES: readonly [{
     readonly delegationReason: "Correctness-heavy implementation by default; quick handles mechanical batches and designer owns UI/visual work.";
 }, {
     readonly id: "verify";
-    readonly order: 10;
+    readonly order: 11;
     readonly requiredFor: ["accelerated", "full"];
     readonly prerequisites: ["apply"];
     readonly producesArtifact: true;
+    readonly gate: "iterative-verify";
+    readonly maxRounds: 3;
     readonly owner: "oracle";
     readonly artifactSkill: "sdd-verify";
     readonly defaultAgentRole: "oracle";
@@ -142,7 +162,7 @@ export declare const SDD_PHASES: readonly [{
     readonly delegationReason: "Independent verification review; quick persists the report when the selected store requires writes.";
 }, {
     readonly id: "archive";
-    readonly order: 11;
+    readonly order: 12;
     readonly requiredFor: ["accelerated", "full"];
     readonly prerequisites: ["verify"];
     readonly producesArtifact: true;

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

@@ -51,6 +51,13 @@ export declare const BUNDLED_SKILL_REGISTRY: readonly [{
     readonly sourcePath: "src/skills/sdd-spec";
     readonly kind: "skill";
     readonly purpose: "sdd";
+}, {
+    readonly name: "sdd-clarify";
+    readonly description: "Resolve residual spec ambiguity in place before design, with a bounded taxonomy-driven clarification pass.";
+    readonly allowedRoles: AgentRoleName[];
+    readonly sourcePath: "src/skills/sdd-clarify";
+    readonly kind: "skill";
+    readonly purpose: "sdd";
 }, {
     readonly name: "sdd-design";
     readonly description: "Create technical solution design artifacts for changes";
@@ -93,6 +100,13 @@ export declare const BUNDLED_SKILL_REGISTRY: readonly [{
     readonly sourcePath: "src/skills/sdd-archive";
     readonly kind: "skill";
     readonly purpose: "sdd";
+}, {
+    readonly name: "sdd-constitution";
+    readonly description: "Guide a semver constitution amendment and Sync-Impact Report entry.";
+    readonly allowedRoles: AgentRoleName[];
+    readonly sourcePath: "src/skills/sdd-constitution";
+    readonly kind: "skill";
+    readonly purpose: "sdd";
 }];
 export declare const SKILL_REGISTRY: readonly [{
     readonly name: "requirements-interview";
@@ -136,6 +150,13 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly sourcePath: "src/skills/sdd-spec";
     readonly kind: "skill";
     readonly purpose: "sdd";
+}, {
+    readonly name: "sdd-clarify";
+    readonly description: "Resolve residual spec ambiguity in place before design, with a bounded taxonomy-driven clarification pass.";
+    readonly allowedRoles: AgentRoleName[];
+    readonly sourcePath: "src/skills/sdd-clarify";
+    readonly kind: "skill";
+    readonly purpose: "sdd";
 }, {
     readonly name: "sdd-design";
     readonly description: "Create technical solution design artifacts for changes";
@@ -178,6 +199,13 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly sourcePath: "src/skills/sdd-archive";
     readonly kind: "skill";
     readonly purpose: "sdd";
+}, {
+    readonly name: "sdd-constitution";
+    readonly description: "Guide a semver constitution amendment and Sync-Impact Report entry.";
+    readonly allowedRoles: AgentRoleName[];
+    readonly sourcePath: "src/skills/sdd-constitution";
+    readonly kind: "skill";
+    readonly purpose: "sdd";
 }, SkillRegistryEntry];
 export declare function getSkillRegistry(): SkillRegistryEntry[];
 export declare function getBundledSkillRegistry(): SkillRegistryEntry[];