thoth-agents 0.6.0 → 0.7.0

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

@@ -1,6 +1,6 @@
 ---
 name: thoth-sdd
-description: Apply proportional understanding and risk-aware SDD classification, with one ID-named record for substantial changes.
+description: Governs SDD changes, including the single ID-named record for substantial work. Use for any change requiring proportional understanding and risk-aware classification, whether small or substantial.
 license: MIT
 compatibility: Requires Node.js >=22.19 for bundled product validation.
 metadata:
@@ -74,7 +74,7 @@ At substantial `ready`, first show the user a concise plan summary (goal,
 acceptance, key decisions, units, risks, record path), then always offer
 `Review plan with Oracle (Recommended)` or `Proceed without review`, even when implementation was already authorized.
 Silence is never an explicit review skip; run a fresh read-only review only when
-selected. After a selected `[OKAY]`, separately offer `Implement (Recommended)` /
+selected. After a validated plan-review `OKAY`, separately offer `Implement (Recommended)` /
 `Stop`; prior explicit authorization remains valid, while an explicit later
 `Stop` supersedes it. Record the plan-review selection as
 `EXPLICIT_REVIEW`, `EXPLICIT_SKIP`, or `DEFAULT_REVIEW_AFTER_3`; `SKIPPED`
@@ -88,6 +88,19 @@ independent review; never claim independent PASS or archive.
 
 ## Bounded execution
 
+Root uses the harness progress tool (Pi `todo`, Claude `TodoWrite`, OpenCode
+`todowrite`, Codex `update_plan`) to show SDD progress. Before implementation,
+create one item per remaining applicable stage:
+explore/specify/clarify/classify/plan/tasks/ready/plan review/authorization.
+Pi `todo` may hold several in_progress items for concurrently active stages or
+tasks (e.g. parallel delegated units); Claude `TodoWrite`, OpenCode `todowrite`
+and Codex `update_plan` keep one in_progress item; complete each stage/task
+immediately. At implementation, replace stage items with the record's task rows
+plus final verification and archive (for small changes, use the settled work
+steps plus verification). Keep one list per change; prefix items with the change
+ID when several changes are active. This native progress view is not a sidecar
+record and never replaces SDD gates or authorization.
+
 Apply these rules across all workflow stages. Each assignment names one
 independently acceptable outcome, exact known entrypoints and skill paths,
 concrete accepted inputs and dependencies, its produced result, owned writes and
@@ -143,12 +156,54 @@ parent. Read only the current phase under
 plan review and archive are sibling skill contracts. Use installed local assets
 only; do not provision skills or run a network installer mid-workflow.
 
+## Specialist result validation
+
+Only Oracle gate assignments (plan-review and final-verification) return a
+structured envelope. Before recording plan-review `OKAY` or final-verification
+`PASS`, root resolves `<skill-dir>` from the installed thoth-sdd SKILL.md
+directory, exactly as for `scripts/validate.mjs`, and runs:
+
+```text
+node "<skill-dir>/scripts/validate-result.mjs" --review-kind <kind> [--record-sha256 <hex>] [--no-record] [--input <path>]
+```
+
+Pass the unchanged native terminal result via stdin, or `--input <path>` when
+piping is impractical; do not extract, rewrite, or wrap the envelope, or create
+persisted evidence files. Set `--review-kind` to the assigned `plan-review` or
+`final-verification`. For final verification of a substantial record, set
+`--record-sha256` to the independently calculated expected SHA-256 of exact UTF-8
+bytes before `## Authorization` (see the [verify phase](references/phases/verify.md)).
+Confirm `reviewedRecord` identifies the assigned record.
+For Oracle final verification of a small change without a record, root passes
+`--no-record`; Oracle omits both `reviewedRecord` and `reviewedRecordSha256`.
+Do not combine `--no-record` with `--record-sha256` or plan-review.
+Without `--no-record`, final verification still requires both binding fields.
+
+- Exit **0** means structurally valid only. Root still judges scope, evidence,
+  checks, freshness, provenance, independence, and content before recording any
+  approval, and presents accepted results to the user in readable prose.
+- Exit **1** means no approval. Allow at most one format-only repair request per assignment,
+  shared with any runtime enforcement; it must not change findings or verdict.
+  Exhaustion is a contract failure reported truthfully, never converted into an Oracle `BLOCKED` judgment.
+- Exit **2** or an unavailable skill/validator means validation cannot be completed:
+  report the error (missing assets are installation drift). This blocks only gate approvals;
+  ordinary delegations proceed. Do not provision replacements mid-workflow.
+
+Other Thoth specialist returns use compact markdown fields and are judged on content,
+not validated for format. User-defined custom agents retain their own free format;
+neither ordinary specialist results nor custom agents are rejected for format or
+count as approvals. Oracle `diagnosis` and `advice` never authorize implementation
+or closeout and return compact markdown, not envelopes. Approval comes only from
+the validated gate review field, never free text; validation itself is not user authorization.
+
 ## Gates and CLI
 
 ```text
 node "<skill-dir>/scripts/validate.mjs" --change .thoth/changes/<id> --through <explore|specify|clarify|plan|tasks|checklist|ready|verify|closeout> --json
 ```
 
