@240xu/dsh-tech-lead-plugin 0.3.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@240xu/dsh-tech-lead-plugin",
+  "version": "0.3.0",
+  "description": "Read-only tech-lead lifecycle tools for DeepSeek Harness (classify, validate, lint, audit)",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/240xu/tech-lead-skill.git",
+    "directory": "packages/dsh-tech-lead-plugin"
+  },
+  "dependencies": {
+    "@240xu/dsh-tech-lead-core": "workspace:^",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.6",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "cordis",
+    "tech-lead",
+    "plugin",
+    "opencode"
+  ]
+}

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 '@240xu/dsh-tech-lead-core';
+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 '@240xu/dsh-tech-lead-core';
+
+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;
+}

package/src/tools/context.js

@@ -0,0 +1,94 @@
+import { errorEnvelope, okEnvelope } from '@240xu/dsh-tech-lead-core';
+import { parseJsonFields, parseJsonString, renderEnvelope, runGuarded } from '../protocol.js';
+
+export function registerContextTools(defineTool, core) {
+  const output = [];
+  output.push(defineTool({
+    name: 'tech_lead_context_validate',
+    description: 'Validate an inline tech-lead.context.v1 snapshot. Read-only and deterministic.',
+    parameters: { contextJson: { type: 'string', required: true, description: 'context snapshot JSON text' } },
+    output: { schema: { type: 'string' }, render: (_a, value) => [{ type: 'text', text: value }] },
+    async execute(args) {
+      return runGuarded('context_validate', () => {
+        const parsed = parseJsonString(args?.contextJson, 'contextJson');
+        if (!parsed.ok) return renderEnvelope(errorEnvelope('context_validate', parsed.error.code, [parsed.error]));
+        const result = core.validateContext(parsed.value);
+        if (!result.valid) {
+          const errors = result.errors.map((item) => ({ code: 'SCHEMA_INVALID', path: item.path, message: item.message }));
+          return renderEnvelope(errorEnvelope('context_validate', 'SCHEMA_INVALID', errors, result));
+        }
+        return renderEnvelope(okEnvelope('context_validate', result));
+      });
+    },
+  }));
+  output.push(defineTool({
+    name: 'tech_lead_evidence_graph_lint',
+    description: 'Check explicit evidence references against context ledgers.',
+    parameters: { contextJson: { type: 'string', required: true, description: 'context snapshot JSON text' } },
+    output: { schema: { type: 'string' }, render: (_a, value) => [{ type: 'text', text: value }] },
+    async execute(args) {
+      return runGuarded('evidence_graph_lint', () => {
+        const parsed = parseJsonString(args?.contextJson, 'contextJson');
+        if (!parsed.ok) return renderEnvelope(errorEnvelope('evidence_graph_lint', parsed.error.code, [parsed.error]));
+        const result = core.evidenceGraphLint(parsed.value);
+        return renderEnvelope(result.valid
+          ? okEnvelope('evidence_graph_lint', result)
+          : errorEnvelope('evidence_graph_lint', 'SCHEMA_INVALID', result.findings, result));
+      });
+    },
+  }));
+  output.push(defineTool({
+    name: 'tech_lead_evidence_freshness',
+    description: 'Detect stale evidence and snapshot fingerprint drift.',
+    parameters: {
+      contextJson: { type: 'string', required: true, description: 'context snapshot JSON text' },
+      optionsJson: { type: 'string', description: 'optional freshness options JSON text (provide now for deterministic runs)' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, value) => [{ type: 'text', text: value }] },
+    async execute(args) {
+      return runGuarded('evidence_freshness', () => {
+        const input = parseJsonFields(args ?? {}, ['contextJson']);
+        if (!input.ok) return renderEnvelope(errorEnvelope('evidence_freshness', 'BAD_INPUT', input.errors));
+        let options = {};
+        if (args.optionsJson != null && args.optionsJson !== '') {
+          const parsedOptions = parseJsonString(args.optionsJson, 'optionsJson');
+          if (!parsedOptions.ok) return renderEnvelope(errorEnvelope('evidence_freshness', parsedOptions.error.code, [parsedOptions.error]));
+          options = parsedOptions.value && typeof parsedOptions.value === 'object' && !Array.isArray(parsedOptions.value) ? parsedOptions.value : {};
+        }
+        const clockPinned = typeof options.now === 'string' && Number.isFinite(Date.parse(options.now));
+        const result = core.evidenceFreshness(input.values.contextJson, options);
+        const envelope = result.stale
+          ? errorEnvelope('evidence_freshness', 'STALE_EVIDENCE', result.findings, result)
+          : okEnvelope('evidence_freshness', result, result.warnings);
+        envelope.meta.deterministic = clockPinned;
+        return renderEnvelope(envelope);
+      });
+    },
+  }));
+  output.push(defineTool({
+    name: 'tech_lead_assumption_register',
+    description: 'Analyze assumptions and their verification readiness without persisting them.',
+    parameters: { contextJson: { type: 'string', required: true, description: 'context snapshot JSON text' } },
+    output: { schema: { type: 'string' }, render: (_a, value) => [{ type: 'text', text: value }] },
+    async execute(args) {
+      return runGuarded('assumption_register', () => {
+        const parsed = parseJsonString(args?.contextJson, 'contextJson');
+        if (!parsed.ok) return renderEnvelope(errorEnvelope('assumption_register', parsed.error.code, [parsed.error]));
+        const assumptions = Array.isArray(parsed.value?.assumptions) ? parsed.value.assumptions : [];
+        const items = assumptions.map((item, index) => ({
+          id: item?.id ?? `assumption-${index + 1}`,
+          status: typeof item?.verification === 'string' && item.verification.trim() ? 'verifiable' : 'missing_verification',
+          verification: item?.verification ?? null,
+          affects: Array.isArray(item?.affects) ? item.affects.slice() : [],
+        }));
+        const missing = items.filter((item) => item.status === 'missing_verification');
+        if (missing.length) {
+          const errors = missing.map((item) => ({ code: 'MISSING_VERIFICATION', path: `/assumptions/${item.id}`, message: 'assumption lacks a verification method' }));
+          return renderEnvelope(errorEnvelope('assumption_register', 'SCHEMA_INVALID', errors, { items }));
+        }
+        return renderEnvelope(okEnvelope('assumption_register', { items }));
+      });
+    },
+  }));
+  return output;
+}

