thoth-agents 0.3.10 → 0.3.12

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

@@ -540,6 +540,97 @@ function exactTaskPath(line) {
   return normalized.toLowerCase();
 }
 
+function taskDependencyEdges(content) {
+  return [...content.matchAll(/\bT\d{3}(?:\s*->\s*T\d{3})+\b/g)].flatMap(
+    ([chain]) => {
+      const ids = chain.match(/\bT\d{3}\b/g) ?? [];
+      return ids.slice(1).map((target, index) => ({
+        source: ids[index],
+        target,
+      }));
+    },
+  );
+}
+
+function parseParallelGroups(content) {
+  const lines = content.split(/\r?\n/);
+  const headingIndexes = lines
+    .map((line, index) => (/^###\s+Group\s+P\d+\s*$/.test(line) ? index : -1))
+    .filter((index) => index >= 0);
+  const groups = [];
+  let valid = headingIndexes.length > 0;
+
+  if (
+    lines
+      .slice(0, headingIndexes[0] ?? lines.length)
+      .some((line) => line.trim())
+  ) {
+    valid = false;
+  }
+
+  for (const [groupIndex, start] of headingIndexes.entries()) {
+    const end = headingIndexes[groupIndex + 1] ?? lines.length;
+    const groupId = /^###\s+Group\s+P(\d+)\s*$/.exec(lines[start])?.[1];
+    const body = lines.slice(start + 1, end).filter((line) => line.trim());
+    const lanes = [];
+    let prerequisites;
+    let barrier;
+    let rationale;
+    for (const line of body) {
+      const lane =
+        /^- Lane L(\d+): (T\d{3}(?: -> T\d{3})*)(?: \| Owner: (\S+))?\s*$/.exec(
+          line,
+        );
+      if (lane) {
+        lanes.push({
+          number: Number.parseInt(lane[1], 10),
+          taskIds: lane[2].split(' -> '),
+          owner: lane[3],
+        });
+        continue;
+      }
+      const prerequisiteLine =
+        /^- Prerequisites: (None|T\d{3}(?:, T\d{3})*)\s*$/.exec(line);
+      if (prerequisiteLine && prerequisites === undefined) {
+        prerequisites =
+          prerequisiteLine[1] === 'None' ? [] : prerequisiteLine[1].split(', ');
+        continue;
+      }
+      const barrierLine = /^- Barrier: (Final verification|T\d{3})\s*$/.exec(
+        line,
+      );
+      if (barrierLine && barrier === undefined) {
+        barrier = barrierLine[1];
+        continue;
+      }
+      const rationaleLine = /^- Rationale: (\S.*)$/.exec(line);
+      if (rationaleLine && rationale === undefined) {
+        rationale = rationaleLine[1];
+        continue;
+      }
+      valid = false;
+    }
+    if (
+      groupId === undefined ||
+      lanes.length < 2 ||
+      rationale === undefined ||
+      !isConcreteEvidence(rationale) ||
+      lanes.some((lane, index) => lane.number !== index + 1)
+    ) {
+      valid = false;
+    }
+    groups.push({
+      number: Number.parseInt(groupId ?? '0', 10),
+      lanes,
+      prerequisites,
+      barrier,
+      rationale,
+    });
+  }
+  if (groups.some((group, index) => group.number !== index + 1)) valid = false;
+  return { groups, valid };
+}
+
 function validateTasks(content, errors, spec) {
   const artifact = 'tasks.md';
   const taskLines = content
@@ -644,12 +735,6 @@ function validateTasks(content, errors, spec) {
   }));
   const tasksById = new Map(taskRecords.map((task) => [task.id, task]));
   const hasParallelTask = taskRecords.some((task) => task.parallel);
-  const parallelLines = (parallelSection ?? '')
-    .split(/\r?\n/)
-    .map((line) => [line, [...new Set(line.match(/\bT\d{3}\b/g) ?? [])]])
-    .filter(([, ids]) => ids.length >= 2);
-  const referencedTaskIds = new Set(parallelLines.flatMap(([, ids]) => ids));
-  const hasParallelExample = parallelLines.length > 0;
   const noParallelMatch = /^-\s+None:\s*(\S.*)$/im.exec(parallelSection ?? '');
   const explainsNoParallelWork =
     noParallelMatch !== null && isConcreteEvidence(noParallelMatch[1]);
@@ -657,42 +742,190 @@ function validateTasks(content, errors, spec) {
     left === right ||
     left.startsWith(`${right}/`) ||
     right.startsWith(`${left}/`);
-  const unknownReferences = [...referencedTaskIds].filter(
-    (id) => !tasksById.has(id),
+  const noneOnly =
+    explainsNoParallelWork &&
+    parallelSection?.trim() === noParallelMatch?.[0].trim();
+  const { groups, valid: validGroupGrammar } = parseParallelGroups(
+    parallelSection ?? '',
   );
-  const omittedParallelTasks = taskRecords
-    .filter((task) => task.parallel && !referencedTaskIds.has(task.id))
-    .map((task) => task.id);
-  const examplesWithoutParallelTask = parallelLines.some(
-    ([, ids]) => !ids.some((id) => tasksById.get(id)?.parallel),
+  const declaredDependencies = taskDependencyEdges(
+    sectionContent(content, 'Dependencies') ?? '',
   );
-  const overlappingExamples = parallelLines.some(([, ids]) => {
-    const paths = ids.map((id) => tasksById.get(id)?.path);
-    if (paths.some((path) => path === undefined)) return true;
-    return paths.some((path, index) =>
-      paths.slice(index + 1).some((other) => pathsOverlap(path, other)),
-    );
-  });
+  const hasGroups = groups.length > 0;
   if (
     parallelSection === undefined ||
-    (explainsNoParallelWork && hasParallelExample) ||
-    (hasParallelTask &&
-      (!hasParallelExample ||
-        explainsNoParallelWork ||
-        unknownReferences.length > 0 ||
-        omittedParallelTasks.length > 0 ||
-        examplesWithoutParallelTask ||
-        overlappingExamples)) ||
-    (!hasParallelTask && !explainsNoParallelWork)
+    (hasParallelTask && (!hasGroups || explainsNoParallelWork)) ||
+    (!hasParallelTask && !noneOnly) ||
+    (explainsNoParallelWork && !noneOnly)
   ) {
     errors.push(
       issue(
         'SDD-TASK-PARALLEL',
         artifact,
-        'Document existing [P] tasks with non-overlapping paths, or explain why no safe parallel work exists.',
+        'Declare strict parallel groups for [P] tasks, or provide one exclusive evidence-backed None reason.',
+      ),
+    );
+  }
+  if (hasGroups && !validGroupGrammar) {
+    errors.push(
+      issue(
+        'SDD-TASK-LANE-GRAMMAR',
+        artifact,
+        'Groups and lanes must use unique sequential IDs, at least two lanes, and every required field.',
       ),
     );
   }
+
+  if (hasGroups && validGroupGrammar) {
+    const memberships = groups.flatMap((group) =>
+      group.lanes.flatMap((lane) =>
+        lane.taskIds.map((taskId) => ({ group, lane, taskId })),
+      ),
+    );
+    const membershipCounts = new Map();
+    for (const { taskId } of memberships) {
+      membershipCounts.set(taskId, (membershipCounts.get(taskId) ?? 0) + 1);
+    }
+    const invalidMembership =
+      memberships.some(({ taskId }) => !tasksById.get(taskId)?.parallel) ||
+      taskRecords.some(
+        (task) => task.parallel && membershipCounts.get(task.id) !== 1,
+      );
+    if (invalidMembership) {
+      errors.push(
+        issue(
+          'SDD-TASK-LANE-MEMBERSHIP',
+          artifact,
+          'Every [P] task must belong to exactly one lane, and lane members must be known [P] tasks.',
+        ),
+      );
+    }
+
+    if (
+      groups.some((group) =>
+        group.lanes.some(
+          (lane) => !['designer', 'quick', 'deep'].includes(lane.owner),
+        ),
+      )
+    ) {
+      errors.push(
+        issue(
+          'SDD-TASK-LANE-OWNER',
+          artifact,
+          'Every lane owner must be designer, quick, or deep.',
+        ),
+      );
+    }
+
+    for (const group of groups) {
+      const rationale = group.rationale ?? '';
+      const hasPathIndependenceEvidence =
+        /\b(?:path|file|surface)s?\b/i.test(rationale) &&
+        /\b(?:disjoint|non[- ]?overlap(?:ping)?)\b/i.test(rationale);
+      const hasDependencyIndependenceEvidence =
+        /\b(?:dependenc(?:y|ies)|consum(?:e|es|ing)|peer output|data flow)\b/i.test(
+          rationale,
+        );
+      if (!hasPathIndependenceEvidence || !hasDependencyIndependenceEvidence) {
+        errors.push(
+          issue(
+            'SDD-TASK-LANE-RATIONALE',
+            artifact,
+            'Parallel rationale must state concrete path-disjointness and cross-lane dependency evidence for Oracle review.',
+          ),
+        );
+      }
+
+      const memberIds = new Set(group.lanes.flatMap((lane) => lane.taskIds));
+      const prerequisites = group.prerequisites ?? [];
+      if (
+        group.prerequisites === undefined ||
+        new Set(prerequisites).size !== prerequisites.length ||
+        prerequisites.some(
+          (taskId) => !tasksById.has(taskId) || memberIds.has(taskId),
+        )
+      ) {
+        errors.push(
+          issue(
+            'SDD-TASK-LANE-PREREQUISITE',
+            artifact,
+            'Prerequisites must be unique known tasks outside the group.',
+          ),
+        );
+      }
+
+      const memberNumbers = [...memberIds].map((id) =>
+        Number.parseInt(id.slice(1), 10),
+      );
+      const barrierNumber = /^T\d{3}$/.test(group.barrier ?? '')
+        ? Number.parseInt(group.barrier.slice(1), 10)
+        : undefined;
+      if (
+        group.barrier !== 'Final verification' &&
+        (barrierNumber === undefined ||
+          !tasksById.has(group.barrier) ||
+          memberIds.has(group.barrier) ||
+          prerequisites.includes(group.barrier) ||
+          memberNumbers.some((number) => barrierNumber <= number))
+      ) {
+        errors.push(
+          issue(
+            'SDD-TASK-LANE-BARRIER',
+            artifact,
+            'A task barrier must be a known downstream non-member task, or use exact Final verification.',
+          ),
+        );
+      }
+
+      const laneByTask = new Map(
+        group.lanes.flatMap((lane) =>
+          lane.taskIds.map((taskId) => [taskId, lane.number]),
+        ),
+      );
+      if (
+        declaredDependencies.some(
+          ({ source, target }) =>
+            laneByTask.has(source) &&
+            laneByTask.has(target) &&
+            laneByTask.get(source) !== laneByTask.get(target),
+        )
+      ) {
+        errors.push(
+          issue(
+            'SDD-TASK-LANE-DEPENDENCY',
+            artifact,
+            'Declared dependencies cannot connect different lanes in one group.',
+          ),
+        );
+      }
+
+      const lanePaths = group.lanes.map((lane) =>
+        lane.taskIds.map((taskId) => tasksById.get(taskId)?.path),
+      );
+      const overlaps = lanePaths.some((paths, index) =>
+        lanePaths
+          .slice(index + 1)
+          .some((otherPaths) =>
+            paths.some(
+              (path) =>
+                path !== undefined &&
+                otherPaths.some(
+                  (other) => other !== undefined && pathsOverlap(path, other),
+                ),
+            ),
+          ),
+      );
+      if (overlaps) {
+        errors.push(
+          issue(
+            'SDD-TASK-LANE-OVERLAP',
+            artifact,
+            'Mutable task paths cannot overlap across lanes in one group.',
+          ),
+        );
+      }
+    }
+  }
 }
 
 function validateChecklist(content, errors, spec, requireComplete) {

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

@@ -32,8 +32,24 @@ for them.
 
 ## Parallel execution
 
-[Replace the anchor with exactly one form: concrete task pairings covering every
-`[P]` task, or `- None: <evidence-backed reason>`. Never keep both forms.]
+Use this exact grammar when safe parallel work exists:
+
+### Group P1
+
+- Lane L1: T001 -> T002 | Owner: deep
+- Lane L2: T003 -> T004 | Owner: quick
+- Prerequisites: None
+- Barrier: Final verification
+- Rationale: Both lane path sets are disjoint and neither lane consumes peer output.
+
+Groups and lanes are sequential and unique. Every `[P]` task belongs to exactly one lane; non-`[P]` tasks do not. Lane surfaces are the union of exact task
+paths, and lanes in a group have disjoint surfaces and no cross-lane dependency.
+The `Rationale` must explicitly state path-disjointness and cross-lane dependency
+evidence so structural validation can gate the evidence shape and Oracle can
+judge whether the claim is true.
+Prerequisites name known tasks outside the group; the barrier is a downstream
+task or `Final verification` after all lane members. If no group exists, use
+only `- None: <evidence-backed reason>` and no task may use `[P]`.
 
 <!-- PARALLEL-EXECUTION-EVIDENCE -->
 

package/skills/README.md

@@ -7,7 +7,8 @@ the same packaged skill trees globally under `~/.config/opencode/skills/`.
 
 Owned workflow skills are `thoth-init`, `thoth-sdd`, `thoth-constitution`,
 `thoth-archive`, and `plan-reviewer`. The last one implements the optional,
-user-selected, read-only Oracle review before implementation. Mandatory external
+explicitly or bounded-default selected, read-only Oracle review before
+implementation. Mandatory external
 skills (`simplify`, `tdd`,
 `progressive-context-router`, and `architectural-grilling`) are not copied here:
 the thoth-agents installer invokes `npx skills add` against their canonical

package/skills/plan-reviewer/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: plan-reviewer
-description: Review a ready Accelerated or Full SDD artifact set for execution blockers after the user chooses the optional Oracle plan review. Use only for the pre-implementation plan-review phase; return exact [OKAY] or [REJECT] semantics while keeping final verification separate.
+description: Review a ready Accelerated or Full SDD artifact set for execution blockers after Oracle review is explicitly or recommended-default selected. Use only for the pre-implementation plan-review phase; return exact [OKAY] or [REJECT] semantics while keeping final verification separate.
+license: MIT
+compatibility: Designed for thoth-agents Accelerated and Full SDD workflows.
 metadata:
   author: thoth-agents
-  version: '1.0'
+  version: "1.0"
 ---
 
 # Plan Reviewer
@@ -17,12 +19,16 @@ Use this skill only after all of these conditions hold:
 
 - The selected route is Accelerated or Full.
 - The route's `ready` validator gate has passed.
-- The user chose `Review plan with Oracle (Recommended)` instead of
-  `Proceed without review`.
+- `Review plan with Oracle (Recommended)` was explicitly selected or selected
+  by the bounded no-answer fallback.
 
-Do not activate automatically, and do not use it for Direct work. The user may
-proceed without this review. Skipping it means there is no pre-implementation
-Oracle review; mandatory final Oracle verify still applies.
+At the ready gate, any explicit `Proceed without review` answer wins. When the
+native question returns answerless, Root
+makes at most three total attempts; after the third answerless result, Root
+treats `Review plan with Oracle (Recommended)` as selected. This bounded
+fallback is the only automatic activation. Do not use this skill for Direct
+work. Explicitly proceeding without review means there is no pre-implementation
+Oracle review; mandatory final verification still applies.
 
 ## Ownership and inputs
 
@@ -61,6 +67,29 @@ Judge the artifact set on five dimensions:
 Respect TDD ordering and the repository constitution when they apply. Report
 non-blocking cautions separately so they do not become artificial gates.
 
+## Native parallel executability
+
+Structural ready validation proves that declared parallel metadata is
+well-formed; it does not prove semantic independence. When `tasks.md` declares
+parallel groups, Oracle must independently assess whether the plan can execute
+them safely:
+
+- Confirm each lane path union is genuinely disjoint from the other lanes and
+  its selected owner fits the bounded work.
+- Confirm cross-lane data flow does not hide a dependency and that the declared
+  prerequisites and barrier reflect the real execution order.
+- Confirm the handoff is sufficient for native capacity-bounded waves:
+  dispatch-before-wait for every admitted lane, refill before another wait, and
+  terminal reconciliation before releasing the barrier.
+- Require a truthful sequential fallback when native concurrency or capacity is
+  unavailable or unproven.
+
+For an evidence-backed `None` declaration, assess whether the claimed coupling
+really prevents a safe group. Treat a structural-but-semantically-unsafe group
+as a blocker only when the smallest repair is required before implementation;
+keep capacity uncertainty as a non-blocking caution when the declared fallback
+still makes the plan executable.
+
 ## Decision contract
 
 Default to `[OKAY]`. Return `[REJECT]` only when execution is genuinely blocked.
@@ -68,8 +97,10 @@ A rejection contains at most 3 actionable blockers. For each blocker, state why
 it blocks execution and the smallest concrete repair. Preserve the exact
 `[OKAY]` and `[REJECT]` tokens across every harness.
 
-After `[REJECT]`, Root repairs the canonical artifacts and offers the user the
-review-or-proceed choice again. Do not silently approve a changed plan.
+After `[REJECT]`, Root repairs actionable same-intent planning artifacts,
+revalidates affected gates, and starts a fresh Oracle approval round until
+`[OKAY]`. A material human-owned blocker stops the loop for user input. Do not
+silently approve a changed plan or reuse an Oracle to issue a new approval.
 
 ## Freshness and persistence
 
@@ -84,12 +115,20 @@ digests. Oracle returns this payload; Root is the only writer that persists it.
 
 ## Handoff
 
-After `[OKAY]`, Root summarizes the approved plan and must ask whether to implement or stop.
-Approval is not implementation authorization. Choosing
-`Proceed without review` at the earlier choice does authorize implementation.
-
-Plan review never replaces mandatory final Oracle verify. Every route still
-requires independent post-implementation verification by a non-writer.
+After `[OKAY]`, Root summarizes the approved scope, approach, ownership,
+verification, and material risks before asking the native question:
+`Implement (Recommended)` or `Stop`. Any explicit `Stop` answer wins. If the
+implementation question returns answerless, Root makes at most three total
+attempts; after the third answerless result, Root treats implementation as
+selected. `[OKAY]` alone does not authorize implementation before that explicit
+choice or bounded fallback resolves. Choosing `Proceed without review` at the
+earlier choice does authorize implementation.
+
+Plan review never replaces or substitutes for mandatory final verification.
+Every route still requires post-implementation verification, but ownership is
+proportional: trivial deterministic Direct work may be Root-verified when Root
+is not self-approving its own implementation; materially risky Direct work and
+every Accelerated or Full final verify require a fresh read-only Oracle.
 
 ## Output
 

package/skills/thoth-archive/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: thoth-archive
 description: Close a passing artifact-backed thoth-agents change by transactionally synchronizing explicitly declared durable requirement deltas and moving the complete audit trail to a dated archive.
+license: MIT
+compatibility: Requires Node.js >=22.13 and write access to the project OpenSpec tree.
+metadata:
+  author: thoth-agents
+  version: "1.0"
 ---
 
 # Thoth Archive

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

@@ -300,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) ?? [];

package/skills/thoth-constitution/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: thoth-constitution
 description: Create or explicitly amend the project constitution, choose its governance SemVer bump, propagate its impact, and validate lifecycle metadata. Use only for constitution lifecycle work; routine SDD planning reads the constitution without activating this skill.
+license: MIT
+compatibility: Requires Node.js >=22.13 for bundled validation scripts.
+metadata:
+  author: thoth-agents
+  version: "1.0"
 ---
 
 # Thoth Constitution

package/skills/thoth-constitution/templates/constitution.md

@@ -24,7 +24,11 @@ infrastructure without a current requirement is prohibited.
 
 Delivery MUST use the smallest coherent design that satisfies accepted
 requirements. Non-goals MUST be named, and scope cannot expand silently.
-SDD route selection MUST remain user-owned after an evidence-based recommendation.
+Before the SDD route question, Root MUST summarize relevant context, scope,
+clarity, risk, and its evidence-based recommendation. Any explicit answer wins.
+When the native question returns answerless, Root MUST make at most three total
+attempts; after the third answerless result, the recommended route counts as
+selected.
 
 ### III. Testable contracts
 
@@ -33,7 +37,20 @@ changes MUST use test-first execution at an agreed public seam when practical.
 
 ### IV. Independent assurance
 
-The implementation writer cannot approve its own work. Pre-implementation plan review is optional and user-selected. When selected, it uses an independent read-only reviewer. Every final verify MUST use an independent read-only reviewer.
+Every route MUST include verification proportional to the changed behavior and
+risk. The implementation writer cannot approve its own work. Trivial
+deterministic Direct work MAY be verified by Root when the decision is bounded
+and independent of the implementation writer. Materially risky Direct work and
+every Accelerated or Full final verify MUST use a fresh independent read-only
+reviewer. Pre-implementation plan review is optional and is selected explicitly
+or by the bounded recommended fallback; when offered, any explicit answer wins.
+After the third answerless result,
+`Review plan with Oracle (Recommended)` counts as selected. Actionable review
+rejections MUST be repaired and revalidated before a fresh reviewer round until
+approval or a material human-owned blocker. After approval, Root MUST give an
+approved plan summary before asking `Implement (Recommended)` or `Stop`; any
+explicit answer wins, while the third answerless result selects implementation.
+Plan review never substitutes for final verification.
 
 ### V. Traceable delivery
 

package/skills/thoth-init/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: thoth-init
 description: Initialize or synchronize the minimum project OpenSpec governance structure required by thoth-agents SDD flows.
+license: MIT
+compatibility: Requires Node.js >=22.13 and write access to the target project.
+metadata:
+  author: thoth-agents
+  version: "1.0"
 ---
 
 # Thoth Init