dsh-themis 1.0.0

package/src/core/install.js

@@ -0,0 +1,31 @@
+/**
+ * Install drift audit over caller-supplied listings. Pure function.
+ * Hash comparison lives in bin/install.js --check; this module does set math.
+ *
+ * @param {{version: string, files: string[]}} manifest
+ * @param {string[]} actualFiles all files present under target (relative, posix)
+ * @param {string[]} pkgFiles managed files in the current package
+ * @param {string} pkgVersion
+ * @returns {{
+ *   missingManaged: string[],
+ *   unmanaged: string[],
+ *   versionMismatch: boolean,
+ *   newInPackage: string[],
+ * }}
+ */
+export function installAudit(manifest, actualFiles, pkgFiles, pkgVersion) {
+  const managedSet = new Set(manifest?.files ?? []);
+  const actualSet = new Set(Array.isArray(actualFiles) ? actualFiles : []);
+  const isBackup = (rel) => /\.bak-\d+(?:-\d+)?$/.test(rel);
+
+  const missingManaged = (manifest?.files ?? []).filter((f) => !actualSet.has(f));
+  const unmanaged = (Array.isArray(actualFiles) ? actualFiles : []).filter((f) => !managedSet.has(f) && !isBackup(f)).sort();
+  const newInPackage = (Array.isArray(pkgFiles) ? pkgFiles : []).filter((f) => !managedSet.has(f));
+
+  return {
+    missingManaged,
+    unmanaged,
+    versionMismatch: Boolean(manifest && pkgVersion && manifest.version !== pkgVersion),
+    newInPackage,
+  };
+}

package/src/core/mutation.js

@@ -0,0 +1,53 @@
+import { errorEnvelope, okEnvelope } from './envelope.js';
+
+const list = (value) => Array.isArray(value) ? value : [];
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const clone = (value) => JSON.parse(JSON.stringify(value));
+const EXECUTABLE_OPERATIONS = new Set(['apply', 'execute', 'deploy']);
+const MARKER_PATTERN = /\b(apply|execute|deploy)\b/i;
+const scanMarkers = (value, base, depth, errors) => {
+  if (depth > 24 || errors.length > 32) return;
+  if (typeof value === 'string') {
+    if (MARKER_PATTERN.test(value)) errors.push({ path: base, code: 'CAPABILITY_DENIED', message: 'executable marker inside intent payload' });
+    return;
+  }
+  if (Array.isArray(value)) { value.forEach((item, i) => scanMarkers(item, `${base}/${i}`, depth + 1, errors)); return; }
+  if (value !== null && typeof value === 'object') {
+    for (const key of Object.keys(value)) scanMarkers(value[key], `${base}/${key}`, depth + 1, errors);
+  }
+};
+
+export function validateMutationIntent(raw) {
+  const errors = [];
+  if (!object(raw)) return { valid: false, errors: [{ path: '/', message: 'intent must be an object' }], warnings: [] };
+  if (raw.schema !== 'tech-lead.mutation-intent.v1') errors.push({ path: '/schema', message: 'invalid schema' });
+  if (raw.mode !== 'read-only-preview') errors.push({ path: '/mode', code: 'CAPABILITY_DENIED', message: 'only read-only-preview is available' });
+  if (!list(raw.target).length) errors.push({ path: '/target', message: 'at least one target is required' });
+  for (const [index, target] of list(raw.target).entries()) if (EXECUTABLE_OPERATIONS.has(target?.operation)) errors.push({ path: `/target/${index}/operation`, code: 'CAPABILITY_DENIED', message: 'executable target operations are unavailable' });
+  if (!list(raw.expectedDiff).length) errors.push({ path: '/expectedDiff', message: 'expectedDiff is required' });
+  if (!object(raw.recoveryPoint) || raw.recoveryPoint.required !== true) errors.push({ path: '/recoveryPoint', message: 'recovery point is required' });
+  if (!list(raw.verification).length) errors.push({ path: '/verification', message: 'verification is required' });
+  if (!object(raw.authorization) || raw.authorization.required !== true) errors.push({ path: '/authorization', message: 'authorization declaration is required' });
+  return { valid: errors.length === 0, errors, warnings: [] };
+}
+
+export function previewMutation(raw) {
+  if (!object(raw) || raw.mode !== 'read-only-preview') return errorEnvelope('mutation_preview', 'CAPABILITY_DENIED', [{ code: 'CAPABILITY_DENIED', message: 'mutation execution is not enabled' }]);
+  const validation = validateMutationIntent(raw);
+  if (!validation.valid) return errorEnvelope('mutation_preview', 'SCHEMA_INVALID', validation.errors, validation);
+  const markers = [];
+  for (const field of ['target', 'expectedDiff', 'verification', 'recoveryPoint', 'authorization']) scanMarkers(raw[field], `/${field}`, 0, markers);
+  if (markers.length) return errorEnvelope('mutation_preview', 'CAPABILITY_DENIED', markers);
+  try {
+    return okEnvelope('mutation_preview', {
+      execution: 'not performed',
+      mode: 'read-only-preview',
+      targets: clone(list(raw.target)),
+      expectedDiff: clone(list(raw.expectedDiff)),
+      verification: clone(list(raw.verification)),
+      authorization: clone(raw.authorization),
+    });
+  } catch {
+    return errorEnvelope('mutation_preview', 'SERIALIZATION_FAILED', [{ code: 'SERIALIZATION_FAILED', path: '/', message: 'intent payload is not serializable for preview' }]);
+  }
+}