+Substantial records must not contain other `thoth-result` fences or `**Oracle envelope**:` marker lines anywhere in the file; write examples inline instead.
+
 The early gates validate the one record proportionally. `plan` validates without
 requiring tasks. `tasks` and `ready` require concrete coverage of every accepted
 outcome. `ready` requires settled material decisions before the mandatory
@@ -159,6 +214,16 @@ implementation authorization, and reviewed source digests/baselines. It permits
 final-review and Archive placeholders. `closeout` additionally requires a fresh
 independent Oracle PASS, every acceptance outcome with concrete PASS
 check/evidence, exactly one matching record SHA-256 field, and Archive READY.
+Order: `verify` → fresh final Oracle → root validates and pastes → `closeout` → archive.
+After accepting a validated PASS, root pastes the Oracle's unchanged
+final-verification envelope under `**Oracle envelope**:` in the record's
+Verification section (post-PASS bookkeeping in Verification; no new review).
+Plan-review envelopes are not embedded. Closeout fails without exactly one valid
+PASS envelope matching the record path and prefix digest, consistent with
+`**Verdict**` and `**Reviewed record SHA-256**`. Preserve the envelope unchanged
+when archiving; archived validation accepts its original active record path.
+Historical archived records are not retrofitted or re-validated by this rule.
+
 The initial `PENDING` selection placeholder is allowed before `verify` only.
 `SKIPPED` requires `EXPLICIT_SKIP`; `OKAY` requires `EXPLICIT_REVIEW` or
 `DEFAULT_REVIEW_AFTER_3`. Every canonical spec affected by a durable delta must

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

@@ -2,6 +2,16 @@
 
 Every change requires final verification against accepted outcomes and actual execution evidence. Small low-risk work uses focused independent root checks; substantial or materially risky work requires a fresh read-only Oracle independent from the writer. Judge the actual diff, behavior, completeness, correctness, coherence, checks, and residual risks.
 
+For Oracle final verification of a small change without a record, root passes `--no-record`; Oracle omits both `reviewedRecord` and `reviewedRecordSha256`. Do not combine `--no-record` with `--record-sha256` or plan-review. Otherwise final verification still requires both binding fields.
+
 Before requesting final Oracle for substantial work, run `node "<skill-dir>/scripts/validate.mjs" --change .thoth/changes/<id> --through verify --json`. This gate requires ready coverage, complete tasks, authorization disposition/provenance, and reviewed source digests/baselines; final-review fields, AC evidence rows, and Archive may remain placeholders. For each capability named by a durable delta, add exactly one `Source` entry for `.thoth/specs/<capability>/spec.md`: its reviewed SHA-256 when it exists, or `absent` only when no canonical file exists.
 
