thoth-agents 0.9.8 → 0.9.9

package/skills/thoth-sdd/SKILL.md

@@ -160,31 +160,74 @@ only; do not provision skills or run a network installer mid-workflow.
 
 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:
+`PASS`, use the harness-delivered `thoth-gate-verdict` line for that result:
+exactly one per delivered result; more than one, or one inside the envelope
+fence, is invalid. No delivered verdict means the explicit fallback below,
+not approval. Never re-emit the envelope to validate it when a verdict exists.
+
+Require `valid:true` and `kind` matches the assignment. Plan review requires
+`verdict:"OKAY"` and `record` null or the assigned record; ignore `mode` and
+`recordDigest`. Final verification requires `verdict:"PASS"` plus:
+
+- Record-bound final verification requires `record` = assigned record and
+  `mode:"record"`, with `recordDigest:"match"`: the bundled validator hashed exact
+  UTF-8 record bytes before `## Authorization`. A mismatch is no approval. If a
+  valid verdict has `recordDigest:"unavailable"`, independently calculate the
+  record-prefix SHA-256 and compare it with `recordSha256`; mismatch or inability
+  to calculate means no approval. This checks digest agreement only: do not rerun
+  the validator or re-emit the envelope.
+- Recordless small-change final verification requires `mode:"no-record"`, null
+  `record` and `recordSha256`, and `recordDigest:"none"`.
+
+Record equality, `mode` and `recordDigest` checks apply only to final verification.
+See the [verify phase](references/phases/verify.md).
+Copy the verdict and `recordSha256` into the record when there is one; final
+verification uses that digest for `**Reviewed record SHA-256**`. Still judge
+scope, evidence, checks, freshness, provenance, independence, and content.
+Validation is not authorization.
+
+Delivery differs by harness: Pi attaches verdicts to completion notifications,
+`subagent_result`, and task-mode `subagent_run` (match `taskId`); OpenCode appends
+them to Oracle `task` output. Claude Code verdicts arrive with Subagent hand-back
+reports (foreground or background; `agent` is the agent id, match it to the Agent
+result's `agentId`) and completed foreground `Agent` results whose content carries
+the report. Other deliveries (e.g. background runs without hand-back) carry none;
+use the explicit compact fallback below. Codex verdicts arrive only with
+multi-agent v1 `wait_agent` results when plugin hooks are enabled and trusted;
+`agent` is the status-map key, not proof of Oracle provenance. Multi-agent v2
+delivers the Oracle's `FINAL_ANSWER` as an inter-agent message with no hook, so no
+verdict arrives and root uses the explicit compact fallback below on the unchanged
+result.
+
+### Explicit compact fallback
+
+Only when no verdict was delivered (hook unavailable/untrusted, a Codex multi-agent
+v2 delivery, or a Claude background run without hand-back), resolve `<skill-dir>` from the installed
+thoth-sdd SKILL.md directory, exactly as for `scripts/validate.mjs`, and run:
 
 ```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.
+Supply the unchanged native result through stdin or an existing `--input <path>`;
+never extract, rewrite, or wrap the envelope or create persisted evidence files.
+The CLI prints only the compact summary, not the envelope. Set `--review-kind`
+to the assigned `plan-review` or `final-verification`. For record-bound final
+verification, independently calculate the expected record-prefix SHA-256 and
+pass `--record-sha256 <hex>`. Apply the same kind-specific approval checks above;
+the explicit expected digest supplies agreement if the CLI cannot read the
+record itself. Copy the accepted summary and digest into
+the 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 requires both fields.
+
+- Exit **0** means structurally valid only, not approval: apply the assignment,
+  digest, content and provenance checks above.
+- Exit **1** means no approval. Invalid delivered verdicts have the same rule.
+  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, 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.
@@ -215,7 +258,8 @@ 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
+Root validates via the delivery verdict (explicit compact fallback only if none
+was delivered), records the verdict and digest, then 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
@@ -230,8 +274,10 @@ The initial `PENDING` selection placeholder is allowed before `verify` only.
 have exactly one `Source` entry in the same record:
 `- Source: .thoth/specs/<capability>/spec.md | sha256:<digest>` when present, or
 `- Source: .thoth/specs/<capability>/spec.md | absent` when absent. Missing or
-stale coverage blocks `verify`, closeout, and archive. Calculate the record hash
-from exact UTF-8 bytes preceding the case-sensitive `## Authorization` heading.
+stale coverage blocks `verify`, closeout, and archive. The record hash covers
+exact UTF-8 bytes preceding the case-sensitive `## Authorization` heading; use
+the delivery verdict's `recordSha256` when its digest matches. Independent hash
+calculation is needed only for unavailable digest agreement or the CLI fallback.
 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

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

@@ -2,13 +2,17 @@
 
 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.
+For Oracle final verification of a small change without a record, require a valid delivery verdict with `mode:"no-record"`, null `record` and `recordSha256`, and `recordDigest:"none"`. Oracle omits both `reviewedRecord` and `reviewedRecordSha256`. Only in the CLI fallback, root passes `--no-record`. 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.
 
 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.
+Record equality, `mode` and `recordDigest` checks apply only to final verification. Plan review requires `valid:true`, `kind:"plan-review"`, `verdict:"OKAY"`, and `record` null or the assigned record; ignore `mode` and `recordDigest`.
+
+Root uses the harness-delivered `thoth-gate-verdict` under thoth-sdd **Specialist result validation**: exactly one outside the envelope fence, `valid:true`, assigned `kind:"final-verification"`, `verdict:"PASS"`, assigned `record`, `mode:"record"`, and `recordDigest:"match"`. Never re-emit the envelope to validate it. If a valid verdict reports `recordDigest:"unavailable"`, independently hash exact UTF-8 record bytes before `## Authorization` and compare with `recordSha256`; mismatch or unavailable calculation means no approval, with no validator rerun. Use the explicit compact CLI fallback only when no verdict was delivered: unchanged result, `--review-kind final-verification --record-sha256 <hex>` with the independently calculated expected prefix digest. Claude Code verdicts arrive with Subagent hand-back reports (foreground or background; `agent` is the agent id, match it to the Agent result's `agentId`) and completed foreground `Agent` results whose content carries the report. Other deliveries (e.g. background runs without hand-back) carry none; use the explicit compact CLI fallback.
+
+Root records `**Reviewer**: oracle`, `**Independent from implementer**: Yes`, `**Verdict**: PASS`, and `**Reviewed record SHA-256**` only from a validated PASS whose digest matches the current record, after judging content and confirming reviewer independence and provenance. Copy the verdict and `recordSha256` into the record (accepted CLI summary/digest in fallback); use `recordSha256` for the SHA field. 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.
 

package/skills/thoth-sdd/scripts/record-digest.mjs

@@ -0,0 +1,15 @@
+import { createHash } from 'node:crypto';
+
+/** Hash the exact UTF-8 prefix preceding the first case-sensitive heading. */
+export function recordPrefixSha256(text) {
+  let offset = 0;
+  for (const raw of text.split(/(?<=\n)/)) {
+    let line = raw.replace(/\r?\n$/, '');
+    if (offset === 0) line = line.replace(/^\uFEFF/, '');
+    if (line === '## Authorization') break;
+    offset += raw.length;
+  }
+  return createHash('sha256')
+    .update(text.slice(0, offset), 'utf8')
+    .digest('hex');
+}

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

@@ -44,4 +44,23 @@ export function validateResult(
   message: string,
   options?: ResultValidationOptions,
 ): ResultValidation;
+export interface GateSummaryOptions {
+  cwd?: string;
+}
+export interface GateResultSummary {
+  valid: boolean;
+  role: string | null;
+  kind: string | null;
+  verdict: string | null;
+  mode: 'record' | 'no-record';
+  record: string | null;
+  recordSha256: string | null;
+  recordDigest: 'none' | 'match' | 'mismatch' | 'unavailable';
+  issues: Pick<ResultValidationIssue, 'code' | 'path'>[];
+}
+export function summarizeGateResult(
+  message: string,
+  options?: GateSummaryOptions,
+): GateResultSummary;
+export function formatGateVerdict(summary: GateResultSummary): string;
 export const RESULT_VALIDATOR_USAGE: string;

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

@@ -1,10 +1,9 @@
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { recordPrefixSha256 } from './record-digest.mjs';
+import contract from './result-contract.json' with { type: 'json' };
 
-const contract = JSON.parse(
-  readFileSync(new URL('./result-contract.json', import.meta.url), 'utf8'),
-);
 const childPath = (path, key) =>
   `${path}/${String(key).replaceAll('~', '~0').replaceAll('/', '~1')}`;
 
@@ -123,32 +122,39 @@ function checkExpectations(options, issue) {
     );
 }
 
-export function validateResult(message, options = {}) {
-  const issues = [];
-  const issue = (code, path, text) =>
-    issues.push({ code, path, message: text });
-  const invalid = () => ({ valid: false, issues });
-  checkExpectations(options, issue);
-  if (issues.length) return invalid();
+function parseEnvelope(message) {
   const trimmed = typeof message === 'string' ? message.trim() : '';
   const block = new RegExp(
     `^\`\`\`${contract.fence}\\r?\\n([\\s\\S]*?)\\r?\\n\`\`\`$`,
   ).exec(trimmed);
   if (!block || (trimmed.match(/^```.*$/gm) ?? []).length !== 2) {
-    issue(
-      'ENVELOPE_FORMAT',
-      '',
-      'Expected exactly one thoth-result fence and no surrounding prose.',
-    );
-    return invalid();
+    return {
+      issues: [
+        {
+          code: 'ENVELOPE_FORMAT',
+          path: '',
+          message:
+            'Expected exactly one thoth-result fence and no surrounding prose.',
+        },
+      ],
+    };
   }
-  let envelope;
   try {
-    envelope = parseStrictJSON(block[1]);
+    return { envelope: parseStrictJSON(block[1]), issues: [] };
   } catch (error) {
-    issues.push(error);
-    return invalid();
+    return { issues: [error] };
   }
+}
+
+function validateEnvelope(parsed, options) {
+  const issues = [];
+  const issue = (code, path, text) =>
+    issues.push({ code, path, message: text });
+  const invalid = () => ({ valid: false, issues });
+  checkExpectations(options, issue);
+  if (issues.length) return invalid();
+  if (parsed.issues.length) return { valid: false, issues: parsed.issues };
+  const { envelope } = parsed;
   function check(value, schema, path) {
     const type =
       value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
@@ -314,9 +320,83 @@ export function validateResult(message, options = {}) {
   return issues.length ? invalid() : { valid: true, envelope, issues };
 }
 
+export function validateResult(message, options = {}) {
+  return validateEnvelope(parseEnvelope(message), options);
+}
+
+const stringOrNull = (value) => (typeof value === 'string' ? value : null);
+function gateMode(envelope) {
+  const review = envelope?.review;
+  return review?.kind === contract.rules.recordBindingReviewKind &&
+    contract.rules.recordBindingRequiredFields.every(
+      (key) => !Object.hasOwn(review, key),
+    )
+    ? 'no-record'
+    : 'record';
+}
+
+function recordDigest(review, cwd) {
+  if (!review || !Object.hasOwn(review, 'reviewedRecordSha256')) return 'none';
+  if (!cwd || typeof review.reviewedRecord !== 'string') return 'unavailable';
+  const inside = (root, path) => {
+    const fromRoot = relative(root, path);
+    return (
+      fromRoot !== '..' &&
+      !fromRoot.startsWith(`..${sep}`) &&
+      !isAbsolute(fromRoot)
+    );
+  };
+  try {
+    const root = resolve(cwd);
+    const path = resolve(root, review.reviewedRecord);
+    if (!inside(root, path) || !inside(realpathSync(root), realpathSync(path)))
+      return 'unavailable';
+    return recordPrefixSha256(readFileSync(path, 'utf8')) ===
+      review.reviewedRecordSha256
+      ? 'match'
+      : 'mismatch';
+  } catch {
+    return 'unavailable';
+  }
+}
+
+function summarizeValidation(envelope, result, cwd) {
+  const review = envelope?.review;
+  return {
+    valid: result.valid,
+    role: stringOrNull(envelope?.role),
+    kind: stringOrNull(review?.kind),
+    verdict: stringOrNull(review?.verdict),
+    mode: gateMode(envelope),
+    record: stringOrNull(review?.reviewedRecord),
+    recordSha256: stringOrNull(review?.reviewedRecordSha256),
+    recordDigest: recordDigest(review, cwd),
+    issues: result.issues.map(({ code, path }) => ({ code, path })),
+  };
+}
+
+export function summarizeGateResult(message, { cwd } = {}) {
+  const parsed = parseEnvelope(message);
+  return summarizeValidation(
+    parsed.envelope,
+    validateEnvelope(parsed, {
+      noRecord: gateMode(parsed.envelope) === 'no-record',
+    }),
+    cwd,
+  );
+}
+
+export function formatGateVerdict(summary) {
+  return `thoth-gate-verdict ${JSON.stringify(summary)}`;
+}
+
 export const RESULT_VALIDATOR_USAGE =
   'node validate-result.mjs [--role oracle] [--review-kind plan-review|final-verification] [--record-sha256 <hex>] [--no-record] [--input <path>]';
 function main(args) {
+  const print = (result, envelope) =>
+    console.log(
+      JSON.stringify(summarizeValidation(envelope, result, process.cwd())),
+    );
   const options = {};
   let input;
   const names = {
@@ -335,14 +415,7 @@ function main(args) {
       (flag !== '--no-record' &&
         (!args[index + 1] || args[index + 1].startsWith('--')))
     ) {
-      console.log(
-        JSON.stringify({
-          valid: false,
-          issues: [
-            { code: 'CLI_USAGE', path: '', message: RESULT_VALIDATOR_USAGE },
-          ],
-        }),
-      );
+      print({ valid: false, issues: [{ code: 'CLI_USAGE', path: '' }] });
       return 2;
     }
     seen.add(flag);
@@ -359,31 +432,27 @@ function main(args) {
     expectationIssues.push({ code, path, message });
   });
   if (expectationIssues.length) {
-    console.log(JSON.stringify({ valid: false, issues: expectationIssues }));
+    print({ valid: false, issues: expectationIssues });
     return 2;
   }
   let message;
   try {
     message = readFileSync(input ?? 0, 'utf8');
   } catch {
-    console.log(
-      JSON.stringify({
-        valid: false,
-        issues: [
-          { code: 'CLI_INPUT', path: '', message: 'Unable to read input.' },
-        ],
-      }),
-    );
+    print({ valid: false, issues: [{ code: 'CLI_INPUT', path: '' }] });
     return 2;
   }
-  const result = validateResult(message, options);
-  console.log(JSON.stringify(result));
+  const parsed = parseEnvelope(message);
+  const result = validateEnvelope(parsed, options);
+  print(result, parsed.envelope);
   if (result.valid) return 0;
   return result.issues.some((issue) => issue.code === 'EXPECTATION_INVALID')
     ? 2
     : 1;
 }
+// Bundled imports share the entry/chunk URL and must not invoke this CLI.
 if (
+  import.meta.url.endsWith('/validate-result.mjs') &&
   process.argv[1] &&
   resolve(process.argv[1]) === fileURLToPath(import.meta.url)
 )

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

@@ -17,6 +17,7 @@ import {
   parseRequirementDelta,
   preflightRequirementDeltas,
 } from './durable-deltas.mjs';
+import { recordPrefixSha256 } from './record-digest.mjs';
 import { validateResult } from './validate-result.mjs';
 
 const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
@@ -302,18 +303,12 @@ function coverageErrors(text, ids, errors, recordName) {
 
 // Whole-file textual binding: Markdown containers never hide candidates or markers.
 function scanOracleEnvelope(text) {
-  let offset = 0;
-  const lines = text.split(/(?<=\n)/).map((raw) => {
-    const entry = { raw, offset, line: raw.replace(/\r?\n$/, '') };
-    if (offset === 0) entry.line = entry.line.replace(/^\uFEFF/, '');
-    offset += raw.length;
-    return entry;
+  const lines = text.split(/(?<=\n)/).map((raw, index) => {
+    const line = raw.replace(/\r?\n$/, '');
+    return { raw, line: index === 0 ? line.replace(/^\uFEFF/, '') : line };
   });
   const markers = [];
   const fences = [];
-  const authorization = lines.findIndex(
-    ({ line }) => line === '## Authorization',
-  );
   const verification = lines.findIndex(
     ({ line }) => line === '## Verification',
   );
@@ -363,7 +358,6 @@ function scanOracleEnvelope(text) {
     markers,
     fences,
     positioned,
-    authorizationOffset: lines[authorization]?.offset,
   };
 }
 
@@ -727,10 +721,7 @@ export function validate({ change, through }) {
         : verificationText;
     const verified = verificationFields.trim();
     if (through === 'closeout') {
-      const prefix = text.slice(
-        0,
-        extraction.authorizationOffset ?? text.length,
-      );
+      const recordSha256 = recordPrefixSha256(text);
       if (
         !/^\*\*Reviewer\*\*: oracle$/m.test(verified) ||
         !/^\*\*Independent from implementer\*\*: Yes$/m.test(verified) ||
@@ -753,7 +744,7 @@ export function validate({ change, through }) {
               digestLines[0],
             )?.[1]
           : undefined;
-      if (reviewedDigest !== sha(prefix)) {
+      if (reviewedDigest !== recordSha256) {
         errors.push(
           issue(
             'SDD-VERIFICATION-STALE',
@@ -765,7 +756,7 @@ export function validate({ change, through }) {
       validateOracleEnvelope({
         extraction,
         verificationFields,
-        recordSha256: sha(prefix),
+        recordSha256,
         reviewedDigest,
         // Archived records retain the active path reviewed by the Oracle.
         expectedRecord: `.thoth/changes/${id}/${id}.md`,