package/src/core/plan.js

@@ -0,0 +1,62 @@
+/**
+ * Plan completeness lint (SKILL §3.1 goal ledger + assumption/decision/risk/
+ * dependency contracts). Pure function.
+ *
+ * @param {Record<string, unknown>} plan
+ * @returns {Array<{severity:'error'|'warning', path:string, message:string}>}
+ */
+export function planLint(plan) {
+  if (plan === null || typeof plan !== 'object' || Array.isArray(plan)) {
+    return [{ severity: 'error', path: 'plan', message: 'plan must be an object' }];
+  }
+  /** @type {Array<{severity:'error'|'warning', path:string, message:string}>} */
+  const f = [];
+  const reqStr = (obj, key) => typeof obj[key] === 'string' && !!obj[key].trim();
+
+  if (!reqStr(plan, 'goal')) {
+    f.push({ severity: 'error', path: 'goal', message: 'required non-empty goal' });
+  } else {
+    if (!reqStr(plan, 'metric')) f.push({ severity: 'error', path: 'metric', message: 'goal needs a measurable metric' });
+    if (!reqStr(plan, 'target')) f.push({ severity: 'error', path: 'target', message: 'goal needs a target value' });
+  }
+
+  for (const [i, item] of objectItemsOrGap(plan.assumptions, 'assumptions', f)) {
+    if (!reqStr(item, 'verification')) {
+      f.push({ severity: 'error', path: `assumptions[${i}].verification`, message: 'assumption needs a verification method' });
+    }
+  }
+  for (const [i, item] of objectItemsOrGap(plan.decisions, 'decisions', f)) {
+    if (!hasAlternatives(item)) f.push({ severity: 'error', path: `decisions[${i}].alternatives`, message: 'decision must record rejected alternatives' });
+    if (!reqStr(item, 'reason')) f.push({ severity: 'error', path: `decisions[${i}].reason`, message: 'decision must record its reason' });
+  }
+  for (const [i, item] of objectItemsOrGap(plan.risks, 'risks', f)) {
+    if (!reqStr(item, 'impact')) f.push({ severity: 'error', path: `risks[${i}].impact`, message: 'risk needs impact' });
+    if (!reqStr(item, 'mitigation')) f.push({ severity: 'error', path: `risks[${i}].mitigation`, message: 'risk needs mitigation' });
+  }
+  for (const [i, item] of objectItemsOrGap(plan.dependencies, 'dependencies', f)) {
+    if (!reqStr(item, 'blocker')) f.push({ severity: 'error', path: `dependencies[${i}].blocker`, message: 'dependency needs its blocking relation / alternative path' });
+  }
+
+  const irreversible = Array.isArray(plan.irreversibleOps) ? plan.irreversibleOps : [];
+  if (irreversible.length && !reqStr(plan, 'rollback')) {
+    f.push({ severity: 'error', path: 'rollback', message: 'irreversible operations require a rollback plan' });
+  }
+
+  return f;
+}
+
+function objectItemsOrGap(arr, name, findings) {
+  const out = [];
+  if (!Array.isArray(arr)) return out;
+  arr.forEach((item, i) => {
+    if (item !== null && typeof item === 'object' && !Array.isArray(item)) out.push([i, item]);
+    else findings.push({ severity: 'error', path: `${name}[${i}]`, message: 'must be an object ({claim,...}, {choice,...}, {description,...}, {what,...})' });
+  });
+  return out;
+}
+
+function hasAlternatives(item) {
+  const a = item.alternatives;
+  if (typeof a === 'string') return !!a.trim();
+  return Array.isArray(a) && a.length > 0;
+}