-After review, record each outcome's concrete PASS evidence, actual checks, source SHA-256 digests, and the hash of exact UTF-8 record bytes preceding the case-sensitive `## Authorization` heading. After PASS, edits confined to Authorization, Verification, or Closeout need no new review; any edit before `## Authorization` requires fresh independent review and a new digest. This allowance never waives structural checks, truthful provenance, stale-source rejection, or review of changed implementation. Recheck baselines after review; missing or stale digests/absence, missing evidence, or blockers prevent closeout and archive. Never create a verification report or evidence directory; route actionable findings to convergence.
+Assign Oracle a `final-verification` review of the substantial record. Oracle returns exactly one fenced `thoth-result` JSON envelope as the entire final message, following the Oracle gate contract with `role: "oracle"`, `review.kind: "final-verification"`, and `review.verdict: "PASS" | "FAIL" | "BLOCKED"`. Its review includes `reviewedRecord` naming the reviewed record path and `reviewedRecordSha256` containing the 64 lowercase hex SHA-256 of exact UTF-8 record bytes preceding the case-sensitive `## Authorization` heading. PASS requires `status: "complete"` and no blocking risks. FAIL reports findings; BLOCKED is an actual inability to complete review, never a substitute for a malformed result or exhausted format repair.
+
+Root validates the unchanged native terminal result using the thoth-sdd **Specialist result validation** procedure with `--review-kind final-verification --record-sha256 <hex>`, where `<hex>` is the independently calculated expected record-prefix digest. Confirm `reviewedRecord` identifies the assigned record. Root records `**Reviewer**: oracle`, `**Independent from implementer**: Yes`, `**Verdict**: PASS`, and `**Reviewed record SHA-256**` only from a validated PASS envelope whose digest matches the current record, after judging the content and confirming reviewer independence. Invalid results, FAIL, BLOCKED, and diagnosis/advice reviews do not authorize closeout or archive; route findings to convergence and report contract failures truthfully.
+
+Substantial records must not contain other `thoth-result` fences or `**Oracle envelope**:` marker lines anywhere in the file; write examples inline instead.
+
+Order: `verify` → fresh final Oracle → root validates and pastes → `closeout` → archive. After accepting a validated PASS, root pastes the Oracle's unchanged final-verification envelope under `**Oracle envelope**:` in the record's Verification section (post-PASS bookkeeping in Verification; no new review). Plan-review envelopes are not embedded. Closeout fails without exactly one valid PASS envelope matching the record path and prefix digest, consistent with `**Verdict**` and `**Reviewed record SHA-256**`. Preserve the envelope unchanged when archiving; archived validation accepts its original active record path. Historical archived records are not retrofitted or re-validated by this rule.
+
+After accepted review, record each outcome's concrete PASS evidence, actual checks, source SHA-256 digests, and the matched record-prefix hash. After PASS, edits confined to Authorization, Verification, or Closeout need no new review; any edit before `## Authorization` requires fresh independent review and a new digest. This allowance never waives structural checks, truthful provenance, stale-source rejection, or review of changed implementation. Recheck baselines after review; missing or stale digests/absence, missing evidence, or blockers prevent closeout and archive. Never create a verification report or evidence directory; route actionable findings to convergence.

package/plugin/skills/thoth-sdd/scripts/result-contract.json