package/src/tools/gates.js

@@ -0,0 +1,93 @@
+import { errorEnvelope, okEnvelope } from '@240xu/dsh-tech-lead-core';
+import { parseJsonFields, renderEnvelope, runGuarded } from '../protocol.js';
+
+const FINGERPRINT_KEYS = ['contextFingerprint', 'evidenceFingerprint', 'dependencyFingerprint', 'impactFingerprint'];
+
+export function registerGateTools(defineTool, core) {
+  const output = [];
+  const add = (definition) => output.push(defineTool({ ...definition, output: { schema: { type: 'string' }, render: (_a, value) => [{ type: 'text', text: value }] } }));
+  add({
+    name: 'tech_lead_gate_plan',
+    description: 'Generate deterministic reviewer roles, evidence minimum, quorum, and gate conditions.',
+    parameters: {
+      impactJson: { type: 'string', required: true, description: 'change impact object as JSON text ({tier?, destructive?})' },
+      contextJson: { type: 'string', required: true, description: 'context snapshot JSON text ({tier?})' },
+    },
+    async execute(args) {
+      return runGuarded('gate_plan', () => {
+        const input = parseJsonFields(args ?? {}, ['impactJson', 'contextJson']);
+        if (!input.ok) return renderEnvelope(errorEnvelope('gate_plan', 'BAD_INPUT', input.errors));
+        const errors = [];
+        for (const key of ['impactJson', 'contextJson']) {
+          const value = input.values[key];
+          if (value === null || typeof value !== 'object' || Array.isArray(value)) errors.push({ code: 'BAD_INPUT', path: key, message: 'expected JSON object' });
+        }
+        if (errors.length) return renderEnvelope(errorEnvelope('gate_plan', 'BAD_INPUT', errors));
+        return renderEnvelope(okEnvelope('gate_plan', core.gatePlan(input.values.impactJson, input.values.contextJson)));
+      });
+    },
+  });
+  add({
+    name: 'tech_lead_gate_aggregate',
+    description: 'Aggregate anchored role reports, propagate rejects, and de-duplicate findings.',
+    parameters: {
+      reportsJson: { type: 'string', required: true, description: '[{role,verdict(pass|conditional|reject),anchors:[non-empty strings],findings?[]}] as JSON text; one report per role' },
+      planJson: { type: 'string', required: true, description: '{requiredRoles:[...],quorum:<positive int>} as JSON text' },
+    },
+    async execute(args) {
+      return runGuarded('gate_aggregate', () => {
+        const input = parseJsonFields(args ?? {}, ['reportsJson', 'planJson']);
+        if (!input.ok) return renderEnvelope(errorEnvelope('gate_aggregate', 'BAD_INPUT', input.errors));
+        const errors = [];
+        if (!Array.isArray(input.values.reportsJson)) errors.push({ code: 'BAD_INPUT', path: 'reportsJson', message: 'expected JSON array' });
+        const plan = input.values.planJson;
+        if (plan === null || typeof plan !== 'object' || Array.isArray(plan)) {
+          errors.push({ code: 'BAD_INPUT', path: 'planJson', message: 'expected JSON object' });
+        } else if (!Array.isArray(plan.requiredRoles) || plan.requiredRoles.length === 0 || !Number.isInteger(plan.quorum) || plan.quorum <= 0) {
+          errors.push({ code: 'BAD_INPUT', path: 'planJson', message: 'plan needs non-empty requiredRoles and a positive integer quorum' });
+        }
+        if (errors.length) return renderEnvelope(errorEnvelope('gate_aggregate', 'BAD_INPUT', errors));
+        const result = core.gateAggregate(input.values.reportsJson, plan);
+        if (!result.pass) {
+          const conditionalCount = Array.isArray(input.values.reportsJson)
+            ? input.values.reportsJson.filter((report) => report && report.verdict === 'conditional').length
+            : 0;
+          const derived = [
+            ...result.missingRoles.map((role) => ({ code: 'MISSING_ROLE', path: `/roles/${role}`, message: `no anchored report from required role "${role}"` })),
+            ...(conditionalCount > 0 ? [{ code: 'CONDITIONAL_VERDICT', path: '/reports', message: `${conditionalCount} report(s) hold a conditional verdict` }] : []),
+            ...(result.verdict !== 'reject' && result.findings.filter((f) => f.code).length === 0 && Array.isArray(input.values.reportsJson) && input.values.reportsJson.length < plan.quorum
+              ? [{ code: 'QUORUM_UNMET', path: '/reports', message: `${input.values.reportsJson.length} of ${plan.quorum} reports present` }]
+              : []),
+          ];
+          return renderEnvelope(errorEnvelope('gate_aggregate', 'GATE_BLOCKED', [...derived, ...result.findings], result));
+        }
+        return renderEnvelope(okEnvelope('gate_aggregate', result));
+      });
+    },
+  });
+  add({
+    name: 'tech_lead_gate_reopen',
+    description: 'Detect whether a previously passed gate must reopen after snapshot drift.',
+    parameters: {
+      previousJson: { type: 'string', required: true, description: `object with at least one of: ${FINGERPRINT_KEYS.join(', ')}` },
+      currentJson: { type: 'string', required: true, description: `object with at least one of: ${FINGERPRINT_KEYS.join(', ')}` },
+    },
+    async execute(args) {
+      return runGuarded('gate_reopen', () => {
+        const input = parseJsonFields(args ?? {}, ['previousJson', 'currentJson']);
+        if (!input.ok) return renderEnvelope(errorEnvelope('gate_reopen', 'BAD_INPUT', input.errors));
+        const errors = [];
+        for (const key of ['previousJson', 'currentJson']) {
+          const value = input.values[key];
+          const usable = value !== null && typeof value === 'object' && !Array.isArray(value) && FINGERPRINT_KEYS.some((k) => value[k] !== undefined);
+          if (!usable) errors.push({ code: 'BAD_INPUT', path: key, message: `expected an object containing at least one of: ${FINGERPRINT_KEYS.join(', ')}` });
+        }
+        if (errors.length) return renderEnvelope(errorEnvelope('gate_reopen', 'BAD_INPUT', errors));
+        const result = core.gateReopen(input.values.previousJson, input.values.currentJson);
+        const reasons = result.changedInputs.map((item) => ({ code: `${item.toUpperCase()}_DRIFT`, path: `/${item}Fingerprint`, message: `${item} changed` }));
+        return renderEnvelope(result.reopen ? errorEnvelope('gate_reopen', 'DRIFT_DETECTED', reasons, result) : okEnvelope('gate_reopen', result));
+      });
+    },
+  });
+  return output;
+}