package/src/core/progress.js

@@ -0,0 +1,20 @@
+const list = (value) => Array.isArray(value) ? value : [];
+
+export function progressDecide(context, options = {}) {
+  if (!context || typeof context !== 'object' || Array.isArray(context)) return {
+    outcome: 'PAUSE', allowed: false, reasons: [{ code: 'BAD_INPUT', message: 'context must be an object' }], blockers: [], requiredActions: ['provide context'], confidence: 1,
+  };
+  options = options && typeof options === 'object' && !Array.isArray(options) ? options : {};
+  const blockers = list(context.dependencies).filter((item) => item?.blocker && item.status !== 'done').map((item) => String(item.id ?? 'unknown'));
+  const reasons = [];
+  const stale = list(context.evidence).filter((item) => item?.stale).map((item) => String(item.id ?? 'unknown'));
+  if (stale.length) reasons.push({ code: 'STALE_EVIDENCE', evidence: stale });
+  if (blockers.length) reasons.push({ code: 'DEPENDENCY_BLOCKED', dependencies: blockers });
+  const destructiveGate = list(context.gates).some((item) => item?.destructive && item.status !== 'pass');
+  if (destructiveGate) reasons.push({ code: 'GATE_BLOCKED', message: 'destructive gate is not passed' });
+  if (stale.length || blockers.length || destructiveGate) return {
+    outcome: 'PAUSE', allowed: false, reasons, blockers, requiredActions: ['resolve blockers and refresh evidence'], confidence: 1,
+  };
+  if (options.forcePivot === true) return { outcome: 'PIVOT', allowed: false, reasons: [{ code: 'PIVOT_REQUESTED' }], blockers: [], requiredActions: ['record decision'], confidence: 0.8 };
+  return { outcome: 'CONTINUE', allowed: true, reasons: [{ code: 'NO_BLOCKER' }], blockers: [], requiredActions: [], confidence: 0.7 };
+}

package/src/core/release.js

