thoth-agents 0.3.9 → 0.3.11

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}]`);
 }
 
@@ -313,16 +300,36 @@ function parseStoryScenarios(spec) {
     const covers =
       /^\*\*Covers\*\*:\s*(.+)$/im.exec(story)?.[1].match(/\bFR-\d{3}\b/g) ??
       [];
-    const scenarios = [
-      ...story.matchAll(
-        /^\d+\.\s+\*\*Given\*\*\s+(.+?),\s+\*\*When\*\*\s+(.+?),\s+\*\*Then\*\*\s+(.+?)\.?\s*$/gim,
-      ),
-    ].map((scenario, scenarioIndex) => ({
-      title: `US${storyMatch[1]} - ${storyMatch[2].trim()} ${scenarioIndex + 1}`,
-      given: scenario[1].trim(),
-      when: scenario[2].trim(),
-      result: scenario[3].trim(),
-    }));
+    const acceptanceMarker = /^\*\*Acceptance scenarios\*\*:\s*$/im.exec(story);
+    const acceptance = acceptanceMarker
+      ? story.slice((acceptanceMarker.index ?? 0) + acceptanceMarker[0].length)
+      : '';
+    const scenarioStarts = [
+      ...acceptance.matchAll(/^\d+\.\s+\*\*Given\*\*/gim),
+    ];
+    const scenarios = scenarioStarts.map((scenarioStart, scenarioIndex) => {
+      const start = scenarioStart.index ?? 0;
+      const end = scenarioStarts[scenarioIndex + 1]?.index ?? acceptance.length;
+      const normalized = acceptance
+        .slice(start, end)
+        .replace(/\s+/g, ' ')
+        .trim();
+      const scenario =
+        /^\d+\.\s+\*\*Given\*\*\s+(.+?),\s+\*\*When\*\*\s+(.+?),\s+\*\*Then\*\*\s+(.+?)\.?\s*$/i.exec(
+          normalized,
+        );
+      if (!scenario) {
+        throw new Error(
+          `US${storyMatch[1]} acceptance scenario ${scenarioIndex + 1} must use Given, When, and Then`,
+        );
+      }
+      return {
+        title: `US${storyMatch[1]} - ${storyMatch[2].trim()} ${scenarioIndex + 1}`,
+        given: scenario[1].trim(),
+        when: scenario[2].trim(),
+        result: scenario[3].trim(),
+      };
+    });
 
     for (const requirementId of covers) {
       const current = scenariosByRequirement.get(requirementId) ?? [];
@@ -418,27 +425,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 +466,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 +505,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/SKILL.md

@@ -31,7 +31,19 @@ Accelerated the minimum recommendation but does not force it.
 
 - Root owns sequential coordination artifacts, gate execution, and archive.
 - Explorer owns Full-route repository discovery.
-- Designer, quick, deep, or root may implement according to scope.
+- SDD routes govern artifacts and gates, not implementation ownership. Root,
+  `designer`, `quick`, or `deep` may implement in Direct, Accelerated, or Full.
+- Root decides ownership from explicit safe user direction and demonstrated net
+  gain. Delegation benefits include specialization, context isolation,
+  independent bounded work, quality, latency, or total cost; root continuity
+  benefits include short or sequential work, shared mutable state, accumulated
+  context, rediscovery, and coordination overhead. Route, file count, or cheaper
+  model price alone never selects an owner.
+- Only after deciding to delegate implementation, select `designer` for UI/UX,
+  `quick` for known narrow low-risk work, or `deep` for coupled, edge-case-heavy,
+  migration, concurrency, shared-contract, or high-risk work.
+- Each mutable surface has one writer; independent non-overlapping surfaces may
+  split, while coupled surfaces use one `deep` writer and ordered handoffs.
 - Oracle owns `plan-review` when the user selects it and **every** `verify`. The
   implementation writer never approves its own work.
 

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

@@ -1,12 +1,39 @@
 # Implement contract
 
-**Owner**: root, designer, quick, or deep; exactly one writer per mutable surface
+**Owner**: adaptive root, `designer`, `quick`, or `deep` in every route; exactly
+one writer per mutable surface
 
-Root marks selected artifact-backed tasks `[~]`, then assigns exact paths,
-accepted FR/buildable-SC scope, non-goals, and verification commands. Use the
-mandatory `tdd` skill for behavior changes and work in vertical red/green
-slices. Child writers never edit task state; root marks `[x]` only after checking
-task-specific evidence.
+SDD routes govern artifacts and gates, not implementation ownership. Before
+implementation or dispatch, root records the decided owner, task-shape/net-gain
+rationale, exact paths, accepted FR/buildable-SC scope, non-goals, and
+verification commands. Route, file count, or cheaper model price alone is not an
+ownership rationale.
+
+Root may retain implementation when short or sequential work, shared mutable
+state, accumulated context, rediscovery, or coordination overhead outweighs
+delegation benefit. Delegate when specialization, context isolation, independent
+bounded work, quality, latency, or total cost creates demonstrated net gain. If
+root owns the surface, do not dispatch a writer. If a specialist owns it, send a
+bounded handoff with the exact surface, requirements, and checks.
+
+Root marks selected artifact-backed tasks `[~]`; Direct or no-artifact work has
+no task state. Use the mandatory `tdd` skill for behavior changes and work in
+vertical red/green slices. Child writers never edit task state; root marks `[x]`
+only after checking task-specific evidence.
+
+After deciding delegation creates net gain, select deterministically:
+
+- `designer` for user-facing UI/UX, interaction, accessibility, responsive, or
+  visual-quality work;
+- `quick` for a known narrow mechanical low-risk surface with exact targets;
+- `deep` for coupled multi-file, shared-contract, migration, concurrency,
+  edge-case-heavy, or high-risk work.
+
+Proven independent surfaces may use different writers only with non-overlapping
+ownership. Overlapping or compatibility-coupled work uses one `deep` writer and
+ordered handoffs. A writer escalates before expanding beyond its routing
+boundary. The implementation writer never performs final verification; root
+hands the unchanged candidate to a fresh Oracle.
 
 Implementation evidence may refine an artifact without restarting the workflow:
 

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