thoth-agents 0.6.0 → 0.8.0

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

@@ -0,0 +1,390 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+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')}`;
+
+/** Parse JSON ourselves so duplicate keys cannot be erased by JSON.parse. */
+function parseStrictJSON(source) {
+  let cursor = 0;
+  const fail = (code, path, message) => {
+    throw { code, path, message };
+  };
+  const whitespace = () => {
+    while (/[\t\n\r ]/.test(source[cursor] ?? '\0')) cursor++;
+  };
+  const syntax = (path) =>
+    fail('JSON_SYNTAX', path, `Invalid JSON at offset ${cursor}.`);
+  function string(path) {
+    const start = cursor++;
+    while (cursor < source.length) {
+      const char = source[cursor++];
+      if (char === '\\') cursor++;
+      else if (char === '"') {
+        try {
+          return JSON.parse(source.slice(start, cursor));
+        } catch {
+          syntax(path);
+        }
+      }
+    }
+    syntax(path);
+  }
+  function value(path, depth) {
+    if (depth > 256)
+      fail('JSON_SYNTAX', path, 'JSON nesting exceeds 256 levels.');
+    whitespace();
+    const char = source[cursor];
+    if (char === '"') return string(path);
+    if (char === '{' || char === '[') {
+      const isObject = char === '{';
+      const close = isObject ? '}' : ']';
+      const result = isObject ? Object.create(null) : [];
+      const keys = new Set();
+      cursor++;
+      whitespace();
+      if (source[cursor] === close) {
+        cursor++;
+        return result;
+      }
+      for (;;) {
+        let key = result.length;
+        if (isObject) {
+          if (source[cursor] !== '"') syntax(path);
+          key = string(path);
+          if (keys.has(key))
+            fail(
+              'JSON_DUPLICATE_KEY',
+              childPath(path, key),
+              `Duplicate key ${JSON.stringify(key)}.`,
+            );
+          keys.add(key);
+          whitespace();
+          if (source[cursor++] !== ':') syntax(path);
+        }
+        result[key] = value(childPath(path, key), depth + 1);
+        whitespace();
+        if (source[cursor] === close) {
+          cursor++;
+          return result;
+        }
+        if (source[cursor++] !== ',') syntax(path);
+        whitespace();
+      }
+    }
+    const token =
+      /^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(
+        source.slice(cursor),
+      );
+    if (!token) syntax(path);
+    cursor += token[0].length;
+    const result = JSON.parse(token[0]);
+    if (typeof result === 'number' && !Number.isFinite(result)) syntax(path);
+    return result;
+  }
+  const result = value('', 0);
+  whitespace();
+  if (cursor !== source.length) syntax('');
+  return result;
+}
+
+function checkExpectations(options, issue) {
+  if (
+    options.noRecord &&
+    (options.recordSha256 !== undefined ||
+      (options.reviewKind !== undefined &&
+        options.reviewKind !== contract.rules.recordBindingReviewKind))
+  )
+    issue(
+      'EXPECTATION_INVALID',
+      '',
+      'No-record mode requires final-verification without an expected digest.',
+    );
+  const expectations = [
+    ['role', Object.keys(contract.roles)],
+    ['reviewKind', Object.keys(contract.reviewKinds)],
+  ];
+  for (const [key, values] of expectations) {
+    if (options[key] !== undefined && !values.includes(options[key]))
+      issue('EXPECTATION_INVALID', '', `Unknown expected ${key}.`);
+  }
+  if (
+    options.recordSha256 !== undefined &&
+    !/^[a-f0-9]{64}$/.test(options.recordSha256)
+  )
+    issue(
+      'EXPECTATION_INVALID',
+      '',
+      'Expected digest must be 64 lowercase hex characters.',
+    );
+}
+
+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();
+  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();
+  }
+  let envelope;
+  try {
+    envelope = parseStrictJSON(block[1]);
+  } catch (error) {
+    issues.push(error);
+    return invalid();
+  }
+  function check(value, schema, path) {
+    const type =
+      value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.includes(type)) {
+      issue('TYPE_MISMATCH', path, `Expected ${types.join(' or ')}.`);
+      return;
+    }
+    if ('const' in schema && value !== schema.const)
+      issue('INVALID_VALUE', path, 'Value differs from required constant.');
+    if (schema.enum && !schema.enum.includes(value))
+      issue('INVALID_VALUE', path, 'Value is not in the allowed enumeration.');
+    if (type === 'string') {
+      if (schema.minLength && value.length < schema.minLength)
+        issue('INVALID_VALUE', path, 'String must not be empty.');
+      if (schema.pattern && !new RegExp(schema.pattern).test(value))
+        issue(
+          'INVALID_VALUE',
+          path,
+          'String does not match the required pattern.',
+        );
+    }
+    if (type === 'array') {
+      value.forEach((item, index) => {
+        check(item, schema.items, childPath(path, index));
+      });
+    }
+    if (type === 'object') {
+      for (const key of schema.required)
+        if (!Object.hasOwn(value, key))
+          issue(
+            'REQUIRED_FIELD',
+            childPath(path, key),
+            'Required field is missing.',
+          );
+      for (const key of Object.keys(value)) {
+        if (!Object.hasOwn(schema.properties, key))
+          issue(
+            'UNDECLARED_FIELD',
+            childPath(path, key),
+            'Undeclared field is forbidden.',
+          );
+        else check(value[key], schema.properties[key], childPath(path, key));
+      }
+    }
+  }
+  const roleSchema =
+    envelope &&
+    typeof envelope.role === 'string' &&
+    Object.hasOwn(contract.roles, envelope.role)
+      ? contract.roles[envelope.role]
+      : { properties: {}, required: [] };
+  check(
+    envelope,
+    {
+      ...contract.common,
+      properties: { ...contract.common.properties, ...roleSchema.properties },
+      required: [...contract.common.required, ...roleSchema.required],
+    },
+    '',
+  );
+  if (issues.length) return invalid();
+  if (
+    options.noRecord &&
+    envelope.review.kind !== contract.rules.recordBindingReviewKind
+  ) {
+    issue(
+      'EXPECTATION_INVALID',
+      '/review/kind',
+      'No-record mode requires final-verification.',
+    );
+    return invalid();
+  }
+  if (options.role && envelope.role !== options.role)
+    issue('ROLE_MISMATCH', '/role', 'Role does not match assignment.');
+  if (options.reviewKind && envelope.review.kind !== options.reviewKind)
+    issue(
+      'REVIEW_KIND_MISMATCH',
+      '/review/kind',
+      'Review kind does not match assignment.',
+    );
+  const ids = new Set();
+  envelope.evidence.forEach((entry, index) => {
+    if (contract.rules.evidenceIdUnique && ids.has(entry.id))
+      issue(
+        'EVIDENCE_ID_DUPLICATE',
+        `/evidence/${index}/id`,
+        'Evidence ids must be unique.',
+      );
+    ids.add(entry.id);
+  });
+  for (const field of contract.rules.evidenceReferences) {
+    envelope[field].forEach((entry, index) => {
+      entry.evidenceIds.forEach((id, ref) => {
+        if (!ids.has(id))
+          issue(
+            'EVIDENCE_REFERENCE',
+            `/${field}/${index}/evidenceIds/${ref}`,
+            'Reference does not identify supplied evidence.',
+          );
+      });
+    });
+  }
+  const { kind, verdict } = envelope.review;
+  if (!contract.reviewKinds[kind].verdicts.includes(verdict))
+    issue(
+      'VERDICT_MISMATCH',
+      '/review/verdict',
+      'Verdict is not allowed for this review kind.',
+    );
+  if (contract.rules.positiveVerdicts.includes(verdict)) {
+    if (envelope.status !== contract.rules.positiveStatus)
+      issue(
+        'VERDICT_STATUS',
+        '/status',
+        'Positive verdict requires complete status.',
+      );
+    envelope.risks.forEach((risk, index) => {
+      if (!contract.rules.positiveAllowsBlockingRisks && risk.blocking)
+        issue(
+          'BLOCKING_RISK',
+          `/risks/${index}/blocking`,
+          'Positive verdict forbids blocking risks.',
+        );
+    });
+  }
+  if (options.noRecord) {
+    for (const key of contract.rules.recordBindingForbiddenUnderNoRecord) {
+      if (Object.hasOwn(envelope.review, key))
+        issue(
+          'RECORD_BINDING_FORBIDDEN',
+          `/review/${key}`,
+          'No-record mode forbids reviewed record binding.',
+        );
+    }
+  } else if (envelope.review.kind === contract.rules.recordBindingReviewKind) {
+    for (const key of contract.rules.recordBindingRequiredFields) {
+      if (!envelope.review[key])
+        issue(
+          'RECORD_BINDING_REQUIRED',
+          `/review/${key}`,
+          'Final verification requires reviewed record binding.',
+        );
+    }
+  }
+  if (options.recordSha256 !== undefined) {
+    if (envelope.review.kind !== contract.rules.recordBindingReviewKind)
+      issue(
+        'REVIEW_KIND_MISMATCH',
+        '/review/kind',
+        'Record binding requires final-verification.',
+      );
+    if (
+      envelope.review.reviewedRecordSha256 &&
+      envelope.review.reviewedRecordSha256 !== options.recordSha256
+    )
+      issue(
+        'RECORD_DIGEST_MISMATCH',
+        '/review/reviewedRecordSha256',
+        'Digest does not match assignment.',
+      );
+  }
+  return issues.length ? invalid() : { valid: true, envelope, issues };
+}
+
+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 options = {};
+  let input;
+  const names = {
+    '--role': 'role',
+    '--review-kind': 'reviewKind',
+    '--record-sha256': 'recordSha256',
+    '--no-record': 'noRecord',
+    '--input': 'input',
+  };
+  const seen = new Set();
+  for (let index = 0; index < args.length; index++) {
+    const flag = args[index];
+    if (
+      !Object.hasOwn(names, flag) ||
+      seen.has(flag) ||
+      (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 },
+          ],
+        }),
+      );
+      return 2;
+    }
+    seen.add(flag);
+    if (flag === '--no-record') {
+      options.noRecord = true;
+      continue;
+    }
+    const value = args[++index];
+    if (flag === '--input') input = value;
+    else options[names[flag]] = value;
+  }
+  const expectationIssues = [];
+  checkExpectations(options, (code, path, message) => {
+    expectationIssues.push({ code, path, message });
+  });
+  if (expectationIssues.length) {
+    console.log(JSON.stringify({ 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.' },
+        ],
+      }),
+    );
+    return 2;
+  }
+  const result = validateResult(message, options);
+  console.log(JSON.stringify(result));
+  if (result.valid) return 0;
+  return result.issues.some((issue) => issue.code === 'EXPECTATION_INVALID')
+    ? 2
+    : 1;
+}
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+)
+  process.exitCode = main(process.argv.slice(2));

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

