@open-agent-toolkit/cli 0.2.53 → 0.2.55

package/assets/skills/recon/references/profiles.md

@@ -0,0 +1,58 @@
+# Recon Profiles
+
+Profiles define assurance topology, not a model tier. The controller sizes
+adaptive lanes from a mechanical source inventory, shows exact counts before
+approval, and never exceeds the approved hard cap. Every wave remains
+homogeneous and every pass uses the same approved model and effort.
+
+## quick
+
+Use for bounded orientation where independently checked locators and supported
+claims are sufficient.
+
+- Required: one mapping wave, one or more non-overlapping gather lanes, one
+  compile lane, deterministic schema and locator validation, and rendering.
+- Adaptive lane range: 1–4 gather lanes; hard cap 4.
+- Maximum concurrency: 4.
+- Assurance ceiling: `supported`; a quick packet is never `verified`.
+- Conditional work: no semantic, adversarial, or coverage worker is implied.
+
+## standard
+
+Use for load-bearing evidence that needs independent semantic challenge.
+
+- Required: quick topology plus selectively blind semantic verification,
+  adversarial review, coverage review, and reconciliation.
+- Adaptive lane range: 1–6 gather lanes and 1–3 verification lanes; hard cap 10
+  total worker lanes.
+- Maximum concurrency: 6.
+- Assurance ceiling: `verified` only after exact locator validation, affirmative
+  independent semantic review, no unresolved material challenge, and adequate
+  coverage.
+- Conditional work: at most one approved reconciliation lane for a material
+  contradiction.
+
+## thorough
+
+Use when expensive failure or correlated blind spots justify redundant source
+reopening and explicit contradiction resolution.
+
+- Required: standard topology plus redundant independent gathering and
+  verification for load-bearing claims and explicit contradiction resolution.
+- Adaptive lane range: 2–10 gather lanes and 2–6 verification or adversarial
+  lanes; hard cap 20 total worker lanes.
+- Maximum concurrency: 8.
+- Assurance ceiling: `verified` only for claims affirmed by the required
+  independent passes and left without unresolved material challenge.
+- Conditional work: up to two approved contradiction-resolution lanes within
+  the manifest's hard cap.
+
+## Planning Rules
+
+1. Partition by source or question so lane inputs and outputs never overlap.
+2. Classify required and conditional waves before target preparation.
+3. Compute the run-wide maximum model-class floor from every allowed wave.
+4. Reduce lanes when scope is small; never invent work to fill a profile cap.
+5. If runtime limits prevent the requested topology, prepare a different
+   profile for approval or publish an honest partial after an accepted failure.
+6. Never add a lane, retry, or replacement beyond the approved envelope.

package/assets/skills/recon/references/worker-contract.md