@@ -0,0 +1,210 @@
+{
+  "schemaVersion": 1,
+  "fence": "thoth-result",
+  "common": {
+    "type": "object",
+    "properties": {
+      "schemaVersion": {
+        "type": "number",
+        "const": 1
+      },
+      "role": {
+        "type": "string",
+        "enum": ["oracle"]
+      },
+      "status": {
+        "type": "string",
+        "enum": ["complete", "partial", "blocked", "failed"]
+      },
+      "conclusion": {
+        "type": "string"
+      },
+      "evidence": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "minLength": 1
+            },
+            "kind": {
+              "type": "string"
+            },
+            "locator": {
+              "type": "string"
+            },
+            "claim": {
+              "type": "string"
+            },
+            "basis": {
+              "type": "string",
+              "enum": ["observed", "inferred"]
+            },
+            "uncertainty": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "kind",
+            "locator",
+            "claim",
+            "basis",
+            "uncertainty"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "verification": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "check": {
+              "type": "string"
+            },
+            "method": {
+              "type": "string"
+            },
+            "outcome": {
+              "type": "string",
+              "enum": ["pass", "fail", "not-run"]
+            },
+            "evidenceIds": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "reason": {
+              "type": "string"
+            }
+          },
+          "required": ["check", "method", "outcome", "evidenceIds", "reason"],
+          "additionalProperties": false
+        }
+      },
+      "risks": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "description": {
+              "type": "string"
+            },
+            "severity": {
+              "type": "string",
+              "enum": ["low", "medium", "high", "critical"]
+            },
+            "blocking": {
+              "type": "boolean"
+            },
+            "evidenceIds": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "required": ["description", "severity", "blocking", "evidenceIds"],
+          "additionalProperties": false
+        }
+      },
+      "openQuestions": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "question": {
+              "type": "string"
+            },
+            "owner": {
+              "type": "string"
+            },
+            "options": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "facts": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "required": ["question", "owner", "options", "facts"],
+          "additionalProperties": false
+        }
+      }
+    },
+    "required": [
+      "schemaVersion",
+      "role",
+      "status",
+      "conclusion",
+      "evidence",
+      "verification",
+      "risks",
+      "openQuestions"
+    ],
+    "additionalProperties": false
+  },
+  "roles": {
+    "oracle": {
+      "type": "object",
+      "properties": {
+        "nextAction": {
+          "type": ["string", "null"]
+        },
+        "review": {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": ["plan-review", "final-verification"]
+            },
+            "verdict": {
+              "type": "string"
+            },
+            "reviewedRecord": {
+              "type": "string",
+              "minLength": 1
+            },
+            "reviewedRecordSha256": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$"
+            }
+          },
+          "required": ["kind", "verdict"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["nextAction", "review"],
+      "additionalProperties": false
+    }
+  },
+  "reviewKinds": {
+    "plan-review": {
+      "verdicts": ["OKAY", "REJECT"]
+    },
+    "final-verification": {
+      "verdicts": ["PASS", "FAIL", "BLOCKED"]
+    }
+  },
+  "rules": {
+    "positiveVerdicts": ["OKAY", "PASS"],
+    "positiveStatus": "complete",
+    "positiveAllowsBlockingRisks": false,
+    "evidenceIdUnique": true,
+    "evidenceReferences": ["verification", "risks"],
+    "recordBindingReviewKind": "final-verification",
+    "recordBindingRequiredFields": ["reviewedRecord", "reviewedRecordSha256"],
+    "recordBindingForbiddenUnderNoRecord": [
+      "reviewedRecord",
+      "reviewedRecordSha256"
+    ]
+  }
+}

package/plugin/skills/thoth-sdd/scripts/validate-result.d.mts

@@ -0,0 +1,47 @@
+import type {
+  SpecialistResult,
+  SpecialistRole,
+  OracleReviewKind,
+} from '../../../src/harness/core/result-contract';
+
+export interface ResultValidationOptions {
+  role?: SpecialistRole;
+  reviewKind?: OracleReviewKind;
+  recordSha256?: string;
+  noRecord?: boolean;
+}
+export type ResultIssueCode =
+  | 'ENVELOPE_FORMAT'
+  | 'JSON_SYNTAX'
+  | 'JSON_DUPLICATE_KEY'
+  | 'REQUIRED_FIELD'
+  | 'UNDECLARED_FIELD'
+  | 'TYPE_MISMATCH'
+  | 'INVALID_VALUE'
+  | 'ROLE_MISMATCH'
+  | 'REVIEW_KIND_MISMATCH'
+  | 'EVIDENCE_ID_DUPLICATE'
+  | 'EVIDENCE_REFERENCE'
+  | 'VERDICT_MISMATCH'
+  | 'VERDICT_STATUS'
+  | 'BLOCKING_RISK'
+  | 'RECORD_BINDING_REQUIRED'
+  | 'RECORD_BINDING_FORBIDDEN'
+  | 'RECORD_DIGEST_MISMATCH'
+  | 'EXPECTATION_INVALID'
+  | 'CLI_USAGE'
+  | 'CLI_INPUT';
+export interface ResultValidationIssue {
+  code: ResultIssueCode;
+  /** JSON Pointer; the empty string denotes the whole message/envelope. */
+  path: string;
+  message: string;
+}
+export type ResultValidation =
+  | { valid: true; envelope: SpecialistResult; issues: [] }
+  | { valid: false; envelope?: never; issues: ResultValidationIssue[] };
+export function validateResult(
+  message: string,
+  options?: ResultValidationOptions,
+): ResultValidation;
+export const RESULT_VALIDATOR_USAGE: string;