@@ -17,6 +17,7 @@ import {
   parseRequirementDelta,
   preflightRequirementDeltas,
 } from './durable-deltas.mjs';
+import { validateResult } from './validate-result.mjs';
 
 const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
 const gates = [
@@ -261,10 +262,16 @@ function preflightDeltas(root, deltas, errors, warnings, recordName) {
 }
 
 function settled(text) {
-  return (
-    Boolean(text?.trim()) &&
-    !/\b(?:pending|unresolved|unknown|ask|tbd|todo)\b/i.test(text)
-  );
+  if (!text?.trim() || /\bTBD\b/.test(text)) return false;
+  return !text.split(/\r?\n/).some((line) => {
+    const content = line
+      .replace(/\*\*|__/g, '')
+      .trim()
+      .replace(/^(?:[-+*]|\d+[.)])\s+/, '')
+      .replace(/^\[[ xX]\]\s*/, '')
+      .replace(/^AC-\d+:\s*/, '');
+    return /^(?:TBD|PENDING)(?=:|\s*$)/i.test(content);
+  });
 }
 
 function coverageErrors(text, ids, errors, recordName) {
@@ -293,6 +300,184 @@ function coverageErrors(text, ids, errors, recordName) {
   return rows;
 }
 
+// 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 markers = [];
+  const fences = [];
+  const authorization = lines.findIndex(
+    ({ line }) => line === '## Authorization',
+  );
+  const verification = lines.findIndex(
+    ({ line }) => line === '## Verification',
+  );
+  const closeout = lines.findIndex(
+    ({ line }, index) => index > verification && line === '## Closeout',
+  );
+  const verificationEnd = lines.findIndex(
+    ({ line }, index) => index > verification && line.startsWith('## '),
+  );
+  for (const [index, { line }] of lines.entries()) {
+    if (line.trim() === '**Oracle envelope**:') markers.push(index);
+    const opening =
+      /^(\s*)(?:[>*+-]\s*|\d+[.)]\s*)*(`{3,}|~{3,})\s*thoth-result/i.exec(line);
+    if (!opening) continue;
+    let end = index + 1;
+    for (; end < lines.length; end++) {
+      const closing = /^(\s*)(`{3,}|~{3,})[ \t]*$/.exec(lines[end].line);
+      if (
+        closing &&
+        closing[1] === opening[1] &&
+        closing[2][0] === opening[2][0] &&
+        closing[2].length >= opening[2].length
+      )
+        break;
+    }
+    fences.push({
+      index,
+      end,
+      closed: end < lines.length,
+      block: lines
+        .slice(index, end + 1)
+        .map(({ raw }) => raw)
+        .join(''),
+    });
+  }
+  let next = markers[0] + 1;
+  while (next < lines.length && !lines[next].line.trim()) next++;
+  const positioned =
+    verification >= 0 &&
+    closeout > verification &&
+    markers[0] > verification &&
+    markers[0] < verificationEnd &&
+    fences[0]?.index === next &&
+    next < verificationEnd &&
+    (!fences[0]?.closed || fences[0].end < verificationEnd);
+  return {
+    markers,
+    fences,
+    positioned,
+    authorizationOffset: lines[authorization]?.offset,
+  };
+}
+
+function validateOracleEnvelope({
+  extraction,
+  verificationFields,
+  recordSha256,
+  reviewedDigest,
+  expectedRecord,
+  errors,
+  recordName,
+}) {
+  const { markers, fences, positioned } = extraction;
+  if (markers.length > 1 || fences.length > 1) {
+    errors.push(
+      issue(
+        'SDD-ORACLE-ENVELOPE-DUPLICATE',
+        'Exactly one Oracle envelope marker and block are required',
+        recordName,
+      ),
+    );
+    return;
+  }
+  if (!markers.length || !fences.length || !positioned) {
+    errors.push(
+      issue(
+        'SDD-ORACLE-ENVELOPE-MISSING',
+        'Oracle envelope marker followed by a final-verification block is required',
+        recordName,
+      ),
+    );
+    return;
+  }
+  if (!fences[0].closed) {
+    errors.push(
+      issue(
+        'SDD-ORACLE-ENVELOPE-INVALID',
+        'Oracle envelope fence is unclosed',
+        recordName,
+      ),
+    );
+    return;
+  }
+  // Preserve the original wrapper and line endings for shared-contract validation.
+  const result = validateResult(fences[0].block, {
+    reviewKind: 'final-verification',
+    recordSha256: recordSha256,
+  });
+  if (!result.valid) {
+    errors.push(
+      issue(
+        'SDD-ORACLE-ENVELOPE-INVALID',
+        result.issues
+          .map((entry) => `${entry.code}: ${entry.message}`)
+          .join('; '),
+        recordName,
+      ),
+    );
+    if (
+      result.issues.some((entry) => entry.code === 'RECORD_DIGEST_MISMATCH')
+    ) {
+      errors.push(
+        issue(
+          'SDD-ORACLE-ENVELOPE-DIGEST-MISMATCH',
+          'Oracle envelope digest does not match the reviewed record prefix',
+          recordName,
+        ),
+      );
+    }
+    return;
+  }
+  const { review } = result.envelope;
+  if (review.verdict !== 'PASS') {
+    errors.push(
+      issue(
+        'SDD-ORACLE-ENVELOPE-NOT-PASS',
+        'Oracle final-verification verdict must be PASS',
+        recordName,
+      ),
+    );
+  }
+  if (review.reviewedRecord !== expectedRecord) {
+    errors.push(
+      issue(
+        'SDD-ORACLE-ENVELOPE-RECORD-MISMATCH',
+        `Oracle envelope must review ${expectedRecord}`,
+        recordName,
+      ),
+    );
+  }
+  if (review.reviewedRecordSha256 !== reviewedDigest) {
+    errors.push(
+      issue(
+        'SDD-ORACLE-ENVELOPE-DIGEST-MISMATCH',
+        'Oracle envelope and Reviewed record SHA-256 field must agree',
+        recordName,
+      ),
+    );
+  }
+  const verdictLines = verificationFields.match(/^\*\*Verdict\*\*:.*$/gm) ?? [];
+  if (
+    verdictLines.length !== 1 ||
+    verdictLines[0] !== `**Verdict**: ${review.verdict}`
+  ) {
+    errors.push(
+      issue(
+        'SDD-ORACLE-ENVELOPE-VERDICT-MISMATCH',
+        'Oracle envelope and Verdict field must agree',
+        recordName,
+      ),
+    );
+  }
+}
+
 export function validate({ change, through }) {
   if (!gates.includes(through)) throw new Error('Invalid SDD validation gate');
   const errors = [];
@@ -358,7 +543,7 @@ export function validate({ change, through }) {
     !new RegExp(
       `^# Change: ${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`,
       'm',
-    ).test(text) ||
+    ).test(text.replace(/^\uFEFF/, '')) ||
     !/^\*\*Classification\*\*: substantial$/m.test(text) ||
     !/^\*\*Scope\*\*: (?:local|coordinated|cross-cutting)$/m.test(text) ||
     !/^\*\*Uncertainty\*\*: (?:low|medium|high)$/m.test(text) ||
@@ -534,9 +719,18 @@ export function validate({ change, through }) {
     }
     const verificationText =
       section(text, 'Verification', { trim: false }) ?? '';
-    const verified = verificationText.trim();
+    // Envelope contents are not record fields, AC rows, or reviewed source lines.
+    const extraction = scanOracleEnvelope(text);
+    const verificationFields =
+      through === 'closeout'
+        ? verificationText.replace(extraction.fences[0]?.block ?? '', '')
+        : verificationText;
+    const verified = verificationFields.trim();
     if (through === 'closeout') {
-      const prefix = text.slice(0, authorizationHeading?.index ?? text.length);
+      const prefix = text.slice(
+        0,
+        extraction.authorizationOffset ?? text.length,
+      );
       if (
         !/^\*\*Reviewer\*\*: oracle$/m.test(verified) ||
         !/^\*\*Independent from implementer\*\*: Yes$/m.test(verified) ||
@@ -551,7 +745,8 @@ export function validate({ change, through }) {
         );
       }
       const digestLines =
-        verificationText.match(/^\*\*Reviewed record SHA-256\*\*:.*$/gm) ?? [];
+        verificationFields.match(/^\*\*Reviewed record SHA-256\*\*:.*$/gm) ??
+        [];
       const reviewedDigest =
         digestLines.length === 1
           ? /^\*\*Reviewed record SHA-256\*\*: ([a-f0-9]{64})$/.exec(
@@ -567,6 +762,16 @@ export function validate({ change, through }) {
           ),
         );
       }
+      validateOracleEnvelope({
+        extraction,
+        verificationFields,
+        recordSha256: sha(prefix),
+        reviewedDigest,
+        // Archived records retain the active path reviewed by the Oracle.
+        expectedRecord: `.thoth/changes/${id}/${id}.md`,
+        errors,
+        recordName,
+      });
       const rows = verified
         .split(/\r?\n/)
         .filter((line) => /^- AC-/.test(line));

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

@@ -82,6 +82,14 @@ exactly one SHA field line; put notes on separate lines below the fields.
 **Verdict**: PENDING
 **Reviewed record SHA-256**: PENDING
 
+**Oracle envelope**:
+
+```thoth-result
+PENDING
+```
+
+After PASS, root pastes the Oracle's unchanged final-verification envelope here.
+
 - AC-1: PENDING | check | evidence
 - Source: relative/path | sha256:<actual-source-digest>
 - Source: .thoth/specs/<capability>/spec.md | sha256:<actual-source-digest>

package/thoth-agents.schema.json

@@ -207,6 +207,13 @@
                 }
               ]
             },
+            "skills": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
             "temperature": {
               "type": "number",
               "minimum": 0,
@@ -262,6 +269,13 @@
               }
             ]
           },
+          "skills": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
           "temperature": {
             "type": "number",
             "minimum": 0,