@@ -0,0 +1,71 @@
+# Recon Worker Contract
+
+Every recon assignment is a non-interactive leaf task. The controller supplies
+the complete assignment; a worker does not infer broader authority.
+
+## Required Assignment Envelope
+
+The assignment must declare:
+
+- `runId`, `waveId`, `laneId`, and exactly one mode;
+- bounded objective, included scope, and excluded scope;
+- allowed inputs and excluded inputs;
+- source-read authority in `readSources`, including allowed read-only tools;
+- sole `writePath`, contained by the packet directory and unique to the lane;
+- required artifact `kind`, `schemaVersion`, and output schema;
+- enforcement level and deadline; and
+- whether failure should be recorded as required, optional, or conditional.
+
+Reject an incomplete or contradictory assignment before reading sources. Never
+request credentials, mutate an investigated source, broaden scope, or choose an
+alternate write path.
+
+## Modes
+
+- `map`: inventory only the assigned source partition and report candidate
+  evidence areas, unavailable inputs, and coverage gaps.
+- `gather`: inspect assigned sources and emit source-grounded findings with
+  typed locators, minimal display excerpts, uncertainty, and contradictions.
+- `compile`: consume only designated dossiers and create a provisional claim
+  ledger candidate. Deduplicate without inventing evidence.
+- `verify`: consume an immutable verification brief, reopen only its declared
+  sources, test locators and claim semantics, and report claim dispositions.
+- `adversary`: consume scope, questions, and provisional statements only; seek
+  counterevidence, unsupported inference, and missing alternatives.
+- `coverage`: compare declared scope and questions with ledger coverage without
+  reading gatherer reasoning.
+- `reconcile`: apply review dispositions and contradiction outcomes to a new
+  ledger candidate. Preserve prior revisions and never invent evidence.
+
+No other mode is valid.
+
+## Output Contract
+
+Write exactly one JSON artifact at `writePath`. The artifact must include:
+
+- `kind`, `schemaVersion`, run/wave/lane identity, mode, and outcome;
+- the exact allowed and excluded inputs actually honored;
+- findings or dispositions with evidence IDs and typed locators;
+- uncertainty, contradictions, and gaps as explicit arrays;
+- safe categorical diagnostics for unavailable or invalid inputs; and
+- direct input artifact references and digests when applicable.
+
+Persist minimal excerpts only. Detect and redact secret spans before writing;
+never persist the secret or its sensitive-span digest. Finish by returning the
+artifact path and compact outcome only.
+
+The controller validates the candidate against `packet-contract.md` with the
+bundled deterministic artifact validator. A validation failure quarantines the
+candidate; it never authorizes the worker to rewrite a shared artifact, retry,
+or launch a replacement.
+
+## Invariants
+
+- Read only the assignment's allowed inputs using its source-read authority.
+- Write only the assigned artifact; never update a shared ledger or manifest.
+- Never interact with the user.
+- Never dispatch children, helpers, reviewers, or replacement workers.
+- Never read excluded inputs, prior review conclusions, or raw reasoning that
+  the selected mode is required to remain blind to.
+- Report uncertainty and contradiction instead of converting them to
+  confidence scores.

package/assets/skills/recon/scripts/create-review-brief.mjs