package/src/tools/mutation.js

@@ -0,0 +1,18 @@
+import { errorEnvelope, previewMutation } from '@240xu/dsh-tech-lead-core';
+import { parseJsonString, renderEnvelope, runGuarded } from '../protocol.js';
+
+export function registerMutationTools(defineTool) {
+  return [defineTool({
+    name: 'tech_lead_mutation_preview',
+    description: 'Validate and preview a MutationIntent without executing anything. Schema tech-lead.mutation-intent.v1: mode MUST be "read-only-preview"; requires target[] (each {path,operation}; operations apply/execute/deploy are denied within the bounded marker-scan depth (24 levels), expectedDiff[], recoveryPoint{required:true,...}, verification[] commands-as-inert-strings, authorization{required:true}. Returns CAPABILITY_DENIED for executable modes/markers, SERIALIZATION_FAILED for unserializable payloads.',
+    parameters: { intentJson: { type: 'string', required: true, description: 'mutation intent JSON text' } },
+    output: { schema: { type: 'string' }, render: (_a, value) => [{ type: 'text', text: value }] },
+    async execute(args) {
+      return runGuarded('mutation_preview', () => {
+        const parsed = parseJsonString(args?.intentJson, 'intentJson');
+        if (!parsed.ok) return renderEnvelope(errorEnvelope('mutation_preview', parsed.error.code, [parsed.error]));
+        return renderEnvelope(previewMutation(parsed.value));
+      });
+    },
+  })];
+}

