thoth-agents 0.4.2 → 0.5.1

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

@@ -0,0 +1,94 @@
+# Change: <id>
+
+**Classification**: substantial
+**Scope**: <local|coordinated|cross-cutting>
+**Uncertainty**: <low|medium|high>
+**Risk**: <low|medium|high>
+
+## Exploration
+
+TBD: Confirm current behavior, constraints, and relevant repository evidence.
+
+## Intent
+
+TBD: State the accepted outcome.
+
+## Non-goals
+
+TBD: State boundaries and excluded work.
+
+## Acceptance
+
+- AC-1: TBD
+
+## Clarifications
+
+- PENDING: Record resolved material choices or that none are needed.
+
+## Decisions
+
+- PENDING: Record settled assumptions and human-owned decisions.
+
+## Durable deltas
+
+- None.
+
+## Plan
+
+TBD: Record the technical approach and focused verification seams.
+
+## Tasks
+
+Use one checkbox row per independently acceptable work unit. Keep each checkbox
+on one line in the validator-compatible form `- [ ] AC-n: ...`; indent the
+remaining fields below it. Repeat an AC number when separate units contribute
+to that acceptance outcome. The row text names one reviewable result; do not
+combine separately acceptable outcomes into a phase-sized task. Fill the
+indented fields with concrete information. For a read-only unit, write `none`
+for owned writes.
+
+- [ ] AC-1: TBD
+  - Outcome: one result that root can accept independently
+  - Known entrypoints and skill paths: exact paths needed for this outcome
+  - Inputs: concrete accepted evidence or upstream outputs
+  - Dependencies: named upstream units and their accepted outputs, or none
+  - Output: concrete finding, decision, or artifact
+  - Owner: root or selected role
+  - Writes: exact owned paths, or none for read-only work
+  - Interface boundaries: relevant contracts and callers, or none
+  - Focused check and PASS evidence: check to run and observable passing result
+  - Return milestone: when root can review and accept this result
+  - Stop / reassessment: smallest missing input, conflict, or new scope to return
+
+## Authorization
+
+Accepted values: Plan review: `OKAY | SKIPPED`; Plan review selection:
+`EXPLICIT_REVIEW | EXPLICIT_SKIP | DEFAULT_REVIEW_AFTER_3`; Implementation:
+`AUTHORIZED`. Put notes on separate lines below the fields, never on field lines.
+
+**Plan review**: PENDING
+**Plan review selection**: PENDING
+**Implementation**: PENDING
+
+## Verification
+
+Accepted values: Reviewer: `oracle`; Independent from implementer: `Yes`;
+Verdict: `PASS`; Reviewed record SHA-256: 64 lowercase hex characters hashing
+exact UTF-8 bytes before the case-sensitive `## Authorization` heading. Use
+exactly one SHA field line; put notes on separate lines below the fields.
+
+**Reviewer**: PENDING
+**Independent from implementer**: PENDING
+**Verdict**: PENDING
+**Reviewed record SHA-256**: PENDING
+
+- AC-1: PENDING | check | evidence
+- Source: relative/path | sha256:<actual-source-digest>
+- Source: .thoth/specs/<capability>/spec.md | sha256:<actual-source-digest>
+- Source: .thoth/specs/<new-capability>/spec.md | absent
+
+## Closeout
+
+Accepted value: Archive: `READY`. Put notes on separate lines below the field.
+
+**Archive**: PENDING

package/skills/README.md

@@ -1,17 +1,15 @@
 # Bundled thoth-owned skills
 
-This directory is the canonical, versioned source for skills owned by
-thoth-agents. `pnpm run integration:sync` copies those skills into the Codex and
-Claude Code plugins; `npx thoth-agents install --agent=opencode` materializes
-the same packaged skill trees globally under `~/.config/opencode/skills/`.
+This directory is the canonical, versioned source for owned skills. The installer
+and `pnpm run integration:sync` expose the same bundle in supported harnesses.
 
 Owned workflow skills are `thoth-init`, `thoth-sdd`, `thoth-constitution`,
-`thoth-archive`, and `plan-reviewer`. The last one implements the optional,
-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
-repositories so they retain a single source of truth. `thoth-init` only
-initializes or synchronizes minimum project `openspec/` governance and never
-installs skills.
+`thoth-archive`, and `plan-reviewer`. `thoth-sdd` owns proportional
+understanding/classification, the single ID-named substantial-change record, and
+maintained validation. The optional plan reviewer is read-only; archive applies
+declared `.thoth/specs/` deltas transactionally.
+
+External skills (`simplify`, `tdd`, `progressive-context-router`, and
+`architectural-grilling`) are not copied here. Installation handles them; never
+fetch or install dependencies during an active SDD phase. `thoth-init` only
+initializes canonical `.thoth/` governance and preserves existing records.

package/skills/plan-reviewer/SKILL.md

@@ -1,150 +1,48 @@
 ---
 name: plan-reviewer
-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.
+description: Independent blocker-only Oracle review of a ready substantial SDD plan before separate implementation authorization.
 license: MIT