@@ -0,0 +1,452 @@
+#!/usr/bin/env node
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { canonicalJson, hashFile } from './lib/canonical-json.mjs';
+import { issue, isObject, validateArtifactShape } from './lib/contracts.mjs';
+import { assertSafeOutputPath } from './lib/safe-path.mjs';
+
+const commonKeys = [
+  'kind',
+  'schemaVersion',
+  'id',
+  'runId',
+  'mode',
+  'createdAt',
+  'excludedInputs',
+];
+const allowedKeys = {
+  verify: new Set([...commonKeys, 'claims', 'sources']),
+  adversary: new Set([
+    ...commonKeys,
+    'scope',
+    'questions',
+    'provisionalStatements',
+  ]),
+  coverage: new Set([...commonKeys, 'scope', 'questions', 'claims']),
+};
+const forbiddenKeys = new Set([
+  'derivedFrom',
+  'provenance',
+  'reviewIds',
+  'synthesis',
+  'compilerReasoning',
+  'inputArtifacts',
+  'priorReviews',
+  'dossierPath',
+]);
+
+const reviewSourceFields = {
+  repository: ['root', 'revision', 'dirty', 'contentHashes'],
+  file: ['path', 'contentHash'],
+  url: ['url', 'capturePath', 'captureDigest', 'validatorState'],
+  'command-output': [
+    'argv',
+    'cwd',
+    'exitStatus',
+    'outputPath',
+    'outputDigest',
+    'environmentNames',
+  ],
+  'connected-resource': [
+    'system',
+    'resourceId',
+    'resourceVersion',
+    'retrievalToken',
+    'capturePath',
+    'captureDigest',
+  ],
+};
+const commonReviewSourceFields = [
+  'id',
+  'kind',
+  'available',
+  'authority',
+  'observedAt',
+  'validationState',
+];
+
+function selectedClaims(ledger, claimIds) {
+  const selected = claimIds ? new Set(claimIds) : null;
+  return ledger.claims.filter((claim) => !selected || selected.has(claim.id));
+}
+
+function projectReviewSource(source) {
+  const kindFields = reviewSourceFields[source.kind];
+  if (!kindFields) {
+    throw new Error(`Cannot project unknown source kind ${source.kind}`);
+  }
+  return Object.fromEntries(
+    [...commonReviewSourceFields, ...kindFields]
+      .filter((key) => Object.hasOwn(source, key))
+      .map((key) => [key, structuredClone(source[key])]),
+  );
+}
+
+function verificationBrief(input) {
+  const claims = selectedClaims(input.ledger, input.claimIds);
+  const evidenceById = new Map(
+    input.ledger.evidence.map((evidence) => [evidence.id, evidence]),
+  );
+  const sourceIds = new Set();
+  const projectedClaims = claims.map((claim) => ({
+    id: claim.id,
+    statement: claim.statement,
+    evidence: claim.evidence.map((link) => {
+      const evidence = evidenceById.get(link.evidenceId);
+      if (!evidence) {
+        throw new Error(
+          `Claim ${claim.id} references missing evidence ${link.evidenceId}`,
+        );
+      }
+      sourceIds.add(evidence.sourceId);
+      return {
+        id: evidence.id,
+        sourceId: evidence.sourceId,
+        displayExcerpt: evidence.displayExcerpt,
+        locator: structuredClone(evidence.locator),
+      };
+    }),
+  }));
+  const declaredSourceIds = new Set(
+    input.manifest.sources.map((source) => source.id),
+  );
+  for (const sourceId of sourceIds) {
+    if (!declaredSourceIds.has(sourceId)) {
+      throw new Error(`Evidence references missing source ${sourceId}`);
+    }
+  }
+  return {
+    kind: 'recon.review-brief',
+    schemaVersion: 1,
+    id: input.id,
+    runId: input.manifest.run.id,
+    mode: 'verify',
+    createdAt: input.createdAt,
+    excludedInputs: [
+      'worker_intermediates',
+      'prior_reasoning',
+      'consumer_summary',
+      'artifact_lineage',
+      'earlier_reviews',
+    ],
+    claims: projectedClaims,
+    sources: input.manifest.sources
+      .filter((source) => sourceIds.has(source.id))
+      .map(projectReviewSource),
+  };
+}
+
+function adversarialBrief(input) {
+  return {
+    kind: 'recon.review-brief',
+    schemaVersion: 1,
+    id: input.id,
+    runId: input.manifest.run.id,
+    mode: 'adversary',
+    createdAt: input.createdAt,
+    excludedInputs: [
+      'worker_intermediates',
+      'prior_reasoning',
+      'consumer_summary',
+      'artifact_lineage',
+      'earlier_reviews',
+      'verification_conclusions',
+    ],
+    scope: {
+      included: structuredClone(input.manifest.request.includedScope ?? []),
+      excluded: structuredClone(input.manifest.request.excludedScope ?? []),
+    },
+    questions: structuredClone(input.manifest.request.questions ?? []),
+    provisionalStatements: selectedClaims(input.ledger, input.claimIds).map(
+      (claim) => ({ id: claim.id, statement: claim.statement }),
+    ),
+  };
+}
+
+function coverageBrief(input) {
+  return {
+    kind: 'recon.review-brief',
+    schemaVersion: 1,
+    id: input.id,
+    runId: input.manifest.run.id,
+    mode: 'coverage',
+    createdAt: input.createdAt,
+    excludedInputs: [
+      'worker_intermediates',
+      'prior_reasoning',
+      'consumer_summary',
+      'artifact_lineage',
+      'earlier_reviews',
+      'verification_conclusions',
+      'adversarial_conclusions',
+    ],
+    scope: {
+      included: structuredClone(input.manifest.request.includedScope ?? []),
+      excluded: structuredClone(input.manifest.request.excludedScope ?? []),
+    },
+    questions: structuredClone(input.manifest.request.questions ?? []),
+    claims: selectedClaims(input.ledger, input.claimIds).map((claim) => ({
+      id: claim.id,
+      statement: claim.statement,
+    })),
+  };
+}
+
+export function createReviewBrief(input) {
+  if (!['verify', 'adversary', 'coverage'].includes(input.mode)) {
+    throw new Error(`Unsupported review brief mode: ${input.mode}`);
+  }
+  if (!input.id || !input.createdAt || !input.manifest || !input.ledger) {
+    throw new Error(
+      'Review brief requires id, createdAt, manifest, and ledger',
+    );
+  }
+  const brief =
+    input.mode === 'verify'
+      ? verificationBrief(input)
+      : input.mode === 'adversary'
+        ? adversarialBrief(input)
+        : coverageBrief(input);
+  const result = validateReviewBrief(brief);
+  if (!result.valid) {
+    throw new Error(
+      `Review brief violates selective blindness: ${result.errors[0].message}`,
+    );
+  }
+  return brief;
+}
+
+function inspectForbidden(value, path, errors) {
+  if (typeof value === 'string') {
+    if (/raw[\\/]dossiers/i.test(value)) {
+      errors.push(
+        issue('BLINDNESS_VIOLATION', 'Raw dossier paths are forbidden', path),
+      );
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) =>
+      inspectForbidden(item, `${path}[${index}]`, errors),
+    );
+    return;
+  }
+  if (!isObject(value)) return;
+  for (const [key, item] of Object.entries(value)) {
+    if (forbiddenKeys.has(key)) {
+      errors.push(
+        issue(
+          'BLINDNESS_VIOLATION',
+          `Forbidden field ${key}`,
+          `${path}.${key}`,
+        ),
+      );
+    }
+    inspectForbidden(item, `${path}.${key}`, errors);
+  }
+}
+
+export function validateReviewBrief(brief) {
+  const errors = [];
+  if (
+    !isObject(brief) ||
+    brief.kind !== 'recon.review-brief' ||
+    brief.schemaVersion !== 1
+  ) {
+    errors.push(
+      issue('INVALID_REVIEW_BRIEF', 'Expected recon.review-brief version 1'),
+    );
+    return { valid: false, errors };
+  }
+  const allowed = allowedKeys[brief.mode];
+  if (!allowed) {
+    errors.push(
+      issue(
+        'INVALID_REVIEW_MODE',
+        'Review mode must be verify, adversary, or coverage',
+        '$.mode',
+      ),
+    );
+    return { valid: false, errors };
+  }
+  for (const key of Object.keys(brief)) {
+    if (!allowed.has(key)) {
+      errors.push(
+        issue(
+          'BLINDNESS_VIOLATION',
+          `Unexpected top-level field ${key}`,
+          `$.${key}`,
+        ),
+      );
+    }
+  }
+  inspectForbidden(brief, '$', errors);
+  if (brief.mode === 'verify') {
+    if (!Array.isArray(brief.claims) || !Array.isArray(brief.sources)) {
+      errors.push(
+        issue(
+          'INVALID_REVIEW_BRIEF',
+          'Verification brief needs claims and sources',
+        ),
+      );
+    }
+    for (const [index, claim] of (brief.claims ?? []).entries()) {
+      const keys = Object.keys(claim).sort();
+      if (keys.join(',') !== 'evidence,id,statement') {
+        errors.push(
+          issue(
+            'BLINDNESS_VIOLATION',
+            'Verification claims have an invalid projection',
+            `$.claims[${index}]`,
+          ),
+        );
+      }
+      for (const [evidenceIndex, evidence] of (
+        claim.evidence ?? []
+      ).entries()) {
+        const evidenceKeys = Object.keys(evidence).sort();
+        if (evidenceKeys.join(',') !== 'displayExcerpt,id,locator,sourceId') {
+          errors.push(
+            issue(
+              'BLINDNESS_VIOLATION',
+              'Verification evidence has an invalid projection',
+              `$.claims[${index}].evidence[${evidenceIndex}]`,
+            ),
+          );
+        }
+      }
+    }
+  } else if (brief.mode === 'adversary') {
+    if (
+      !Array.isArray(brief.questions) ||
+      !Array.isArray(brief.provisionalStatements) ||
+      !isObject(brief.scope)
+    ) {
+      errors.push(
+        issue(
+          'INVALID_REVIEW_BRIEF',
+          'Adversarial brief needs scope, questions, and provisional statements',
+        ),
+      );
+    }
+    for (const [index, statement] of (
+      brief.provisionalStatements ?? []
+    ).entries()) {
+      if (
+        !isObject(statement) ||
+        Object.keys(statement).sort().join(',') !== 'id,statement'
+      ) {
+        errors.push(
+          issue(
+            'BLINDNESS_VIOLATION',
+            'Adversarial statements have an invalid projection',
+            `$.provisionalStatements[${index}]`,
+          ),
+        );
+      }
+    }
+  } else if (brief.mode === 'coverage') {
+    if (
+      !Array.isArray(brief.questions) ||
+      !Array.isArray(brief.claims) ||
+      !isObject(brief.scope)
+    ) {
+      errors.push(
+        issue(
+          'INVALID_REVIEW_BRIEF',
+          'Coverage brief needs scope, questions, and claims',
+        ),
+      );
+    }
+    for (const [index, claim] of (brief.claims ?? []).entries()) {
+      if (Object.keys(claim).sort().join(',') !== 'id,statement') {
+        errors.push(
+          issue(
+            'BLINDNESS_VIOLATION',
+            'Coverage claims have an invalid projection',
+            `$.claims[${index}]`,
+          ),
+        );
+      }
+    }
+  }
+  errors.push(...validateArtifactShape(brief).errors);
+  return { valid: errors.length === 0, errors };
+}
+
+export async function writeReviewBrief({ packetRoot, outputPath, brief }) {
+  const root = resolve(packetRoot);
+  const target = resolve(outputPath);
+  await assertSafeOutputPath(root, target);
+  const result = validateReviewBrief(brief);
+  if (!result.valid) {
+    throw new Error(
+      `Review brief violates selective blindness: ${result.errors[0].message}`,
+    );
+  }
+  await mkdir(dirname(target), { recursive: true });
+  try {
+    await writeFile(target, `${canonicalJson(brief)}\n`, {
+      encoding: 'utf8',
+      flag: 'wx',
+    });
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'EEXIST') {
+      throw new Error(`Review brief already exists: ${target}`, {
+        cause: error,
+      });
+    }
+    throw error;
+  }
+  return { path: relative(root, target), digest: await hashFile(target) };
+}
+
+async function main(argv) {
+  const options = Object.fromEntries(
+    argv.reduce((pairs, value, index) => {
+      if (value.startsWith('--')) pairs.push([value.slice(2), argv[index + 1]]);
+      return pairs;
+    }, []),
+  );
+  for (const key of [
+    'mode',
+    'id',
+    'created-at',
+    'manifest',
+    'ledger',
+    'output',
+    'packet-root',
+  ]) {
+    if (!options[key]) throw new Error(`Missing --${key}`);
+  }
+  const [manifest, ledger] = await Promise.all([
+    readFile(options.manifest, 'utf8').then(JSON.parse),
+    readFile(options.ledger, 'utf8').then(JSON.parse),
+  ]);
+  const brief = createReviewBrief({
+    mode: options.mode,
+    id: options.id,
+    createdAt: options['created-at'],
+    manifest,
+    ledger,
+  });
+  const reference = await writeReviewBrief({
+    packetRoot: options['packet-root'],
+    outputPath: options.output,
+    brief,
+  });
+  process.stdout.write(`${JSON.stringify(reference, null, 2)}\n`);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
+    process.exitCode = 1;
+  });
+}