package/src/tools/progress.js

@@ -0,0 +1,77 @@
+import { errorEnvelope, okEnvelope } from '@240xu/dsh-tech-lead-core';
+import { canonicalStringify, parseJsonFields, renderEnvelope, runGuarded } from '../protocol.js';
+
+const BLOCKING_FINDINGS = new Set(['CYCLE', 'INVALID_TASK_ID', 'DUPLICATE_TASK_ID']);
+
+export function registerProgressTools(defineTool, core) {
+  const output = [];
+  const register = (name, description, parameters, execute) => output.push(defineTool({ name, description, parameters, output: { schema: { type: 'string' }, render: (_a, value) => [{ type: 'text', text: value }] }, execute }));
+  register('tech_lead_progress_decide', 'Decide the next lifecycle outcome (CONTINUE/PAUSE/SCOPE-DOWN/PIVOT/STOP). Trigger fields: dependencies[] pauses when an entry has blocker:true and status!=="done"; evidence[] pauses when an entry has stale:true; gates[] pauses when an entry has destructive:true and status!=="pass". optionsJson supports {forcePivot:true} which returns a PIVOT decision as an error envelope (code PIVOT_REQUESTED) — ok means "no blockers", not "call failed".', {
+    contextJson: { type: 'string', required: true, description: 'context snapshot JSON text with dependencies/evidence/gates arrays' },
+    optionsJson: { type: 'string', description: 'optional JSON text ({forcePivot?:boolean})' },
+  }, async (args) => {
+    return runGuarded('progress_decide', () => {
+      const input = parseJsonFields(args ?? {}, ['contextJson']);
+      if (!input.ok) return renderEnvelope(errorEnvelope('progress_decide', 'BAD_INPUT', input.errors));
+      let options = {};
+      if (args.optionsJson != null && args.optionsJson !== '') {
+        const parsedOptions = parseJsonFields(args, ['optionsJson']);
+        if (!parsedOptions.ok) return renderEnvelope(errorEnvelope('progress_decide', 'BAD_INPUT', parsedOptions.errors));
+        options = parsedOptions.values.optionsJson;
+      }
+      const result = core.progressDecide(input.values.contextJson, options);
+      return renderEnvelope(result.outcome === 'CONTINUE' ? okEnvelope('progress_decide', result) : errorEnvelope('progress_decide', result.reasons?.[0]?.code ?? 'PROGRESS_BLOCKED', result.reasons, result));
+    });
+  });
+  register('tech_lead_critical_path', 'Compute blockers, critical path, cycles (with cycleNodes), and parallel windows. Both inputs must be JSON arrays; graph findings (CYCLE / INVALID_TASK_ID / DUPLICATE_TASK_ID) are returned as envelope errors under code SCHEMA_INVALID.', {
+    tasksJson: { type: 'string', required: true, description: '[{id,status?,blocker?}] as JSON text' },
+    dependenciesJson: { type: 'string', required: true, description: '[{from,to}] edge list as JSON text; from blocks to' },
+  }, async (args) => {
+    return runGuarded('critical_path', () => {
+      const input = parseJsonFields(args ?? {}, ['tasksJson', 'dependenciesJson']);
+      if (!input.ok) return renderEnvelope(errorEnvelope('critical_path', 'BAD_INPUT', input.errors));
+      const errors = [];
+      if (!Array.isArray(input.values.tasksJson)) errors.push({ code: 'BAD_INPUT', path: 'tasksJson', message: 'expected JSON array of tasks' });
+      if (!Array.isArray(input.values.dependenciesJson)) errors.push({ code: 'BAD_INPUT', path: 'dependenciesJson', message: 'expected JSON array of edges' });
+      if (errors.length) return renderEnvelope(errorEnvelope('critical_path', 'BAD_INPUT', errors));
+      const result = core.criticalPath(input.values.tasksJson, input.values.dependenciesJson);
+      const blocking = result.findings.filter((f) => BLOCKING_FINDINGS.has(f.code));
+      if (blocking.length) {
+        return renderEnvelope(errorEnvelope('critical_path', 'SCHEMA_INVALID', result.findings.map((f) => ({ ...f, code: f.code })), result));
+      }
+      return renderEnvelope(okEnvelope('critical_path', result));
+    });
+  });
+  register('tech_lead_change_impact', 'Classify change impact (T0/T1/T2), reversibility, and Gate reopen requirements without applying the change. Trigger fields: irreversible (any truthy), publicInterface, modules[], assets[].', {
+    changeJson: { type: 'string', required: true, description: '{modules?:string[],assets?:string[],irreversible?,publicInterface?} as JSON text' },
+    contextJson: { type: 'string', required: true, description: 'context snapshot JSON text ({gates?:[{id}]})' },
+  }, async (args) => {
+    return runGuarded('change_impact', () => {
+      const input = parseJsonFields(args ?? {}, ['changeJson', 'contextJson']);
+      if (!input.ok) return renderEnvelope(errorEnvelope('change_impact', 'BAD_INPUT', input.errors));
+      return renderEnvelope(okEnvelope('change_impact', core.changeImpact(input.values.changeJson, input.values.contextJson)));
+    });
+  });
+  register('tech_lead_resume_reconcile', 'Compare two inline snapshots key-order-insensitively and report deterministic drift with the differing top-level keys.', {
+    previousJson: { type: 'string', required: true, description: 'previous snapshot JSON text' },
+    currentJson: { type: 'string', required: true, description: 'current snapshot JSON text' },
+  }, async (args) => {
+    return runGuarded('resume_reconcile', () => {
+      const input = parseJsonFields(args ?? {}, ['previousJson', 'currentJson']);
+      if (!input.ok) return renderEnvelope(errorEnvelope('resume_reconcile', 'BAD_INPUT', input.errors));
+      const previous = canonicalStringify(input.values.previousJson);
+      const current = canonicalStringify(input.values.currentJson);
+      const changed = JSON.stringify(previous) !== JSON.stringify(current);
+      if (!changed) return renderEnvelope(okEnvelope('resume_reconcile', { drift: false }));
+      const changedKeys = computeChangedKeys(previous, current);
+      return renderEnvelope(errorEnvelope('resume_reconcile', 'DRIFT_DETECTED', changedKeys.map((key) => ({ code: 'KEY_DRIFT', path: `/${key}`, message: `value differs at top-level key "${key}"` })), { drift: true, changedKeys }));
+    });
+  });
+  return output;
+}
+
+function computeChangedKeys(a, b) {
+  if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') return ['<root>'];
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  return [...keys].filter((key) => JSON.stringify(a[key]) !== JSON.stringify(b[key])).sort();
+}