-compatibility: Designed for thoth-agents Accelerated and Full SDD workflows.
+compatibility: Requires the installed sibling thoth-sdd skill.
 metadata:
   author: thoth-agents
-  version: "1.0"
+  version: "2.0"
 ---
 
 # Plan Reviewer
 
-Review whether an accepted SDD plan can be implemented safely as written. Focus
-on true execution blockers, not stylistic preferences or redesign ideas.
-
-## Activation
-
-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.
-- `Review plan with Oracle (Recommended)` was explicitly selected or selected
-  by the bounded no-answer fallback.
-
-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
-
-Resolve `<skill-dir>` as the directory containing this `SKILL.md`. Every bundled
-asset path in this contract is anchored to that installed skill root rather than
-the project or current working directory.
-
-Root coordinates the phase and dispatches Oracle. Oracle remains read-only: it
-must not edit source, SDD artifacts, or coordination state. Root persists the
-returned review at `openspec/changes/<change>/plan-review.md` using
-`<skill-dir>/templates/plan-review.md`.
-
-Review these canonical inputs:
-
-- `spec.md`
-- `plan.md`
-- `tasks.md`
-- an active requirements checklist, when present
-- `openspec/memory/constitution.md`, when governance applies
-
-OpenSpec is the only SDD artifact store. Do not mirror `plan-review.md` or its
-payload into provider memory.
-
-## Review method
-
-Judge the artifact set on five dimensions:
-
-1. Completeness: every in-scope requirement and success criterion maps to work.
-2. Correctness: named files, symbols, commands, and public contracts are real or
-   explicitly created by the plan.
-3. Coherence: artifacts agree on scope, sequencing, dependencies, and ownership.
-4. Buildability: a competent implementer can execute without guessing about
-   critical paths or hidden prerequisites.
-5. Outcome coverage: verification tasks can demonstrate the requested result.
-
-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.
-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 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
-
-Root computes SHA-256 digests for every reviewed artifact and records them in
-the persisted review. Treat a stored approval as fresh only while every recorded
-digest matches. A stale review has no gate value; rerun it only if the user still
-chooses review.
-
-The persisted artifact records the status, Oracle role, timestamp, route,
-comments, non-blocking notes, blockers, any explicit override, and source
-digests. Oracle returns this payload; Root is the only writer that persists it.
-
-## Handoff
-
-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
-
-For an executable plan:
-
-```text
-[OKAY]
-- Brief evidence that the plan is complete, coherent, and executable.
-- Optional non-blocking cautions.
-```
-
-For a blocked plan:
-
-```text
-[REJECT]
-1. <blocker, impact, and smallest repair>
-2. <optional blocker>
-3. <optional blocker>
-```
+After the substantial plan passes `ready`, root first shows the user a concise
+plan summary, then always offers Review plan with Oracle (Recommended) or
+Proceed without review, even when implementation is already authorized. Silence is never an explicit skip; a fresh review runs only
+when selected. Root, not Oracle, owns choices, budgets, recovery, and
+implementation authorization. Every orchestrator choice with a meaningful
+recommendation follows the per-question rule: repeat the same question after its
+first and second confirmed answerless native returns without dependent work,
+then select the recommendation after the third. Explicit answers and `Stop` win.
+Pending, unavailable, failed, interrupted, or host-prohibited attempts do not
+count. Report higher-priority host limits accurately; do not claim unmade returns
+or an explicit user choice. Never invent facts or secrets; when a human-owned
+decision is still unresolved, recommend safe deferral.
+
+A fresh read-only Oracle reviews `.thoth/changes/<id>/<id>.md`,
+`.thoth/constitution.md`, affected canonical `.thoth/specs/`, and focused source
+evidence. Check grounded exploration, observable acceptance, settled
+clarification, technical feasibility, dependencies, verification seams,
+autonomy bounds, and native capacity. Concurrent tasks need semantic
+independence and non-overlapping mutable ownership; unknown liveness blocks only
+conflicting work. Do not require multiple reports, universal requirement IDs,
+workflow manifests, evidence directories, or a scheduler. Structural `ready` is
+necessary but not sufficient for semantic readiness.
+
+Return `[OKAY]` with concise evidence or `[REJECT]` with at most three actual
+execution blockers and smallest repairs; keep cautions separate. Root repairs
+same-intent blockers in the same record, revalidates affected gates, and uses a
+fresh Oracle for each round. A human-owned material blocker stops the round.
+Root records both review disposition and selection provenance without inventing
+approval. Accepted provenance is `EXPLICIT_REVIEW`, `EXPLICIT_SKIP`, or
+`DEFAULT_REVIEW_AFTER_3`; `SKIPPED` requires explicit skip, while `OKAY` requires
+explicit review or the third-return review default. After `[OKAY]`, root preserves
+the separate Implement (Recommended) / Stop choice and separately offers it,
+honoring prior explicit implementation authorization; an explicit later Stop
+supersedes it. That choice has its own per-question budget. Review never
+substitutes for fresh independent final Oracle verification, and Oracle never
+writes change artifacts.