@@ -0,0 +1,57 @@
+/**
+ * Release audit (SKILL §11 INVENTORY/CONTENT-SCAN, mechanical subset).
+ * Pure function: regex scan over provided content only — no filesystem access.
+ *
+ * @param {{
+ *   allowlist: string[],
+ *   files: Array<{path: string, content?: string}>,
+ *   contentScan?: boolean,
+ * }} input
+ * @returns {Array<{type:string, path:string, line:number, detail:string}>}
+ */
+export function releaseAudit(input = {}) {
+  /** @type {Array<{type:string, path:string, line:number, detail:string}>} */
+  const v = [];
+  if (input === null || typeof input !== 'object' || !Array.isArray(input.files)) {
+    return [{ type: 'BAD_INPUT', path: '', line: 0, detail: 'releaseAudit expects {allowlist[], files[]}' }];
+  }
+  const allowlist = new Set(input.allowlist ?? []);
+  const contentScan = input.contentScan !== false;
+
+  for (const file of input.files) {
+    if (file === null || typeof file !== 'object' || typeof file.path !== 'string') {
+      v.push({ type: 'BAD_ENTRY', path: '', line: 0, detail: 'files[] entries must be objects with a path' });
+      continue;
+    }
+    if (!allowlist.has(file.path)) {
+      v.push({ type: 'EXTRA_FILE', path: file.path, line: 0, detail: 'not in release allowlist' });
+    }
+    if (!contentScan) continue;
+    if (typeof file.content !== 'string') {
+      v.push({ type: 'UNSCANNED', path: file.path, line: 0, detail: 'no content provided; file was NOT leak-scanned' });
+      continue;
+    }
+
+    const lines = file.content.split('\n');
+    lines.forEach((line, idx) => {
+      if (ABS_PATH_RE.test(line)) {
+        push(v, 'ABS_PATH', file.path, idx + 1, 'absolute home/user path');
+      } else {
+        const tok = line.match(TOKEN_RE);
+        if (tok) push(v, 'TOKEN_SUSPECT', file.path, idx + 1, `token-like literal (${tok[0].slice(0, 6)}…)`);
+        const cred = line.match(CRED_LINE_RE);
+        if (cred) push(v, 'CREDENTIAL_LINE', file.path, idx + 1, 'credential assignment');
+      }
+    });
+  }
+  return v;
+}
+
+const ABS_PATH_RE =
+  /(\/data\/data\/com\.termux|\/Users\/[A-Za-z0-9_.-]+|\/home\/[A-Za-z0-9_.-]+|\/root(?:\/[^\s'"]*)?|C:\\+Users\\+[A-Za-z0-9_.-]+)/i;
+const TOKEN_RE = /\b(sk-[A-Za-z0-9][A-Za-z0-9-]{7,}|gh[pousr]_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|ASIA[0-9A-Z]{16}|AIza[A-Za-z0-9_-]{10,}|xox[baprs]-[A-Za-z0-9-]{10,})/;
+const CRED_LINE_RE = /\b(bearer\s+[A-Za-z0-9._-]{10,}|(password|passwd|pwd|secret|api[_-]?key|token)\s*[=:]\s*['"]?[^\s'\"]{6,})/i;
+
+function push(arr, type, path, line, detail) {
+  arr.push({ type, path, line, detail });
+}

package/src/core/resume.js

@@ -0,0 +1,73 @@
+/**
+ * Resume card renderer (SKILL §7). Pure function.
+ *
+ * @param {Record<string, unknown>} state validated-ish tech-lead state object
+ * @param {{ now?: string, maxAgeDays?: number }} [opts]
+ * @returns {{
+ *   position: string,
+ *   lastGate: string,
+ *   nextStep: string,
+ *   staleEvidenceIds: string[],
+ *   warnings: string[],
+ * }}
+ */
+export function resumeCard(maybeState, maybeOpts = {}) {
+  const opts = maybeOpts !== null && typeof maybeOpts === 'object' && !Array.isArray(maybeOpts) ? maybeOpts : {};
+  const warnings = [];
+  const state = maybeState !== null && typeof maybeState === 'object' ? maybeState : {};
+  if (maybeState === null || typeof maybeState !== 'object') {
+    warnings.push('state is missing or not an object; card rendered from defaults');
+  }
+  const tier = String(state.tier ?? '?');
+  const phase = String(state.phase ?? '?');
+  const mode = String(state.mode ?? '?');
+
+  const nextStep = typeof state.next_step === 'string' && state.next_step.trim()
+    ? state.next_step
+    : '(empty — set next_step before resuming)';
+  if (!(typeof state.next_step === 'string' && state.next_step.trim())) {
+    warnings.push('next_step is empty; set it before resuming');
+  }
+
+  if (Array.isArray(state.open_gates) && state.open_gates.length) {
+    warnings.push(`open gates pending: ${state.open_gates.slice(0, 20).join(', ')}${state.open_gates.length > 20 ? ` …+${state.open_gates.length - 20} more` : ''}`);
+  }
+
+  const staleEvidenceIds = [];
+  let nowMs = Date.now();
+  if (opts.now) {
+    const parsed = Date.parse(opts.now);
+    if (Number.isFinite(parsed)) nowMs = parsed;
+    else warnings.push('opts.now is not a parseable time; using current clock');
+  }
+  let maxAgeDays = 7;
+  if (opts.maxAgeDays !== undefined) {
+    const n = Number(opts.maxAgeDays);
+    if (typeof opts.maxAgeDays === 'number' && Number.isFinite(n) && n >= 0) maxAgeDays = n;
+    else warnings.push('maxAgeDays must be a finite number >= 0; using default 7');
+  }
+  if (Number.isFinite(nowMs) && Array.isArray(state.evidence)) {
+    for (const e of state.evidence) {
+      if (!e || typeof e !== 'object') continue;
+      const t = Date.parse(String(e.time ?? ''));
+      if (!Number.isFinite(t)) {
+        warnings.push(`evidence ${String(e.id ?? '?')} has unparseable time; excluded from staleness check`);
+        continue;
+      }
+      if (t > nowMs || nowMs - t > maxAgeDays * 86400_000) {
+        staleEvidenceIds.push(String(e.id));
+      }
+    }
+  }
+  if (staleEvidenceIds.length) {
+    warnings.push(`stale evidence (> ${maxAgeDays}d): ${staleEvidenceIds.slice(0, 20).join(', ')}${staleEvidenceIds.length > 20 ? ` …+${staleEvidenceIds.length - 20} more` : ''}`);
+  }
+
+  return {
+    position: `[${tier}] ${phase} · mode=${mode}`,
+    lastGate: String(state.last_outcome ?? '') || 'none',
+    nextStep,
+    staleEvidenceIds,
+    warnings,
+  };
+}

package/src/core/state.js

@@ -0,0 +1,123 @@
+/**
+ * Machine-checkable validation for tech-lead state.json (schema v1).
+ * Pure function: no I/O, throws only on programmer error.
+ *
+ * @param {unknown} raw parsed JSON value
+ * @returns {{
+ *   valid: boolean,
+ *   errors: Array<{path: string, message: string}>,
+ *   warnings: Array<{path: string, message: string}>,
+ *   unknownFields: string[],
+ * }}
+ */
+export function validateState(raw) {
+  const errors = [];
+  const warnings = [];
+  const unknownFields = [];
+
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return {
+      valid: false,
+      errors: [{ path: '', message: 'state must be a JSON object' }],
+      warnings,
+      unknownFields,
+    };
+  }
+
+  const s = /** @type {Record<string, unknown>} */ (raw);
+
+  const KNOWN_FIELDS = new Set([
+    'schema_version', 'mode', 'tier', 'phase', 'repository_mode',
+    'state_persistence', 'done', 'open_gates', 'goal_ledger', 'constraints',
+    'decisions', 'risks', 'dependencies', 'evidence', 'critical_path',
+    'protected_assets', 'hypotheses', 'assumptions', 'last_outcome',
+    'next_review_trigger', 'degraded_reason', 'tags', 'next_step', 'updated_at',
+  ]);
+  for (const key of Object.keys(s)) {
+    if (!KNOWN_FIELDS.has(key)) unknownFields.push(key);
+  }
+  for (const key of unknownFields) {
+    warnings.push({ path: key, message: 'unknown field preserved (schema v1 does not define it)' });
+  }
+
+  // schema_version: number 1 or legacy string "1"
+  if (s.schema_version !== 1 && s.schema_version !== '1') {
+    errors.push({ path: 'schema_version', message: "must be 1 (number) or \"1\" (legacy)" });
+  }
+
+  requireEnum(s, 'mode', ['PLAN', 'EXECUTE'], errors);
+  requireEnum(s, 'tier', ['T0', 'T1', 'T2'], errors);
+  requireEnum(s, 'repository_mode', ['git', 'non-git', 'read-only'], errors);
+  optionalEnum(s, 'state_persistence', ['available', 'unavailable'], errors);
+  optionalEnum(s, 'last_outcome',
+    ['', 'CONTINUE', 'PAUSE', 'SCOPE-DOWN', 'PIVOT', 'STOP'], errors);
+
+  requireNonEmptyString(s, 'phase', errors);
+  requireNonEmptyString(s, 'updated_at', errors);
+
+  // done[]: each entry needs item + non-empty anchor
+  if (Array.isArray(s.done)) {
+    s.done.forEach((entry, i) => {
+      if (entry === null || typeof entry !== 'object') {
+        errors.push({ path: `done[${i}]`, message: 'must be an object' });
+        return;
+      }
+      const e = /** @type {Record<string, unknown>} */ (entry);
+      if (typeof e.item !== 'string' || !e.item.trim()) {
+        errors.push({ path: `done[${i}].item`, message: 'required non-empty string' });
+      }
+      if (typeof e.anchor !== 'string' || !e.anchor.trim()) {
+        errors.push({ path: `done[${i}].anchor`, message: 'required non-empty anchor (commit/tag/file:line)' });
+      }
+    });
+  } else if (s.done !== undefined) {
+    errors.push({ path: 'done', message: 'must be an array' });
+  }
+
+  // evidence[]: full provenance + bounded level
+  if (Array.isArray(s.evidence)) {
+    const LEVELS = new Set(['E0', 'E1', 'E2', 'E3', 'E4']);
+    const REQUIRED = ['id', 'level', 'source', 'time', 'scope', 'repro'];
+    s.evidence.forEach((entry, i) => {
+      if (entry === null || typeof entry !== 'object') {
+        errors.push({ path: `evidence[${i}]`, message: 'must be an object' });
+        return;
+      }
+      const e = /** @type {Record<string, unknown>} */ (entry);
+      for (const field of REQUIRED) {
+        const v = e[field];
+        if (typeof v !== 'string' || !v.trim()) {
+          errors.push({ path: `evidence[${i}].${field}`, message: 'required non-empty string' });
+        }
+      }
+      if (typeof e.level === 'string' && !LEVELS.has(e.level)) {
+        errors.push({ path: `evidence[${i}].level`, message: 'must be one of E0,E1,E2,E3,E4' });
+      }
+    });
+  } else if (s.evidence !== undefined) {
+    errors.push({ path: 'evidence', message: 'must be an array' });
+  }
+
+  return { valid: errors.length === 0, errors, warnings, unknownFields };
+}
+
+function requireEnum(obj, key, values, errors) {
+  const v = obj[key];
+  if (!values.includes(v)) {
+    errors.push({ path: key, message: `must be one of ${values.join('|')}` });
+  }
+}
+
+function optionalEnum(obj, key, values, errors) {
+  const v = obj[key];
+  if (v !== undefined && !values.includes(v)) {
+    errors.push({ path: key, message: `must be one of ${values.join('|')} (or omitted)` });
+  }
+}
+
+function requireNonEmptyString(obj, key, errors) {
+  const v = obj[key];
+  if (typeof v !== 'string' || !v.trim()) {
+    errors.push({ path: key, message: 'required non-empty string' });
+  }
+}

package/src/core/transition.js

@@ -0,0 +1,42 @@
+const OUTCOMES = ['CONTINUE', 'PAUSE', 'SCOPE-DOWN', 'PIVOT', 'STOP'];
+
+/**
+ * Mechanical outcome-transition check (SKILL §4.8 subset). Pure function.
+ *
+ * @param {Record<string, unknown>} state tech-lead state object
+ * @param {string} proposed proposed last_outcome
+ * @returns {{ allowed: boolean, reason: string }}
+ */
+export function transitionCheck(state, proposed) {
+  if (!OUTCOMES.includes(proposed)) {
+    return { allowed: false, reason: `proposed must be one of ${OUTCOMES.join('|')}` };
+  }
+  if (proposed === 'CONTINUE') {
+    return { allowed: true, reason: 'CONTINUE is always available when evidence supports the next step' };
+  }
+
+  const arr = (k) => (Array.isArray(state?.[k]) ? state[k] : []);
+  const decisions = arr('decisions');
+  const goalLedger = arr('goal_ledger');
+  const risks = arr('risks');
+  const done = arr('done');
+  const degraded = typeof state?.degraded_reason === 'string' && !!state.degraded_reason.trim();
+
+  if (proposed === 'PIVOT') {
+    return decisions.length > 0
+      ? { allowed: true, reason: 'PIVOT requires a falsified recorded decision; decisions ledger present' }
+      : { allowed: false, reason: 'PIVOT requires at least one recorded decision being falsified (decisions[] empty)' };
+  }
+  if (proposed === 'SCOPE-DOWN') {
+    return goalLedger.length > 0 && risks.length > 0
+      ? { allowed: true, reason: 'SCOPE-DOWN rewrites goal/DoD; ledger and risks present' }
+      : { allowed: false, reason: 'SCOPE-DOWN requires non-empty goal_ledger[] and risks[]' };
+  }
+  if (proposed === 'STOP') {
+    return done.length > 0 || degraded
+      ? { allowed: true, reason: done.length ? 'STOP backed by completed anchored items' : 'STOP justified via degraded_reason' }
+      : { allowed: false, reason: 'STOP requires achieved anchored items or a degraded_reason justification' };
+  }
+  // PAUSE
+  return { allowed: true, reason: 'PAUSE halts side effects and preserves resume conditions' };
+}

package/src/index.js

@@ -0,0 +1,33 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import {
+  classify, validateState, transitionCheck,
+  evidenceLint, planLint, gatePrecheck,
+  releaseAudit, installAudit, resumeCard,
+  getCapabilities,
+  validateContext, evidenceGraphLint, evidenceFreshness,
+  progressDecide, criticalPath, changeImpact,
+  gatePlan, gateAggregate, gateReopen, previewMutation,
+} from './core/index.js';
+import { registerTools } from './tools.js';
+
+export const name = 'tech-lead-tools';
+export const inject = ['tools'];
+export { getCapabilities };
+
+/**
+ * Registers the read-only tech-lead tool surface. Every tool computes over
+ * caller-supplied JSON — no filesystem writes, no subprocesses, no network.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ */
+export function apply(ctx) {
+  for (const tool of registerTools(defineTool, {
+    classify, validateState, transitionCheck,
+    evidenceLint, planLint, gatePrecheck,
+    releaseAudit, installAudit, resumeCard,
+    validateContext, evidenceGraphLint, evidenceFreshness,
+    progressDecide, criticalPath, changeImpact,
+    gatePlan, gateAggregate, gateReopen, previewMutation,
+  })) {
+    ctx.tools.register(tool);
+  }
+}

package/src/protocol.js

@@ -0,0 +1,119 @@
+import { errorEnvelope } from './core/index.js';
+
+export function parseJsonString(value, path = 'input') {
+  if (typeof value !== 'string') {
+    return { ok: false, error: { code: 'BAD_INPUT', path, message: 'expected JSON text string' } };
+  }
+  try {
+    return { ok: true, value: JSON.parse(value) };
+  } catch (error) {
+    return { ok: false, error: { code: 'BAD_INPUT', path, message: `invalid JSON: ${error.message}` } };
+  }
+}
+
+export function parseJsonFields(args, fields) {
+  const values = {};
+  const errors = [];
+  for (const field of fields) {
+    const result = parseJsonString(args?.[field], field);
+    if (result.ok) values[field] = result.value;
+    else errors.push(result.error);
+  }
+  return errors.length ? { ok: false, errors } : { ok: true, values };
+}
+
+const FINDINGS_LIMIT = 500;
+const ECHO_LIMIT = 100;
+const RESULT_ARRAY_LIMIT = 1000;
+const WALK_DEPTH_LIMIT = 64;
+const COMPACT_THRESHOLD = 262144;
+const ECHO_KEYS = new Set(['evidence', 'targets', 'expectedDiff', 'verification', 'items']);
+
+export function clampEnvelope(envelope) {
+  if (Array.isArray(envelope)) return envelope.length > FINDINGS_LIMIT ? envelope.slice(0, FINDINGS_LIMIT) : envelope;
+  if (envelope === null || typeof envelope !== 'object') return envelope;
+  const out = { ...envelope };
+  let truncatedTotal = 0;
+  for (const field of ['errors', 'warnings']) {
+    if (Array.isArray(out[field]) && out[field].length > FINDINGS_LIMIT) {
+      truncatedTotal = Math.max(truncatedTotal, out[field].length);
+      out[field] = out[field].slice(0, FINDINGS_LIMIT);
+    }
+  }
+  if (truncatedTotal > 0) {
+    out.warnings = [...(out.warnings ?? []), { code: 'FINDINGS_TRUNCATED', total: truncatedTotal, message: `output truncated to first ${FINDINGS_LIMIT} entries per findings field` }];
+  }
+  if (out.data !== null && typeof out.data === 'object') {
+    out.data = clampNode(out.data, 0);
+  }
+  return out;
+}
+
+// Iterative walk with a hard depth cap: subtrees deeper than WALK_DEPTH_LIMIT are
+// passed through untouched (native JSON serialization handles arbitrary depth),
+// so hostile nesting can no longer turn the renderer into an INTERNAL error.
+function clampNode(root, rootDepth) {
+  const result = Array.isArray(root) ? [...root] : { ...root };
+  const stack = [[result, rootDepth]];
+  while (stack.length) {
+    const [node, depth] = stack.pop();
+    const entries = Object.keys(node);
+    for (const key of entries) {
+      const value = node[key];
+      if (!value || typeof value !== 'object') continue;
+      if (depth + 1 > WALK_DEPTH_LIMIT) {
+        node[key] = { truncated: true, reason: 'DEPTH_LIMIT', depth: WALK_DEPTH_LIMIT };
+        continue;
+      }
+      if (Array.isArray(value)) {
+        if (ECHO_KEYS.has(key) && value.length > ECHO_LIMIT) {
+          node[key] = { truncated: true, total: value.length };
+        } else if (value.length > RESULT_ARRAY_LIMIT) {
+          node[key] = value.slice(0, RESULT_ARRAY_LIMIT);
+        } else {
+          node[key] = [...value];
+          stack.push([node[key], depth + 1]);
+        }
+      } else {
+        node[key] = { ...value };
+        stack.push([node[key], depth + 1]);
+      }
+    }
+  }
+  return result;
+}
+
+export function canonicalStringify(value) {
+  return canonicalize(value, 0);
+}
+
+function canonicalize(value, depth) {
+  if (depth > WALK_DEPTH_LIMIT) return null; // deep subtrees compare as equal; drift beyond the cap is unreported by design
+  if (Array.isArray(value)) return value.map((item) => canonicalize(item, depth + 1));
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key], depth + 1)]));
+  }
+  return value;
+}
+
+export function runGuarded(operation, fn) {
+  try {
+    return fn();
+  } catch (error) {
+    return JSON.stringify(
+      errorEnvelope(operation, 'INTERNAL', [{ code: 'INTERNAL', message: `${error?.name ?? 'Error'}: unexpected internal failure` }]),
+      null,
+      2,
+    );
+  }
+}
+
+export function csv(value) {
+  return String(value ?? '').split(',').map((item) => item.trim()).filter(Boolean);
+}
+
+export function renderEnvelope(value) {
+  const clamped = clampEnvelope(value);
+  const pretty = JSON.stringify(clamped, null, 2);
+  return pretty.length > COMPACT_THRESHOLD ? JSON.stringify(clamped) : pretty;
+}