package/src/tools.js

@@ -0,0 +1,221 @@
+import { registerContextTools } from './tools/context.js';
+import { registerProgressTools } from './tools/progress.js';
+import { registerGateTools } from './tools/gates.js';
+import { registerMutationTools } from './tools/mutation.js';
+import { renderEnvelope } from './protocol.js';
+
+/**
+ * Tool definitions for the tech-lead read-only surface.
+ *
+ * Every tool computes over caller-supplied primitives/JSON strings:
+ * - composite inputs arrive as JSON strings (parsed defensively),
+ * - list inputs arrive as comma-separated values,
+ * - outputs are pretty-printed JSON strings (uniform string schema); malformed inputs yield structured BAD_INPUT/invalid results instead of throws.
+ * - Legacy nine tools return BARE domain shapes (not wrapped in a tech-lead.result.v1 envelope); consumers can discriminate via the absence of meta.schema. Bare top-level finding arrays slice silently at 500 entries (shape preserved, no warning field exists).
+ * - All rendered output is clamped: finding/error arrays are capped at 500 entries (FINDINGS_TRUNCATED warning appended), oversized caller-echo arrays collapse into {truncated,total}, and payloads above 256KB switch to compact serialization.
+ *
+ * No tool touches the filesystem, spawns processes, or performs network I/O.
+ *
+ * @param {Function} defineTool harness tool factory
+ * @param {Record<string, Function>} core pure validators from @240xu/dsh-tech-lead-core
+ */
+export function registerTools(defineTool, core) {
+  const json = (str) => {
+    try {
+      return { ok: true, value: JSON.parse(str) };
+    } catch (err) {
+      return { ok: false, error: 'invalid JSON: ' + err.message };
+    }
+  };
+  const csv = (str) =>
+    String(str ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+  const out = (value) => renderEnvelope(value);
+
+  /** @type {ReturnType<defineTool>[]} */
+  const tools = [];
+
+  tools.push(defineTool({
+    name: 'tech_lead_classify',
+    description:
+      'Classify a task into tech-lead tiers T0/T1/T2 with reasons. T2 involves multi-module work, irreversible ops, protected assets (user data/secrets/runtime), or public interfaces. Use before planning.',
+    parameters: {
+      touchesMultipleModules: { type: 'boolean', description: 'change spans ≥2 modules' },
+      estimatedDays: { type: 'number', description: 'rough duration in days' },
+      irreversibleOps: { type: 'string', description: 'comma-separated irreversible operations' },
+      protectedAssetTypes: { type: 'string', description: 'comma-separated among SOURCE,USER_DATA,CONFIG,SECRET,RUNTIME,GENERATED' },
+      publicInterfaceChange: { type: 'boolean', description: 'changes public API/contract' },
+      uncertainRisk: { type: 'boolean', description: 'risk level cannot be determined yet' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
+    async execute(args) {
+      const provided = [args.touchesMultipleModules, args.estimatedDays, args.irreversibleOps, args.protectedAssetTypes, args.publicInterfaceChange, args.uncertainRisk];
+      const input = provided.every((v) => v === undefined || v === '')
+        ? {}
+        : {
+            touchesMultipleModules: args.touchesMultipleModules,
+            estimatedDays: args.estimatedDays,
+            irreversibleOps: csv(args.irreversibleOps),
+            protectedAssetTypes: csv(args.protectedAssetTypes),
+            publicInterfaceChange: args.publicInterfaceChange,
+            uncertainRisk: args.uncertainRisk,
+          };
+      return out(core.classify(input));
+    },
+  }));
+
+  tools.push(defineTool({
+    name: 'tech_lead_state_validate',
+    description:
+      'Validate a tech-lead project state.json (schema v1): enum fields, non-empty anchors on done items, full evidence provenance (id/level E0-E4/source/time/scope/repro). Unknown fields preserved as warnings. Returns pretty-printed JSON string.',
+    parameters: {
+      stateJson: { type: 'string', required: true, description: 'state.json SERIALIZED AS A STRING — pass the JSON text itself, never a nested object' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
+    async execute(args) {
+      const parsed = json(args.stateJson);
+      if (!parsed.ok) return out({ valid: false, errors: [{ path: 'stateJson', message: parsed.error }], warnings: [], unknownFields: [] });
+      return out(core.validateState(parsed.value));
+    },
+  }));
+
+  tools.push(defineTool({
+    name: 'tech_lead_transition_check',
+    description:
+      'Check whether a proposed outcome transition (CONTINUE/PAUSE/SCOPE-DOWN/PIVOT/STOP) is mechanically justified by the given state. PIVOT needs recorded decisions; SCOPE-DOWN needs goal ledger + risks; STOP needs anchored done items or degraded_reason. Returns pretty-printed JSON string.',
+    parameters: {
+      stateJson: { type: 'string', required: true, description: 'current state object SERIALIZED AS A STRING (JSON text, not an object)' },
+      proposed: { type: 'string', required: true, description: 'one of CONTINUE,PAUSE,SCOPE-DOWN,PIVOT,STOP' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
+    async execute(args) {
+      const parsed = json(args.stateJson);
+      if (!parsed.ok) return out({ allowed: false, reason: parsed.error });
+      return out(core.transitionCheck(parsed.value, args.proposed));
+    },
+  }));
+
+  tools.push(defineTool({
+    name: 'tech_lead_plan_lint',
+    description:
+      'Lint a plan for the tech-lead minimum contracts: goal+metric+target ledger, assumption verification methods, decision alternatives+reasons, risk impacts+mitigations, dependency blockers, rollback for irreversible ops. Returns pretty-printed JSON array of findings.',
+    parameters: {
+      planJson: { type: 'string', required: true, description: 'plan object SERIALIZED AS A STRING (JSON text, not an object)' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
+    async execute(args) {
+      const parsed = json(args.planJson);
+      if (!parsed.ok) return out([{ severity: 'error', path: 'planJson', message: parsed.error }]);
+      return out(core.planLint(parsed.value));
+    },
+  }));
+
+  tools.push(defineTool({
+    name: 'tech_lead_evidence_lint',
+    description:
+      'Lint evidence entries for complete provenance (id/level E0-E4/source/time/scope/repro). With highRiskChange=true, requires at least one E3+ evidence item. Returns pretty-printed JSON findings array.',
+    parameters: {
+      evidenceJson: { type: 'string', required: true, description: 'evidence array SERIALIZED AS A STRING (JSON text, not an object)' },
+      highRiskChange: { type: 'boolean', description: 'set true for high-risk changes' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
+    async execute(args) {
+      const parsed = json(args.evidenceJson);
+      if (!parsed.ok) return out([{ severity: 'error', path: 'evidenceJson', message: parsed.error }]);
+      return out(core.evidenceLint(parsed.value, { highRiskChange: args.highRiskChange }));
+    },
+  }));
+
+  tools.push(defineTool({
+    name: 'tech_lead_gate_precheck',
+    description:
+      'Precheck a gate review: referee identity separation (proposer/executor must not review), per-report anchors, verdict vocabulary (pass|conditional|reject), solo-review prohibition on destructive scope, blind-gate quorum of ≥3 distinct anchored reviewers. Returns {pass, violations[]}.',
+    parameters: {
+      inputJson: { type: 'string', required: true, description: '{proposalAuthorId?,executorId?,reviewerIds[],solo?,blindRequired?,destructiveScope[],reports[{reviewerId,verdict,anchors[]}]}' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
+    async execute(args) {
+      const parsed = json(args.inputJson);
+      if (!parsed.ok) return out({ pass: false, violations: [{ type: 'BAD_INPUT', detail: parsed.error }] });
+      return out(core.gatePrecheck(parsed.value));
+    },
+  }));
+
+  tools.push(defineTool({
+    name: 'tech_lead_release_audit',
+    description:
+      'Audit a release set: files outside the allowlist are EXTRA_FILE; when contents are provided, scans lines for absolute home paths, token-like literals (sk-/ghp_/AKIA/xox), credential assignments — each with line numbers. Read-only; never uploads anything. Returns pretty-printed JSON findings array.',
+    parameters: {
+      allowlistCsv: { type: 'string', required: true, description: 'comma-separated allowed relative paths' },
+      filesJson: { type: 'string', required: true, description: '[{path, content?}] as JSON string' },
+      contentScan: { type: 'boolean', description: 'default true' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
+    async execute(args) {
+      const parsed = json(args.filesJson);
+      if (!parsed.ok) return out([{ type: 'BAD_INPUT', path: 'filesJson', line: 0, detail: parsed.error }]);
+      return out(core.releaseAudit({
+        allowlist: csv(args.allowlistCsv),
+        files: parsed.value,
+        contentScan: args.contentScan,
+      }));
+    },
+  }));
+
+  tools.push(defineTool({
+    name: 'tech_lead_install_audit',
+    description:
+      'Detect install drift between an installed marker manifest and reality: missing managed files, unmanaged extras (backups ignored), version mismatch against the package. Returns {missingManaged[], unmanaged[], versionMismatch, newInPackage[]}.',
+    parameters: {
+      manifestJson: { type: 'string', required: true, description: 'marker {version, files[]} SERIALIZED AS A STRING (JSON text, not an object)' },
+      actualFilesCsv: { type: 'string', required: true, description: 'comma-separated relative paths present under target' },
+      pkgFilesCsv: { type: 'string', required: true, description: 'comma-separated managed paths in current package' },
+      pkgVersion: { type: 'string', required: true, description: 'package version string' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
+    async execute(args) {
+      const parsed = json(args.manifestJson);
+      if (!parsed.ok || !parsed.value || !Array.isArray(parsed.value.files)) {
+        return out({ missingManaged: [], unmanaged: [], versionMismatch: false, newInPackage: [], error: 'manifestJson must be {version, files[]}' });
+      }
+      return out(core.installAudit(
+        parsed.value,
+        csv(args.actualFilesCsv),
+        csv(args.pkgFilesCsv),
+        args.pkgVersion
+      ));
+    },
+  }));
+
+  tools.push(defineTool({
+    name: 'tech_lead_resume_card',
+    description:
+      'Render a three-line resume card from a tech-lead state: position (tier/phase/mode), last outcome, next step — plus stale-evidence detection (>maxAgeDays old) and warnings for empty next_step or open gates. Returns pretty-printed JSON card.',
+    parameters: {
+      stateJson: { type: 'string', required: true, description: 'state object SERIALIZED AS A STRING (JSON text, not an object)' },
+      nowIso: { type: 'string', description: 'reference time ISO string (defaults to real now)' },
+      maxAgeDays: { type: 'number', description: 'stale threshold in days, default 7' },
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
+    async execute(args) {
+      const parsed = json(args.stateJson);
+      if (!parsed.ok) {
+        return out({ position: '?', lastGate: '?', nextStep: '(invalid state)', staleEvidenceIds: [], warnings: [parsed.error] });
+      }
+      return out(core.resumeCard(parsed.value, { now: args.nowIso, maxAgeDays: args.maxAgeDays }));
+    },
+  }));
+
+  if (core.validateContext && core.evidenceGraphLint && core.evidenceFreshness) {
+    // Domain registration stays optional so the legacy nine-tool contract can
+    // be reused by callers that supply only the original core surface.
+    tools.push(...registerContextTools(defineTool, core));
+  }
+  if (core.progressDecide && core.criticalPath && core.changeImpact) {
+    tools.push(...registerProgressTools(defineTool, core));
+  }
+  if (core.gatePlan && core.gateAggregate && core.gateReopen) {
+    tools.push(...registerGateTools(defineTool, core));
+  }
+  if (core.previewMutation) tools.push(...registerMutationTools(defineTool));
+  return tools;
+}