package/skills/thoth-archive/SKILL.md

@@ -1,56 +1,59 @@
 ---
 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.
+description: Transactionally apply declared .thoth/specs deltas and archive independently verified substantial SDD changes.
 license: MIT
-compatibility: Requires Node.js >=22.19 and write access to the project OpenSpec tree.
+compatibility: Requires Node.js >=22.19 and installed sibling thoth-sdd skill.
 metadata:
   author: thoth-agents
-  version: "1.0"
+  version: "2.0"
 ---
 
 # Thoth Archive
 
-Archive is the required terminal transition for Accelerated and Full routes.
-Resolve `<skill-dir>` as the directory containing this `SKILL.md`, and resolve
-`<skills-root>` as its parent directory. Bundled paths below are anchored to
-those installed roots rather than the project or current working directory.
-
-1. Confirm every task is `[x]`, `verify-report.md` records independent oracle
-   `PASS`, its compliance matrix covers every FR and buildable SC, every outcome
-   SC has observed PASS evidence or an explicit residual RISK, and no unresolved
-   CRITICAL issue remains.
-2. Prepare `archive-report.md` from
-   `<skills-root>/thoth-sdd/templates/archive-report.md` with status `READY`,
-   verification lineage, completed scope, deviations, residual warnings, and
-   the pending canonical-sync line.
-3. Run `node "<skills-root>/thoth-sdd/scripts/validate.mjs"` through `closeout`.
-4. Run `node "<skill-dir>/scripts/archive.mjs" --change <path> --date YYYY-MM-DD --json`.
-5. Return the dated archive path, updated capability specifications, and audit
-   summary.
-
-The script reads delta metadata directly from `spec.md`:
-
-- `[ADDED capability]` creates a named canonical requirement.
-- `[MODIFIED capability]` replaces the named requirement and its scenarios.
-- `[REMOVED capability]` removes the named requirement.
-- `[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
-canonical recovery are attempted independently. It never merges undeclared
-feature prose. No CLI, network access, or installation action is used during SDD
-closeout.
-
-This operation is not crash-atomic. Forced process or operating-system
-termination between filesystem renames can leave `.spec.md.thoth-stage-*` or
-`spec.md.thoth-backup-*` files. Inspect them and the canonical specification
-before retrying archive.
+Root archives only after the implementation writer has terminated and a fresh
+independent Oracle PASS has covered the actual change, diff, checks, and risks.
+Structural closeout validation is not approval. The single record must have all
+tasks complete, explicit plan-review disposition and implementation authorization,
+every acceptance outcome's concrete PASS check/evidence, reviewed-record and
+source digests, reviewed canonical baselines for every affected capability, and
+`**Archive**: READY`. Each affected canonical spec is covered in that same record
+by its SHA-256 `Source` entry or an explicit `absent` entry. Missing or stale
+coverage blocks before canonical or archive changes. No verification or archive
+report is required or allowed.
+
+Plan-review selection provenance must be `EXPLICIT_REVIEW`, `EXPLICIT_SKIP`, or
+`DEFAULT_REVIEW_AFTER_3`. A `SKIPPED` disposition requires `EXPLICIT_SKIP`; an
+`OKAY` disposition requires explicit review or the third-answerless review
+default. An unanswered offer never authorizes skip. The orchestrator owns the
+choice and uses the shared per-question recommendation rule; archive validation
+does not claim that it can authenticate the native interaction.
+
+Run the installed sibling validator at `--through closeout`, then:
+
+```text
+node "<skill-dir>/scripts/archive.mjs" --change .thoth/changes/<id> --date YYYY-MM-DD --json
+```
+
+The shipped `--project <repository-root>` option is also accepted and checked
+against the change location. JSON includes the stable change ID, archive path,
+record path, and updated capabilities.
+
+The script validates before creating the transaction, revalidates under its
+exclusive transaction, and checks actual reviewed baselines again immediately
+before mutation. It applies only declared ADDED/MODIFIED/REMOVED/RENAMED
+exact-title requirements to `.thoth/specs/<capability>/spec.md`, preserving
+unaffected requirements. It then moves the active
+`.thoth/changes/<id>/<id>.md` record to
+`.thoth/changes/archive/<date>-<id>/<id>.md`. The filename and identity remain
+unchanged; the date appears only in the archive directory. Historical changes
+are preserved.
+
+It preflights canonical baselines and destination topology, captures displaced
+original bytes, installs exclusively without overwriting concurrent creation,
+verifies applied bytes, and rolls back handled failures. It rejects unsafe IDs,
+symlink escapes, archive collisions, and unfinished transactions. Forced
+termination is not crash-atomic; a retained
+`.thoth/.archive-transaction/recovery.json` is a filesystem recovery aid, not
+workflow state. Inspect real files, backups, and change/archive locations before
+recovery; never blindly replay external effects. No installer or network access
+is involved.