thoth-agents 0.3.10 → 0.3.12

package/plugin/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/plugin/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/plugin/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/plugin/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/plugin/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/plugin/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

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

@@ -1,6 +1,11 @@
 ---
 name: thoth-sdd
-description: Run thoth-agents Direct, Accelerated, or Full specification-driven development with Spec Kit-grade artifacts, OpenSpec-style durable deltas, fast-forward planning, and oracle-only analysis and verification.
+description: Run thoth-agents Direct, Accelerated, or Full specification-driven development with Spec Kit-grade artifacts, OpenSpec-style durable deltas, fast-forward planning, and proportional independent verification.
+license: MIT
+compatibility: Requires Node.js >=22.13 for bundled validation scripts.
+metadata:
+  author: thoth-agents
+  version: "1.0"
 ---
 
 # Thoth SDD
@@ -18,21 +23,53 @@ intent is clear and risk is low.
 
 Accelerated is a **fast-forward** route: root writes `spec.md`, `plan.md`, and
 `tasks.md` in one uninterrupted pass and creates optional artifacts only for a
-concrete risk. After `ready`, both artifact-backed routes pause once to offer
+concrete risk. After `ready`, both artifact-backed routes offer
 `Review plan with Oracle (Recommended)` or `Proceed without review`. Full uses
 separate planning gates because uncertainty or failure cost justifies them.
 
 An explicitly named route counts as the user's selection. Otherwise assess and
-recommend Direct, Accelerated, or Full, then wait for the user to choose; the
-recommendation is not the decision. A generic request to “use SDD” makes
-Accelerated the minimum recommendation but does not force it.
+recommend Direct, Accelerated, or Full, first summarize the relevant request
+context, scope, clarity, risk, and why the recommendation fits, then ask. When a
+native route question returns answerless, make at most three total attempts;
+after the third answerless result, treat the recommended route as selected. Any
+explicit answer wins. A generic request to “use SDD” makes Accelerated the
+minimum recommendation but does not force it.
+
+At the post-`ready` review choice, an explicit answer wins, including
+`Proceed without review`. When the native question returns answerless, make at
+most three total attempts; after the third answerless result, treat
+`Review plan with Oracle (Recommended)` as selected. Once review is selected,
+repair actionable same-intent planning blockers, revalidate affected gates, and
+use a fresh Oracle for every new approval round until `[OKAY]`; stop instead on
+a material human-owned blocker.
+
+These bounded fallbacks apply only to the route, plan-review, and implementation
+questions. Never apply them to secrets, destructive or security-sensitive
+actions, or material human-owned product or architecture decisions.
 
 ## Ownership
 
 - 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.
-- Oracle owns `plan-review` when the user selects it and **every** `verify`. The
+- 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 review is explicitly selected or chosen by the
+  bounded recommended fallback. Every route requires
+  mandatory verification, but final-verification ownership is proportional:
+  trivial deterministic Direct work may be verified by Root 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. The
   implementation writer never approves its own work.
 
 ## Progressive loading
@@ -78,10 +115,10 @@ node "<skill-dir>/scripts/validate.mjs" --change openspec/changes/<feature> --ro
 - **Checklist**: run only when activated; the later `ready` gate includes it if
   present.
 
-`ready` validates the artifacts needed before the user chooses
-`Review plan with Oracle (Recommended)` or `Proceed without review`. Review
-approval remains separate from implementation confirmation and never satisfies
-final verification.
+`ready` validates the artifacts needed before the explicit or bounded-default
+`Review plan with Oracle (Recommended)` / `Proceed without review` choice.
+Review approval remains separate from implementation confirmation and never
+satisfies final verification.
 `closeout` additionally requires completed tasks, independent oracle PASS,
 complete FR/buildable-SC evidence, an observed PASS or explicit residual RISK
 for every outcome SC, and an archive report ready for the transactional archive

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

@@ -1,12 +1,42 @@
 # 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. Every route requires mandatory verification, and the implementation
+writer never approves its own work. For trivial deterministic Direct work, Root
+may run the proportionate focused checks when Root is not self-approving its own
+implementation. For materially risky Direct work and every Accelerated or Full
+final verify, root hands the unchanged candidate to a fresh read-only Oracle.
 
 Implementation evidence may refine an artifact without restarting the workflow:
 
@@ -17,3 +47,11 @@ Implementation evidence may refine an artifact without restarting the workflow:
   silently expanding this one.
 
 Report files changed, checks executed, deviations, and remaining work.
+
+## Native dispatch groups and waves
+
+For each ready group, confirm prerequisites, ordered lane tasks, exact path
+union, owner, requirements, and checks. Select the capacity-bounded set of
+undispatched ready lanes and create one fresh native specialist assignment per admitted lane. Issue every dispatch in that native wave before any wait, status,
+result collection, or root implementation action. Retain handles; when terminal evidence frees capacity, dispatch the next undispatched ready lane before waiting again. Validate terminal evidence per lane, while root alone updates task state. Cross the declared barrier only after every lane is terminal and reconciled. Preserve truthful capability/capacity fallback: when native
+concurrency is unavailable or width is one, use a truthful sequential fallback.

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

@@ -22,6 +22,27 @@ not justify artificial implementation tasks.
 
 Order test-first work before its implementation, group tasks by independently
 deliverable story, identify the MVP, and state dependencies. `[P]` is permitted
-only when mutable paths provably do not overlap and the Parallel execution
-section names a concrete pairing. If there is no safe parallel work, use
+only for tasks assigned to a declared lane whose mutable path union does not
+overlap another lane in the same group. If there is no safe parallel work, use
 `- None: <evidence-backed reason>` instead. Avoid ceremonial tasks.
+
+## Parallel execution
+
+Declare safe work with this exact grammar:
+
+### 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]`.

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

@@ -1,10 +1,12 @@
 # Verify contract
 
-**Owner**: oracle, always read-only and independent
+**Owner**: route- and risk-aware; Root for trivial deterministic Direct, otherwise a fresh read-only Oracle
 
-Oracle verifies Direct, Accelerated, and Full work. The root or writer that
-implemented the change cannot substitute for oracle. Inspect changed code and
-run or validate the smallest sufficient checks.
+Every route requires mandatory verification. Trivial deterministic Direct work
+may be verified by Root with focused deterministic checks. Materially risky
+Direct work and Accelerated or Full final verification use a fresh read-only
+Oracle. The implementation writer never approves its own work. Inspect changed
+code and run or validate the smallest sufficient checks.
 
 Judge three dimensions separately: **completeness** of accepted scope and
 coverage, **correctness** against behavioral contracts and executed evidence,
@@ -16,7 +18,7 @@ task.
 
 Return `pass` or `fail`, compliance matrix, commands/results, stable findings,
 critical issues, warnings, and remediation anchors. For Direct, return the
-verdict in-session. For Accelerated and Full, root persists oracle's exact result
+verdict in-session regardless of owner. For Accelerated and Full, root persists Oracle's exact result
 using `<skill-dir>/templates/verify-report.md`, where `<skill-dir>` is the
 directory containing the installed `thoth-sdd/SKILL.md`. Fail routes to converge
 (straight back to implement for Direct); PASS permits closeout and archive for