thoth-agents 0.3.8 → 0.3.10

package/package.json

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

package/plugin/.claude-plugin/.thoth-agents-plugin-assets.json

@@ -34,7 +34,7 @@
     {
       "path": "agents/orchestrator.md",
       "kind": "agent-config",
-      "sha256": "sha256:b39b6cb996d5dcb38dc66bb83bfd7d6dacbb75d9e1de9097ce2416e64d630b9e"
+      "sha256": "sha256:9a1a9de425e7499110e457b58481d953391d07841dc319f0f8c7b09d64fa8998"
     },
     {
       "path": "agents/quick.md",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "thoth-agents",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "Adaptive multi-harness agent pack with seven roles and a runtime-autonomous Spec Kit-compatible SDD bundle for Claude Code.",
   "author": {
     "name": "thoth-agents"

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "thoth-agents",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "Bundled Spec Kit-compatible SDD skills and MCP configuration; the seven-role global Codex layer requires thoth-agents CLI setup.",
   "skills": "./skills/",
   "mcpServers": "./codex.mcp.json"

package/plugin/agents/orchestrator.md

@@ -13,10 +13,19 @@ You are the adaptive root for thoth-agents. Keep requirements, decisions, execut
 - Delegate only for net gain from specialization, context isolation, review, or safe parallelism. The maximum delegation depth is 1; children never delegate.
 - Maintain one writer for each mutable surface. Parallelize only independent work with no overlapping writes.
 - Keep prompts bounded; request distilled evidence, not raw logs or full files.
+- Preserve unrelated changes; report changed files, evidence, risks, and capability gaps.
 - Use `AskUserQuestion` only when a material unresolved choice changes the result. Continue all safe non-blocked work first.
 - Use `TodoWrite` only when the work genuinely has multiple dependent steps.
 </operating-model>
 
+<delegation-lifecycle>
+- A new objective, SDD phase, mutable surface, or independent judgment is a work boundary: start a fresh specialist using a normal `Agent` invocation. Never treat completed agents as a reusable role pool.
+- Independent context: do not use `fork` for independent work.
+- Continue with `SendMessage` to the prior agent ID only to steer, complete, or clarify the same bounded assignment; never to cross a work boundary.
+- TaskOutput on the same task session only collects the active nonterminal assignment and does not authorize later reuse.
+- Every Oracle plan review, verification round, and approval or PASS judgment uses a fresh Oracle instance. An existing Oracle session may only clarify its current findings.
+</delegation-lifecycle>
+
 <routing>
 - thoth-agents:explorer: Resolve broad or uncertain repository questions and return distilled evidence.
 - thoth-agents:librarian: Gather current authoritative evidence and separate documented facts from inference.
@@ -55,29 +64,20 @@ You are the adaptive root for thoth-agents. Keep requirements, decisions, execut
 </external-skills>
 
 <memory>
-- Load the installed `thoth-mem` skill for resume or prior work and provider-backed memory; never invent its protocol.
-- Preserve a durable decision, root cause, convention, or discovery only when reusable. Root owns the stable root session ID, project, lifecycle, real-user intent, and authorization; never invent identity or confirmed effects.
-- Follow the skill at verified compaction and a meaningful semantic boundary. Children receive only bounded MEMORY dispatch and never own root lifecycle.
-- `openspec/` remains canonical; do not mirror SDD phase artifacts into provider memory. A memory failure degrades memory only and does not block unrelated implementation or verification.
+- Load the installed `thoth-mem` skill for resume or prior work; never invent its protocol.
+- Preserve a durable decision, root cause, convention, or discovery only when reusable. Root owns the stable root session ID, project, lifecycle, real-user intent, and authorization.
+- Follow the skill at verified compaction or a meaningful semantic boundary; children receive only bounded MEMORY and never own root lifecycle.
+- `openspec/` remains canonical; do not mirror SDD phase artifacts. A memory failure does not block unrelated work.
 </memory>
 
 <artifacts>
-- Preserve Spec Kit semantics inside openspec/changes/<feature>/.
-- Accelerated and Full require spec.md, plan.md, tasks.md, verify-report.md, and archive-report.md; optional when useful: checklists/requirements.md, research.md, data-model.md, contracts/, quickstart.md, plan-review.md.
-- Root owns openspec/ coordination and thoth-sdd gates; product work has one writer, and root alone moves [~] -> [x] after evidence.
-- thoth-agents:oracle returns read-only findings. Root persists verification; after PASS, archive syncs declared durable deltas and moves the change to openspec/changes/archive/YYYY-MM-DD-<feature>/.
+- In openspec/changes/<feature>/, Accelerated and Full require spec.md, plan.md, tasks.md, verify-report.md, and archive-report.md.
+- Root owns openspec/ gates and task state, moves [~] -> [x] after evidence, and keeps one product writer.
+- thoth-agents:oracle returns read-only findings; root persists verification and archives declared durable deltas after PASS.
 </artifacts>
 
-<execution>
-- Validate contracts and tests first; use test-first work for behavior. Root or one writer implements; do not delegate merely because an agent exists.
-- thoth-agents:oracle 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>
-
 <delegation>
-- Dispatch through `Agent` with this envelope; use the same boundaries for non-SDD work.
-- Parallelize only independent work and await requested results before synthesis.
+- Use this envelope for all `Agent` delegation; parallelize only independent work and await results.
 - Child return fields: conclusion, evidence, verification, risks, openQuestions, nextAction.
 
 ## PHASE

package/plugin/skills/thoth-archive/SKILL.md

@@ -31,6 +31,13 @@ The script reads delta metadata directly from `spec.md`:
 - `[RENAMED capability FROM Previous title]` renames and replaces it.
 - `[INTERNAL]` never changes `openspec/specs/`.
 
+The SDD validator preflights these operations against the canonical requirement
+titles from `specify` onward. Archive reuses the same ordered parser and
+preflight as a final defense before staging writes, preserving stable
+`SDD-SPEC-DELTA-*` incompatibility codes. An `ADDED` warning for an existing
+nonempty capability requires semantic-overlap review because differently named
+requirements cannot be proven distinct by exact-title tooling alone.
+
 All delta targets are validated before any permanent specification changes. The
 operation stages and rolls back the full canonical update if a delta, report
 update, or final move raises a handled error in the active process. Report and

package/plugin/skills/thoth-archive/scripts/archive.mjs

@@ -10,8 +10,13 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
+import {
+  CAPABILITY_PATTERN,
+  parseCanonicalSpec,
+  parseRequirementDelta as parseSharedRequirementDelta,
+  preflightRequirementDeltas,
+} from '../../thoth-sdd/scripts/durable-deltas.mjs';
 
-const CAPABILITY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const TEST_FAULTS = new Set(
   (process.env.THOTH_ARCHIVE_TEST_FAULT ?? '')
     .split(',')
@@ -270,26 +275,8 @@ function assertArchivable(change, contract) {
 }
 
 function parseDeltaMetadata(metadata) {
-  if (metadata === 'INTERNAL') return { operation: 'INTERNAL' };
-
-  const change = /^(ADDED|MODIFIED|REMOVED)\s+(\S+)$/.exec(metadata);
-  if (change && CAPABILITY_PATTERN.test(change[2])) {
-    return { operation: change[1], capability: change[2] };
-  }
-
-  const rename = /^RENAMED\s+(\S+)\s+FROM\s+(.+)$/.exec(metadata);
-  if (
-    rename &&
-    CAPABILITY_PATTERN.test(rename[1]) &&
-    rename[2].trim().length > 0
-  ) {
-    return {
-      operation: 'RENAMED',
-      capability: rename[1],
-      previousTitle: rename[2].trim(),
-    };
-  }
-
+  const delta = parseSharedRequirementDelta(metadata);
+  if (delta) return delta;
   throw new Error(`Invalid requirement delta metadata: [${metadata}]`);
 }
 
@@ -418,27 +405,6 @@ function parseChangeSpec(spec) {
   };
 }
 
-function parseCanonicalSpec(content) {
-  const headings = [...content.matchAll(/^### Requirement:\s+(.+?)\s*$/gm)];
-  const requirements = new Map();
-  const prefix =
-    headings.length === 0
-      ? content.trimEnd()
-      : content.slice(0, headings[0].index).trimEnd();
-
-  for (const [index, heading] of headings.entries()) {
-    const start = heading.index ?? 0;
-    const end = headings[index + 1]?.index ?? content.length;
-    const title = heading[1].trim();
-    if (requirements.has(title)) {
-      throw new Error(`Canonical specification repeats requirement: ${title}`);
-    }
-    requirements.set(title, content.slice(start, end).trim());
-  }
-
-  return { prefix, requirements };
-}
-
 function newCanonicalSpec(capability) {
   const title = capability
     .split('-')
@@ -480,41 +446,34 @@ function planCanonicalUpdates(specRoot, deltas) {
   for (const [capability, capabilityDeltas] of byCapability) {
     const path = join(specRoot, capability, 'spec.md');
     const present = existsSync(path);
-    const canonical = present
-      ? parseCanonicalSpec(readFileSync(path, 'utf8'))
-      : newCanonicalSpec(capability);
+    let canonical;
+    try {
+      canonical = present
+        ? parseCanonicalSpec(readFileSync(path, 'utf8'))
+        : newCanonicalSpec(capability);
+    } catch (error) {
+      throw new Error(
+        `SDD-SPEC-DELTA-BASELINE: ${capability} canonical baseline is invalid: ${errorMessage(error)}`,
+      );
+    }
+    const preflight = preflightRequirementDeltas({
+      capability,
+      present,
+      requirements: canonical.requirements,
+      deltas: capabilityDeltas,
+    });
+    if (preflight.errors.length > 0) {
+      const [first] = preflight.errors;
+      throw new Error(`${first.code}: ${first.message}`);
+    }
 
     for (const delta of capabilityDeltas) {
       if (delta.operation === 'ADDED') {
-        if (canonical.requirements.has(delta.title)) {
-          throw new Error(
-            `${capability} already contains requirement: ${delta.title}`,
-          );
-        }
         canonical.requirements.set(delta.title, renderRequirement(delta));
         continue;
       }
 
-      if (!present) {
-        throw new Error(
-          `${capability} has no canonical specification for ${delta.operation}`,
-        );
-      }
-
       if (delta.operation === 'RENAMED') {
-        if (!canonical.requirements.has(delta.previousTitle)) {
-          throw new Error(
-            `${capability} does not contain requirement: ${delta.previousTitle}`,
-          );
-        }
-        if (
-          delta.previousTitle !== delta.title &&
-          canonical.requirements.has(delta.title)
-        ) {
-          throw new Error(
-            `${capability} already contains requirement: ${delta.title}`,
-          );
-        }
         const entries = [...canonical.requirements.entries()];
         canonical.requirements = new Map(
           entries.map(([title, block]) =>
@@ -526,11 +485,6 @@ function planCanonicalUpdates(specRoot, deltas) {
         continue;
       }
 
-      if (!canonical.requirements.has(delta.title)) {
-        throw new Error(
-          `${capability} does not contain requirement: ${delta.title}`,
-        );
-      }
       if (delta.operation === 'MODIFIED') {
         canonical.requirements.set(delta.title, renderRequirement(delta));
       } else if (delta.operation === 'REMOVED') {

package/plugin/skills/thoth-sdd/references/phases/specify.md

@@ -11,6 +11,16 @@ implementation-neutral.
   `None`).
 - Define prioritized, independently testable `US#` stories. Every story needs
   `Covers: FR-###, SC-###` and Given/When/Then acceptance scenarios.
+- Before choosing durable delta metadata, read
+  `openspec/specs/<capability>/spec.md` when it exists and compare the exact
+  `### Requirement:` titles and normative behavior:
+  - use `ADDED` only when no canonical requirement already expresses the
+    behavior;
+  - use `MODIFIED` or `REMOVED` only with the exact existing title;
+  - use `RENAMED <capability> FROM <exact previous title>` when the title changes;
+  - only `ADDED` is valid when the canonical capability does not exist.
+  A validator warning on `ADDED` into an existing nonempty capability requires
+  semantic-overlap review; exact-title validity alone does not prove new intent.
 - Give every sequential FR a descriptive title, a normative `MUST`/`SHALL`
   statement, and exactly one delta marker: `INTERNAL`, `ADDED`, `MODIFIED`,
   `REMOVED`, or `RENAMED ... FROM ...`.
@@ -20,4 +30,5 @@ implementation-neutral.
 - State assumptions, dependencies, edge cases, and explicit non-goals.
 
 Do not advance while a material ambiguity would change scope, behavior,
-architecture, or durable delta intent.
+architecture, or durable delta intent. Run the `specify` gate before planning;
+do not defer canonical delta reconciliation until archive.

package/plugin/skills/thoth-sdd/scripts/durable-deltas.mjs

@@ -0,0 +1,158 @@
+export const CAPABILITY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function parseRequirementDelta(metadata) {
+  if (metadata === 'INTERNAL') return { operation: 'INTERNAL' };
+
+  const change = /^(ADDED|MODIFIED|REMOVED)\s+(\S+)$/.exec(metadata);
+  if (change && CAPABILITY_PATTERN.test(change[2])) {
+    return { operation: change[1], capability: change[2] };
+  }
+
+  const rename = /^RENAMED\s+(\S+)\s+FROM\s+(.+)$/.exec(metadata);
+  if (
+    rename &&
+    CAPABILITY_PATTERN.test(rename[1]) &&
+    rename[2].trim().length > 0
+  ) {
+    return {
+      operation: 'RENAMED',
+      capability: rename[1],
+      previousTitle: rename[2].trim(),
+    };
+  }
+
+  return undefined;
+}
+
+export function parseCanonicalSpec(content) {
+  const candidates = [...content.matchAll(/^### Requirement:[^\r\n]*$/gm)];
+  const headings = [
+    ...content.matchAll(/^### Requirement:[ \t]+(\S(?:[^\r\n]*?\S)?)[ \t]*$/gm),
+  ];
+  if (candidates.length !== headings.length) {
+    throw new Error(
+      'Canonical specification contains a malformed Requirement heading',
+    );
+  }
+  const requirements = new Map();
+  const prefix =
+    headings.length === 0
+      ? content.trimEnd()
+      : content.slice(0, headings[0].index).trimEnd();
+
+  for (const [index, heading] of headings.entries()) {
+    const start = heading.index ?? 0;
+    const end = headings[index + 1]?.index ?? content.length;
+    const title = heading[1].trim();
+    if (requirements.has(title)) {
+      throw new Error(`Canonical specification repeats requirement: ${title}`);
+    }
+    requirements.set(title, content.slice(start, end).trim());
+  }
+
+  return { prefix, requirements };
+}
+
+function issue(code, capability, title, message) {
+  return { code, capability, title, message };
+}
+
+export function preflightRequirementDeltas({
+  capability,
+  present,
+  requirements,
+  deltas,
+}) {
+  const initialTitles = [...requirements.keys()];
+  const titles = new Set(initialTitles);
+  const errors = [];
+  const warnings = [];
+
+  for (const delta of deltas) {
+    if (delta.operation === 'ADDED') {
+      if (titles.has(delta.title)) {
+        errors.push(
+          issue(
+            'SDD-SPEC-DELTA-ADDED-EXISTS',
+            capability,
+            delta.title,
+            `${capability} already contains requirement: ${delta.title}`,
+          ),
+        );
+        continue;
+      }
+      if (present && initialTitles.length > 0) {
+        warnings.push(
+          issue(
+            'SDD-SPEC-DELTA-ADDED-REVIEW',
+            capability,
+            delta.title,
+            `${capability} already contains canonical requirements; confirm ${delta.title} does not overlap: ${initialTitles.join(', ')}`,
+          ),
+        );
+      }
+      titles.add(delta.title);
+      continue;
+    }
+
+    if (!present) {
+      const code =
+        delta.operation === 'RENAMED'
+          ? 'SDD-SPEC-DELTA-RENAMED-SOURCE-MISSING'
+          : `SDD-SPEC-DELTA-${delta.operation}-MISSING`;
+      errors.push(
+        issue(
+          code,
+          capability,
+          delta.title,
+          `${capability} has no canonical specification for ${delta.operation}: ${delta.title}`,
+        ),
+      );
+      continue;
+    }
+
+    if (delta.operation === 'RENAMED') {
+      if (!titles.has(delta.previousTitle)) {
+        errors.push(
+          issue(
+            'SDD-SPEC-DELTA-RENAMED-SOURCE-MISSING',
+            capability,
+            delta.title,
+            `${capability} does not contain requirement: ${delta.previousTitle}`,
+          ),
+        );
+        continue;
+      }
+      if (delta.previousTitle !== delta.title && titles.has(delta.title)) {
+        errors.push(
+          issue(
+            'SDD-SPEC-DELTA-RENAMED-TARGET-EXISTS',
+            capability,
+            delta.title,
+            `${capability} already contains requirement: ${delta.title}`,
+          ),
+        );
+        continue;
+      }
+      titles.delete(delta.previousTitle);
+      titles.add(delta.title);
+      continue;
+    }
+
+    if (!titles.has(delta.title)) {
+      errors.push(
+        issue(
+          `SDD-SPEC-DELTA-${delta.operation}-MISSING`,
+          capability,
+          delta.title,
+          `${capability} does not contain requirement: ${delta.title}`,
+        ),
+      );
+      continue;
+    }
+
+    if (delta.operation === 'REMOVED') titles.delete(delta.title);
+  }
+
+  return { errors, warnings, titles };
+}

package/plugin/skills/thoth-sdd/scripts/validate.mjs

@@ -2,6 +2,12 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join, posix, resolve } from 'node:path';
+import {
+  CAPABILITY_PATTERN,
+  parseCanonicalSpec,
+  parseRequirementDelta,
+  preflightRequirementDeltas,
+} from './durable-deltas.mjs';
 
 function parseArgs(argv) {
   const values = { route: 'full', through: 'ready', json: false };
@@ -86,34 +92,6 @@ function checkUniqueSequential(ids, prefix, artifact, errors) {
   }
 }
 
-const CAPABILITY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-
-function parseRequirementDelta(metadata) {
-  if (metadata === 'INTERNAL') {
-    return { operation: 'INTERNAL' };
-  }
-
-  const change = /^(ADDED|MODIFIED|REMOVED)\s+(\S+)$/.exec(metadata);
-  if (change && CAPABILITY_PATTERN.test(change[2])) {
-    return { operation: change[1], capability: change[2] };
-  }
-
-  const rename = /^RENAMED\s+(\S+)\s+FROM\s+(.+)$/.exec(metadata);
-  if (
-    rename &&
-    CAPABILITY_PATTERN.test(rename[1]) &&
-    rename[2].trim().length > 0
-  ) {
-    return {
-      operation: 'RENAMED',
-      capability: rename[1],
-      previousTitle: rename[2].trim(),
-    };
-  }
-
-  return undefined;
-}
-
 function parseAffectedCapabilities(intentSection) {
   const match = /^\*\*Affected capabilities\*\*:\s*(.+)$/im.exec(
     intentSection ?? '',
@@ -264,6 +242,7 @@ function validateSpec(content, errors) {
       ),
     );
   }
+  const durableDeltas = [];
   if (frIds.length === 0) {
     errors.push(issue('SDD-SPEC-FR', artifact, 'Add FR-### requirements.'));
   } else {
@@ -298,6 +277,11 @@ function validateSpec(content, errors) {
             `FR-${match[1]} targets undeclared capability ${delta.capability}.`,
           ),
         );
+      } else if (delta.operation !== 'INTERNAL') {
+        durableDeltas.push({
+          title: match[2].trim(),
+          ...delta,
+        });
       }
     }
   }
@@ -369,9 +353,56 @@ function validateSpec(content, errors) {
     outcomeScIds: successCriteria
       .filter((match) => match[2].toLowerCase() === 'outcome')
       .map((match) => match[1]),
+    durableDeltas,
   };
 }
 
+function validateDurableDeltaIntent(specRoot, deltas, errors, warnings) {
+  const byCapability = new Map();
+  for (const delta of deltas) {
+    const current = byCapability.get(delta.capability) ?? [];
+    current.push(delta);
+    byCapability.set(delta.capability, current);
+  }
+
+  for (const [capability, capabilityDeltas] of byCapability) {
+    const path = join(specRoot, capability, 'spec.md');
+    const present = existsSync(path);
+    let canonical;
+    try {
+      canonical = present
+        ? parseCanonicalSpec(readFileSync(path, 'utf8'))
+        : { requirements: new Map() };
+    } catch (error) {
+      errors.push(
+        issue(
+          'SDD-SPEC-DELTA-BASELINE',
+          'spec.md',
+          `${capability} canonical baseline is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        ),
+      );
+      continue;
+    }
+
+    const result = preflightRequirementDeltas({
+      capability,
+      present,
+      requirements: canonical.requirements,
+      deltas: capabilityDeltas,
+    });
+    errors.push(
+      ...result.errors.map((entry) =>
+        issue(entry.code, 'spec.md', entry.message),
+      ),
+    );
+    warnings.push(
+      ...result.warnings.map((entry) =>
+        issue(entry.code, 'spec.md', entry.message),
+      ),
+    );
+  }
+}
+
 function constitutionEntries(content) {
   if (content === undefined) return [];
   return content
@@ -1047,6 +1078,14 @@ function validate({ change, route, through }) {
 
   const specContract =
     spec === undefined ? undefined : validateSpec(spec, errors);
+  if (specContract !== undefined) {
+    validateDurableDeltaIntent(
+      join(root, '..', '..', 'specs'),
+      specContract.durableDeltas,
+      errors,
+      warnings,
+    );
+  }
   const constitution = readArtifact(
     join(root, '..', '..'),
     'memory/constitution.md',

package/plugin/skills/thoth-sdd/templates/spec.md

@@ -30,7 +30,15 @@ As a [actor], I can [capability] so that [value].
 
 ## Functional requirements
 
-- **FR-001 — [Requirement name]**: `[ADDED capability-slug]` The system MUST [observable behavior].
+- **FR-001 — [Requirement name]**: `[DELTA capability-slug]` The system MUST [observable behavior].
+
+Replace `DELTA` after inspecting `openspec/specs/<capability>/spec.md`. Use
+`ADDED` only for behavior not expressed by a canonical requirement, `MODIFIED`
+or `REMOVED` only with the exact existing requirement title, and
+`RENAMED capability-slug FROM Exact previous title` when the title changes. Only
+`ADDED` is valid when the canonical capability is absent. An addition to an
+existing nonempty capability requires semantic-overlap review even when its
+exact title is new.
 
 Use exactly one delta marker per FR: `[INTERNAL]`, `[ADDED capability-slug]`,
 `[MODIFIED capability-slug]`, `[REMOVED capability-slug]`, or

package/skills/thoth-archive/SKILL.md

@@ -31,6 +31,13 @@ The script reads delta metadata directly from `spec.md`:
 - `[RENAMED capability FROM Previous title]` renames and replaces it.
 - `[INTERNAL]` never changes `openspec/specs/`.
 
+The SDD validator preflights these operations against the canonical requirement
+titles from `specify` onward. Archive reuses the same ordered parser and
+preflight as a final defense before staging writes, preserving stable
+`SDD-SPEC-DELTA-*` incompatibility codes. An `ADDED` warning for an existing
+nonempty capability requires semantic-overlap review because differently named
+requirements cannot be proven distinct by exact-title tooling alone.
+
 All delta targets are validated before any permanent specification changes. The
 operation stages and rolls back the full canonical update if a delta, report
 update, or final move raises a handled error in the active process. Report and