package/assets/skills/recon/scripts/lib/canonical-json.mjs

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+function canonicalize(value, seen) {
+  if (
+    value === null ||
+    typeof value === 'boolean' ||
+    typeof value === 'string'
+  ) {
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new TypeError('Canonical JSON cannot encode non-finite numbers');
+    }
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => canonicalize(item, seen)).join(',')}]`;
+  }
+  if (typeof value !== 'object' || value === undefined) {
+    throw new TypeError(`Canonical JSON cannot encode ${typeof value}`);
+  }
+  if (seen.has(value)) {
+    throw new TypeError('Canonical JSON cannot encode cyclic values');
+  }
+  seen.add(value);
+  const entries = Object.keys(value)
+    .sort()
+    .map((key) => {
+      const item = value[key];
+      if (item === undefined) {
+        throw new TypeError(`Canonical JSON cannot encode undefined at ${key}`);
+      }
+      return `${JSON.stringify(key)}:${canonicalize(item, seen)}`;
+    });
+  seen.delete(value);
+  return `{${entries.join(',')}}`;
+}
+
+export function canonicalJson(value) {
+  return canonicalize(value, new Set());
+}
+
+export function sha256(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+export function hashCanonicalJson(value) {
+  return sha256(Buffer.from(canonicalJson(value), 'utf8'));
+}
+
+export async function hashFile(path) {
+  return sha256(await readFile(path));
+}