sneakoscope 0.8.6 → 0.9.0

package/README.md

@@ -59,6 +59,19 @@ Research scouts now use named persona-inspired cognitive lenses: Einstein Scout,
 
 For existing 0.7.x users, the visible change is new report-only evidence, not a route personality rewrite. Team still feels like Team, DFix stays ultralight, DB remains conservative, QA-LOOP still dogfoods, PPT stays information-first, imagegen still requires real raster evidence, and Honest Mode remains the final truth pass. The original strong reminder idea became neutral RecallPulse so user-facing prompts stay short, professional, and non-repetitive; hook messages can point at status, but `mission-status-ledger.json` is the durable source when app-visible text disappears. The planning source is `docs/RECALLPULSE_0_8_0_TASKS.md`, and implementation is designed to land in safe task-sized slices before any enforcement promotion.
 
+## 0.9.0 Report-Only Decision Lattice
+
+Sneakoscope 0.9.0 adds a report-only Decision Lattice planner that uses A* over proof-debt signals to explain which route or verification path the pipeline would prefer. It is an evidence and planning surface, not a runtime shortcut: SKS must not claim speedup, fast-lane accuracy, or reduced verification cost from the lattice until replay or scored eval evidence demonstrates those outcomes.
+
+The lattice integrates with the existing proof-field and `sks pipeline plan` surfaces. Its reports are expected to show the explored frontier, the selected path, and rejected paths with their proof-debt reasons, so reviewers can audit why a route stayed on the full Team/Honest path or why a smaller verification plan was only proposed. Like RecallPulse, this is designed to land as report-only evidence first; route enforcement and performance claims remain gated by later validation.
+
+Quick checks:
+
+```bash
+sks proof-field scan --json --intent "small CLI change"
+sks pipeline plan latest --proof-field --json
+```
+
 ## Requirements
 
 - Node.js `>=20.11`
@@ -239,7 +252,7 @@ sks code-structure scan --json
 
 `sks recallpulse` is the 0.8.0 report-only RecallPulse utility. It writes `recallpulse-decision.json`, `mission-status-ledger.json`, `route-proof-capsule.json`, `evidence-envelope.json`, `recallpulse-governance-report.json`, `recallpulse-task-goal-ledger.json`, and `recallpulse-eval-report.json` for the current mission. RecallPulse does not replace route gates, Honest Mode, DB safety, imagegen evidence, or TriWiki validation; it records cache hits, hydration needs, duplicate suppression, route-governance risks, and final-summary-ready durable status so later releases can promote only measured improvements. Checklist updates are sequential: every `Txxx` row is treated as a child `$Goal` checkpoint, and `sks recallpulse checklist ... --task T001 --apply` refuses out-of-order checks unless explicitly overridden.
 
-`sks pipeline plan` shows the active route lane, kept/skipped stages, verification commands, and no-unrequested-fallback invariant. `sks proof-field scan` is the lightweight rubric for small changes; risky or broad signals return to the full Team/Honest path.
+`sks pipeline plan` shows the active route lane, kept/skipped stages, verification commands, and no-unrequested-fallback invariant. The 0.9.0 Decision Lattice augments this planning surface with report-only A*/proof-debt evidence: frontier paths considered, the selected path, and rejected paths with rejection reasons. `sks proof-field scan` remains the lightweight rubric for small changes; risky or broad signals return to the full Team/Honest path, and no speedup claim is valid without replay or eval evidence.
 
 ### Ambiguity Questions
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "ㅅㅋㅅ",
-  "version": "0.8.6",
+  "version": "0.9.0",
   "description": "Sneakoscope Codex: database-safe Codex CLI/App harness with Team, Goal, AutoResearch, TriWiki, and Honest Mode.",
   "type": "module",
   "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",

package/src/cli/main.mjs

@@ -3828,20 +3828,20 @@ async function selftest() {
   if (!harnessReport.forgetting.fixture.passed || !harnessReport.tmux.views.includes('Harness Experiments View') || !harnessReport.reliability.tool_error_taxonomy.includes('Unknown')) throw new Error('selftest: harness growth fixture incomplete');
   const proofField = await proofFieldFixture();
   if (!proofField.validation.ok || !validateProofFieldReport(proofField.report).ok) throw new Error('selftest: proof field report invalid');
-  if (!proofField.checks.route_cone_selected || !proofField.checks.cli_cone_selected || !proofField.checks.catastrophic_guard_present || !proofField.checks.negative_release_work_recorded || !proofField.checks.outcome_rubric_present || !proofField.checks.adversarial_lenses_present || !proofField.checks.route_economy_present || !proofField.checks.simplicity_score_usable || !proofField.checks.execution_fast_lane_selected) throw new Error('selftest: proof field fixture checks incomplete');
+  if (!proofField.checks.route_cone_selected || !proofField.checks.cli_cone_selected || !proofField.checks.catastrophic_guard_present || !proofField.checks.negative_release_work_recorded || !proofField.checks.outcome_rubric_present || !proofField.checks.adversarial_lenses_present || !proofField.checks.route_economy_present || !proofField.checks.decision_lattice_present || !proofField.checks.decision_lattice_report_only || !proofField.checks.decision_lattice_selected_path || !proofField.checks.decision_lattice_frontier_present || !proofField.checks.decision_lattice_rejections_present || !proofField.checks.decision_lattice_scoring_formula_present || !proofField.checks.simplicity_score_usable || !proofField.checks.execution_fast_lane_selected) throw new Error('selftest: proof field fixture checks incomplete');
   if (!speedLanePolicyText().includes('proof_field_fast_lane') || !proofField.report.execution_lane?.skip_when_fast?.includes('planning_debate')) throw new Error('selftest: Proof Field speed lane policy missing');
   const fastPipelinePlan = buildPipelinePlan({ route: routePrompt('$Team small CLI help update'), task: 'small CLI help surface update', proofField: proofField.report });
   if (!validatePipelinePlan(fastPipelinePlan).ok || fastPipelinePlan.runtime_lane?.lane !== 'proof_field_fast_lane' || !fastPipelinePlan.skipped_stages.includes('planning_debate') || !fastPipelinePlan.invariants.includes('no_unrequested_fallback_code')) throw new Error('selftest: pipeline plan did not encode fast lane stage skips and fallback guard');
   const broadProofField = await buildProofField(tmp, { intent: 'database security route refactor', changedFiles: ['src/core/db-safety.mjs', 'src/core/routes.mjs', 'src/cli/main.mjs', 'README.md'] });
   const broadPipelinePlan = buildPipelinePlan({ route: routePrompt('$Team database security route refactor'), task: 'database security route refactor', proofField: broadProofField });
   if (!validatePipelinePlan(broadPipelinePlan).ok || broadPipelinePlan.runtime_lane?.lane === 'proof_field_fast_lane' || broadPipelinePlan.skipped_stages.includes('planning_debate')) throw new Error('selftest: pipeline plan did not fail closed for broad/security work');
-  if (broadPipelinePlan.route_economy?.mode !== 'report_only' || !broadPipelinePlan.route_economy.active_team_triggers?.includes('broad_change_set') || !broadPipelinePlan.route_economy.verification_stage_cache_key) throw new Error('selftest: route economy projection missing from pipeline plan');
+  if (broadPipelinePlan.route_economy?.mode !== 'report_only' || !broadPipelinePlan.route_economy.active_team_triggers?.includes('broad_change_set') || !broadPipelinePlan.route_economy.verification_stage_cache_key || !broadPipelinePlan.route_economy.decision_lattice?.report_only) throw new Error('selftest: route economy projection missing from pipeline plan');
   const workflowPerf = await runWorkflowPerfBench(tmp, {
     iterations: 2,
     intent: 'small CLI help surface update',
     changedFiles: ['src/cli/maintenance-commands.mjs', 'src/core/routes.mjs']
   });
-  if (!validateWorkflowPerfReport(workflowPerf).ok || workflowPerf.metrics.decision_mode !== 'fast_lane' || workflowPerf.metrics.execution_lane !== 'proof_field_fast_lane' || workflowPerf.metrics.pipeline_lane !== 'proof_field_fast_lane' || !workflowPerf.metrics.fast_lane_eligible || !workflowPerf.metrics.fast_lane_allowed || Number(workflowPerf.metrics.simplicity_score) < 0.75 || Number(workflowPerf.metrics.outcome_criteria_passed) < 3) throw new Error('selftest: workflow perf proof field did not produce a valid outcome-scored fast lane report');
+  if (!validateWorkflowPerfReport(workflowPerf).ok || workflowPerf.metrics.decision_mode !== 'fast_lane' || workflowPerf.metrics.execution_lane !== 'proof_field_fast_lane' || workflowPerf.metrics.pipeline_lane !== 'proof_field_fast_lane' || !workflowPerf.metrics.fast_lane_eligible || !workflowPerf.metrics.fast_lane_allowed || !workflowPerf.metrics.decision_lattice_valid || Number(workflowPerf.metrics.decision_lattice_frontier_count) < 1 || Number(workflowPerf.metrics.simplicity_score) < 0.75 || Number(workflowPerf.metrics.outcome_criteria_passed) < 3) throw new Error('selftest: workflow perf proof field did not produce a valid outcome-scored fast lane report');
   if (classifyToolError({ message: 'operation timed out' }) !== 'Timeout' || classifyToolError({ message: 'unclassified weirdness' }) !== 'Unknown') throw new Error('selftest: tool error taxonomy classification');
   const coord = rgbaToWikiCoord({ r: 12, g: 34, b: 56, a: 255 });
   if (coord.schema !== 'sks.wiki-coordinate.v1' || coord.xyzw.length !== 4) throw new Error('selftest: RGBA wiki coordinate conversion');

package/src/cli/maintenance-commands.mjs

@@ -969,6 +969,9 @@ export async function proofFieldCommand(sub, args = []) {
   console.log(`Workflow complexity: ${report.workflow_complexity.band} (${report.workflow_complexity.score})`);
   if (report.team_trigger_matrix.active_triggers.length) console.log(`Team triggers: ${report.team_trigger_matrix.active_triggers.join(', ')}`);
   console.log(`Proof cones: ${report.proof_cones.map((cone) => cone.id).join(', ')}`);
+  if (report.decision_lattice?.selected_path?.id) {
+    console.log(`Decision lattice: ${report.decision_lattice.selected_path.id} f=${report.decision_lattice.selected_path.cost?.f ?? 'n/a'} frontier=${report.decision_lattice.frontier?.expanded_order?.length || 0} rejected=${report.decision_lattice.rejected_alternatives?.length || 0}`);
+  }
   console.log(`Verification: ${report.fast_lane_decision.verification.join('; ')}`);
   console.log(`Report: ${path.relative(root, report.report_path)}`);
 }

package/src/core/decision-lattice.mjs

@@ -0,0 +1,481 @@
+export const DECISION_LATTICE_SCHEMA_VERSION = 1;
+
+export const DEFAULT_LATTICE_WEIGHTS = Object.freeze({
+  step: 1,
+  proof_debt: 3,
+  risk: 1,
+  friction: 1,
+  info_gain: 1
+});
+
+const AXES = Object.freeze(['contract', 'context', 'implementation', 'verification', 'review']);
+
+const DEFAULT_START = Object.freeze({
+  contract: 0,
+  context: 0,
+  implementation: 0,
+  verification: 0,
+  review: 0
+});
+
+const DEFAULT_GOAL = Object.freeze({
+  contract: 2,
+  context: 2,
+  implementation: 2,
+  verification: 2,
+  review: 1
+});
+
+const DEFAULT_ACTIONS = Object.freeze([
+  {
+    id: 'seal_contract',
+    label: 'Seal decision contract',
+    delta: { contract: 2 },
+    risk: 0.05,
+    friction: 0.25,
+    info_gain: 0.9,
+    notes: ['Removes ambiguity before route selection.']
+  },
+  {
+    id: 'read_triwiki',
+    label: 'Read bounded TriWiki context',
+    delta: { context: 1 },
+    risk: 0.05,
+    friction: 0.2,
+    info_gain: 0.7,
+    notes: ['Uses compact high-trust recall before editing.']
+  },
+  {
+    id: 'proof_field_scan',
+    label: 'Run proof-field scan',
+    delta: { context: 2, verification: 1 },
+    risk: 0.1,
+    friction: 0.35,
+    info_gain: 0.95,
+    notes: ['Scores route surface and escalation triggers.']
+  },
+  {
+    id: 'minimal_patch',
+    label: 'Implement smallest scoped change',
+    delta: { implementation: 2 },
+    risk: 0.35,
+    friction: 0.35,
+    info_gain: 0.4,
+    notes: ['Touches only the selected proof cone.']
+  },
+  {
+    id: 'focused_verification',
+    label: 'Run focused verification',
+    delta: { verification: 1 },
+    risk: 0.12,
+    friction: 0.45,
+    info_gain: 0.85,
+    notes: ['Checks syntax and behavior for the changed module.']
+  },
+  {
+    id: 'five_lane_review',
+    label: 'Collect five-lane Team review',
+    delta: { review: 1 },
+    risk: 0.2,
+    friction: 1.1,
+    info_gain: 1,
+    notes: ['Satisfies Team review gate for broad missions.']
+  },
+  {
+    id: 'honest_mode',
+    label: 'Run Honest Mode closeout',
+    delta: { verification: 1 },
+    risk: 0.05,
+    friction: 0.2,
+    info_gain: 0.65,
+    notes: ['Binds final claims to evidence and gaps.']
+  }
+]);
+
+const DEFAULT_ROUTE_PATHS = Object.freeze([
+  {
+    id: 'proof_field_fast_lane',
+    label: 'Proof Field Fast Lane',
+    action_ids: ['seal_contract', 'read_triwiki', 'proof_field_scan', 'minimal_patch', 'focused_verification', 'honest_mode'],
+    notes: ['Lowest friction when scope is narrow and risk flags stay low.']
+  },
+  {
+    id: 'balanced_team_lane',
+    label: 'Balanced Team Lane',
+    action_ids: ['seal_contract', 'read_triwiki', 'proof_field_scan', 'minimal_patch', 'focused_verification', 'five_lane_review', 'honest_mode'],
+    notes: ['Adds review evidence while preserving a compact change surface.']
+  },
+  {
+    id: 'full_team_honest_path',
+    label: 'Full Team Honest Path',
+    action_ids: ['seal_contract', 'read_triwiki', 'proof_field_scan', 'five_lane_review', 'minimal_patch', 'focused_verification', 'five_lane_review', 'honest_mode'],
+    notes: ['Heaviest default for broad or release-sensitive missions.']
+  }
+]);
+
+export function buildDecisionLatticeReport(input = {}) {
+  const weights = normalizeWeights(input.weights);
+  const start = normalizeState(input.start_state || input.start || DEFAULT_START);
+  const goal = normalizeState(input.goal_state || input.target_state || input.target || inferredGoal(input));
+  const actions = normalizeActions(input.actions || DEFAULT_ACTIONS);
+  const routePaths = normalizeRoutePaths(input.route_paths || input.candidate_route_paths || DEFAULT_ROUTE_PATHS, actions);
+  const grid = buildConceptualGrid(start, goal, actions);
+  const search = runAStar({ start, goal, actions, weights });
+  const routeCandidates = routePaths.map((routePath, index) => evaluateRoutePath(routePath, index, { start, goal, actions, weights }));
+  const candidates = routeCandidates.concat([{ ...search.selected_path, rank_hint: routeCandidates.length }]).sort(compareCandidates);
+  const selected = selectPath(candidates, search.selected_path);
+  const rejected = candidates
+    .filter((candidate) => candidate.id !== selected.id)
+    .map((candidate) => ({
+      id: candidate.id,
+      label: candidate.label,
+      f: candidate.cost.f,
+      delta_from_selected: round(candidate.cost.f - selected.cost.f),
+      rejection_reasons: rejectionReasons(candidate, selected)
+    }));
+  const report = {
+    schema_version: DECISION_LATTICE_SCHEMA_VERSION,
+    report_only: true,
+    deterministic: true,
+    module: 'decision-lattice',
+    scoring_formula: String(input.scoring_formula || 'f = g + h + risk + friction - info_gain'),
+    research_basis: {
+      model: 'Decision Lattice A* planner',
+      scoring_formula: 'f = g + h + risk + friction - info_gain',
+      proof_debt_heuristic: 'h is weighted remaining lattice debt across contract, context, implementation, verification, and review axes.'
+    },
+    input_summary: {
+      intent: String(input.intent || input.goal || '').trim() || null,
+      weights,
+      start_state: start,
+      goal_state: goal,
+      action_count: actions.length,
+      route_path_count: routePaths.length
+    },
+    heuristic: {
+      id: 'proof_debt',
+      h_start: proofDebt(start, goal, weights),
+      axes: AXES.map((axis) => ({
+        axis,
+        start: start[axis],
+        goal: goal[axis],
+        debt: debtForAxis(start, goal, axis),
+        weighted_debt: round(debtForAxis(start, goal, axis) * weights.proof_debt)
+      }))
+    },
+    conceptual_grid: grid,
+    frontier: search.frontier,
+    candidate_paths: candidates,
+    selected_path: selected,
+    rejected_alternatives: rejected,
+    validation: null
+  };
+  report.validation = validateDecisionLatticeReport(report);
+  return report;
+}
+
+function inferredGoal(input = {}) {
+  const goal = { ...DEFAULT_GOAL };
+  if (input.execution_lane?.fast_lane_allowed === true && !(input.team_trigger_matrix?.active_triggers || []).length) {
+    goal.review = 0;
+  }
+  return goal;
+}
+
+export function validateDecisionLatticeReport(report = {}) {
+  const issues = [];
+  if (report.schema_version !== DECISION_LATTICE_SCHEMA_VERSION) issues.push('schema_version');
+  if (report.report_only !== true) issues.push('report_only');
+  if (report.deterministic !== true) issues.push('deterministic');
+  if (report.research_basis?.scoring_formula !== 'f = g + h + risk + friction - info_gain') issues.push('scoring_formula');
+  if (!Array.isArray(report.heuristic?.axes) || report.heuristic.axes.length !== AXES.length) issues.push('heuristic_axes');
+  if (!Number.isFinite(Number(report.heuristic?.h_start))) issues.push('heuristic_h_start');
+  if (!Array.isArray(report.conceptual_grid?.cells) || report.conceptual_grid.cells.length < 1) issues.push('conceptual_grid');
+  if (!Array.isArray(report.frontier?.expanded_order) || report.frontier.expanded_order.length < 1) issues.push('frontier_expanded_order');
+  if (!Array.isArray(report.candidate_paths) || report.candidate_paths.length < 1) issues.push('candidate_paths');
+  if (!report.selected_path?.id || !Array.isArray(report.selected_path?.steps)) issues.push('selected_path');
+  if (!Array.isArray(report.rejected_alternatives)) issues.push('rejected_alternatives');
+  if (report.candidate_paths?.some((candidate) => !Number.isFinite(Number(candidate?.cost?.f)))) issues.push('candidate_costs');
+  if (report.selected_path?.cost?.f !== Math.min(...(report.candidate_paths || []).map((candidate) => candidate.cost.f))) issues.push('selected_path_not_min_f');
+  return { ok: issues.length === 0, issues };
+}
+
+function normalizeWeights(input = {}) {
+  return {
+    step: positiveNumber(input.step, DEFAULT_LATTICE_WEIGHTS.step),
+    proof_debt: positiveNumber(input.proof_debt, DEFAULT_LATTICE_WEIGHTS.proof_debt),
+    risk: positiveNumber(input.risk, DEFAULT_LATTICE_WEIGHTS.risk),
+    friction: positiveNumber(input.friction, DEFAULT_LATTICE_WEIGHTS.friction),
+    info_gain: positiveNumber(input.info_gain, DEFAULT_LATTICE_WEIGHTS.info_gain)
+  };
+}
+
+function normalizeState(input = {}) {
+  const state = {};
+  for (const axis of AXES) state[axis] = clampInt(input[axis], 0, 3);
+  return state;
+}
+
+function normalizeActions(input = []) {
+  return input
+    .map((action, index) => ({
+      id: safeId(action.id || `action_${index + 1}`),
+      label: String(action.label || action.id || `Action ${index + 1}`),
+      delta: normalizeDelta(action.delta || {}),
+      risk: nonNegativeNumber(action.risk, 0),
+      friction: nonNegativeNumber(action.friction, 0),
+      info_gain: nonNegativeNumber(action.info_gain, 0),
+      notes: arrayOfStrings(action.notes)
+    }))
+    .filter((action) => AXES.some((axis) => action.delta[axis] > 0))
+    .sort(compareById);
+}
+
+function normalizeRoutePaths(input = [], actions = []) {
+  const actionIds = new Set(actions.map((action) => action.id));
+  return input
+    .map((routePath, index) => ({
+      id: safeId(routePath.id || `route_path_${index + 1}`),
+      label: String(routePath.label || routePath.id || `Route Path ${index + 1}`),
+      action_ids: arrayOfStrings(routePath.action_ids || routePath.actions).map(safeId).filter((id) => actionIds.has(id)),
+      notes: arrayOfStrings(routePath.notes)
+    }))
+    .filter((routePath) => routePath.action_ids.length > 0)
+    .sort(compareById);
+}
+
+function normalizeDelta(delta = {}) {
+  const out = {};
+  for (const axis of AXES) out[axis] = clampInt(delta[axis], 0, 3);
+  return out;
+}
+
+function runAStar({ start, goal, actions, weights }) {
+  const open = [nodeForState(start, { g: 0, h: proofDebt(start, goal, weights), risk: 0, friction: 0, info_gain: 0, steps: [] })];
+  const best = new Map([[stateKey(start), 0]]);
+  const closed = [];
+  const snapshots = [];
+  let selected = open[0];
+
+  while (open.length > 0 && closed.length < 64) {
+    open.sort(compareNodes);
+    const current = open.shift();
+    closed.push(current);
+    snapshots.push({ step: closed.length, current: current.key, f: current.f, open: open.map((node) => node.key).sort() });
+    if (isGoal(current.state, goal)) {
+      selected = current;
+      break;
+    }
+    for (const action of actions) {
+      const nextState = applyAction(current.state, action, goal);
+      const key = stateKey(nextState);
+      const g = round(current.g + weights.step);
+      if (best.has(key) && best.get(key) <= g) continue;
+      best.set(key, g);
+      const risk = round(current.risk + action.risk * weights.risk);
+      const friction = round(current.friction + action.friction * weights.friction);
+      const infoGain = round(current.info_gain + action.info_gain * weights.info_gain);
+      const h = proofDebt(nextState, goal, weights);
+      open.push(nodeForState(nextState, {
+        g,
+        h,
+        risk,
+        friction,
+        info_gain: infoGain,
+        steps: current.steps.concat([stepFromAction(action, nextState)])
+      }));
+    }
+  }
+
+  return {
+    selected_path: pathFromNode('astar_frontier_path', 'A* Frontier Path', selected),
+    frontier: {
+      expanded_order: closed.map((node, index) => ({ index, key: node.key, f: node.f, h: node.h, steps: node.steps.map((step) => step.id) })),
+      open_nodes: open.sort(compareNodes).slice(0, 12).map((node) => ({ key: node.key, f: node.f, h: node.h })),
+      closed_nodes: closed.map((node) => node.key),
+      snapshots
+    }
+  };
+}
+
+function evaluateRoutePath(routePath, index, { start, goal, actions, weights }) {
+  const actionById = new Map(actions.map((action) => [action.id, action]));
+  let state = { ...start };
+  let g = 0;
+  let risk = 0;
+  let friction = 0;
+  let infoGain = 0;
+  const steps = [];
+  for (const id of routePath.action_ids) {
+    const action = actionById.get(id);
+    if (!action) continue;
+    g = round(g + weights.step);
+    risk = round(risk + action.risk * weights.risk);
+    friction = round(friction + action.friction * weights.friction);
+    infoGain = round(infoGain + action.info_gain * weights.info_gain);
+    state = applyAction(state, action, goal);
+    steps.push(stepFromAction(action, state));
+  }
+  const h = proofDebt(state, goal, weights);
+  const f = round(g + h + risk + friction - infoGain);
+  return {
+    id: routePath.id,
+    label: routePath.label,
+    rank_hint: index,
+    route: routePath.action_ids,
+    steps,
+    final_state: state,
+    proof_debt: h,
+    complete: isGoal(state, goal),
+    cost: { g, h, risk, friction, info_gain: infoGain, f },
+    notes: routePath.notes
+  };
+}
+
+function selectPath(candidates, astarPath) {
+  const complete = candidates.filter((candidate) => candidate.complete);
+  const pool = complete.length ? complete : candidates;
+  const selected = pool.slice().sort(compareCandidates)[0] || astarPath;
+  return selected.cost.f <= astarPath.cost.f ? selected : astarPath;
+}
+
+function pathFromNode(id, label, node) {
+  return {
+    id,
+    label,
+    route: node.steps.map((step) => step.id),
+    steps: node.steps,
+    final_state: node.state,
+    proof_debt: node.h,
+    complete: node.h === 0,
+    cost: {
+      g: node.g,
+      h: node.h,
+      risk: node.risk,
+      friction: node.friction,
+      info_gain: node.info_gain,
+      f: node.f
+    },
+    notes: ['Generated by A* frontier expansion over the conceptual lattice.']
+  };
+}
+
+function nodeForState(state, input) {
+  const f = round(input.g + input.h + input.risk + input.friction - input.info_gain);
+  return { ...input, state, key: stateKey(state), f };
+}
+
+function applyAction(state, action, goal) {
+  const next = {};
+  for (const axis of AXES) next[axis] = Math.min(goal[axis], state[axis] + action.delta[axis]);
+  return next;
+}
+
+function proofDebt(state, goal, weights) {
+  return round(AXES.reduce((sum, axis) => sum + debtForAxis(state, goal, axis), 0) * weights.proof_debt);
+}
+
+function debtForAxis(state, goal, axis) {
+  return Math.max(0, Number(goal[axis] || 0) - Number(state[axis] || 0));
+}
+
+function buildConceptualGrid(start, goal, actions) {
+  return {
+    axes: AXES.map((axis) => ({ axis, start: start[axis], goal: goal[axis], span: Math.max(0, goal[axis] - start[axis]) })),
+    cells: AXES.map((axis) => ({
+      id: `axis_${axis}`,
+      axis,
+      start: start[axis],
+      goal: goal[axis],
+      candidate_actions: actions.filter((action) => action.delta[axis] > 0).map((action) => action.id)
+    })),
+    legend: {
+      g: 'path steps already paid',
+      h: 'remaining proof debt',
+      risk: 'expected safety and integration exposure',
+      friction: 'coordination and verification drag',
+      info_gain: 'uncertainty removed by the step'
+    }
+  };
+}
+
+function rejectionReasons(candidate, selected) {
+  const reasons = [];
+  if (!candidate.complete) reasons.push('remaining_proof_debt');
+  if (candidate.cost.risk > selected.cost.risk) reasons.push('higher_risk');
+  if (candidate.cost.friction > selected.cost.friction) reasons.push('higher_friction');
+  if (candidate.cost.info_gain < selected.cost.info_gain) reasons.push('lower_info_gain');
+  if (candidate.cost.f > selected.cost.f) reasons.push('higher_total_f');
+  return reasons.length ? reasons : ['tie_broken_by_deterministic_order'];
+}
+
+function compareCandidates(a, b) {
+  return (a.cost.f - b.cost.f)
+    || (a.cost.h - b.cost.h)
+    || (a.cost.risk - b.cost.risk)
+    || (a.cost.friction - b.cost.friction)
+    || (b.cost.info_gain - a.cost.info_gain)
+    || a.id.localeCompare(b.id);
+}
+
+function compareNodes(a, b) {
+  return (a.f - b.f)
+    || (a.h - b.h)
+    || (a.risk - b.risk)
+    || (a.friction - b.friction)
+    || (b.info_gain - a.info_gain)
+    || a.key.localeCompare(b.key);
+}
+
+function compareById(a, b) {
+  return a.id.localeCompare(b.id);
+}
+
+function stateKey(state) {
+  return AXES.map((axis) => `${axis}:${state[axis]}`).join('|');
+}
+
+function isGoal(state, goal) {
+  return AXES.every((axis) => state[axis] >= goal[axis]);
+}
+
+function stepFromAction(action, state) {
+  return {
+    id: action.id,
+    label: action.label,
+    state_after: state,
+    risk: action.risk,
+    friction: action.friction,
+    info_gain: action.info_gain,
+    notes: action.notes
+  };
+}
+
+function arrayOfStrings(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((item) => String(item || '').trim()).filter(Boolean);
+}
+
+function safeId(value) {
+  return String(value || 'item').trim().toLowerCase().replace(/[^a-z0-9_./-]+/g, '_').replace(/^_+|_+$/g, '') || 'item';
+}
+
+function clampInt(value, min, max) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return min;
+  return Math.max(min, Math.min(max, Math.floor(number)));
+}
+
+function positiveNumber(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : fallback;
+}
+
+function nonNegativeNumber(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : fallback;
+}
+
+function round(value) {
+  return Math.round(Number(value || 0) * 1000) / 1000;
+}

package/src/core/fsx.mjs

@@ -5,7 +5,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 
-export const PACKAGE_VERSION = '0.8.6';
+export const PACKAGE_VERSION = '0.9.0';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
 

package/src/core/perf-bench.mjs

@@ -110,6 +110,11 @@ export async function runWorkflowPerfBench(root, opts = {}) {
       workflow_complexity_band: proofField?.workflow_complexity?.band || null,
       team_trigger_count: proofField?.team_trigger_matrix?.active_triggers?.length || 0,
       verification_stage_cache_key: proofField?.verification_stage_cache?.cache_key || null,
+      decision_lattice_selected_path: proofField?.decision_lattice?.selected_path?.id || null,
+      decision_lattice_frontier_count: proofField?.decision_lattice?.frontier?.expanded_order?.length || 0,
+      decision_lattice_rejected_alternative_count: proofField?.decision_lattice?.rejected_alternatives?.length || 0,
+      decision_lattice_scoring_formula: proofField?.decision_lattice?.scoring_formula || null,
+      decision_lattice_valid: Boolean(proofField?.decision_lattice?.report_only) && proofValidation.ok,
       outcome_criteria_passed: (proofField?.simplicity_scorecard?.criteria || []).filter((item) => item.passed).length,
       proof_field_valid: proofValidation.ok,
       pipeline_plan_valid: planValidation.ok
@@ -138,7 +143,19 @@ export function validateWorkflowPerfReport(report = {}) {
   if (!Number.isFinite(Number(report.metrics?.workflow_complexity_score))) issues.push('workflow_complexity_score');
   if (!report.metrics?.workflow_complexity_band) issues.push('workflow_complexity_band');
   if (!report.metrics?.verification_stage_cache_key) issues.push('verification_stage_cache_key');
+  if (!report.metrics?.decision_lattice_selected_path) issues.push('decision_lattice_selected_path');
+  if (!Number.isFinite(Number(report.metrics?.decision_lattice_frontier_count))) issues.push('decision_lattice_frontier_count');
+  if (!Number.isFinite(Number(report.metrics?.decision_lattice_rejected_alternative_count))) issues.push('decision_lattice_rejected_alternative_count');
+  if (!report.metrics?.decision_lattice_scoring_formula) issues.push('decision_lattice_scoring_formula');
+  if (report.metrics?.decision_lattice_valid !== true) issues.push('decision_lattice_valid');
   if (!report.proof_field || !validateProofFieldReport(report.proof_field).ok) issues.push('proof_field');
+  else {
+    const lattice = report.proof_field.decision_lattice;
+    if (report.metrics.decision_lattice_selected_path !== lattice?.selected_path?.id) issues.push('decision_lattice_selected_path_mismatch');
+    if (Number(report.metrics.decision_lattice_frontier_count) !== Number(lattice?.frontier?.expanded_order?.length || 0)) issues.push('decision_lattice_frontier_count_mismatch');
+    if (Number(report.metrics.decision_lattice_rejected_alternative_count) !== Number(lattice?.rejected_alternatives?.length || 0)) issues.push('decision_lattice_rejected_alternative_count_mismatch');
+    if (report.metrics.decision_lattice_scoring_formula !== lattice?.scoring_formula) issues.push('decision_lattice_scoring_formula_mismatch');
+  }
   if (!report.pipeline_plan || !validatePipelinePlan(report.pipeline_plan).ok) issues.push('pipeline_plan');
   if (!report.recommendation?.mode) issues.push('recommendation');
   return { ok: issues.length === 0, issues };

package/src/core/pipeline.mjs

@@ -135,11 +135,32 @@ export function validatePipelinePlan(plan = {}) {
   if (!Array.isArray(plan.stages) || !plan.stages.length) issues.push('stages');
   if (!Array.isArray(plan.verification) || !plan.verification.length) issues.push('verification');
   if (!plan.route_economy?.mode) issues.push('route_economy');
+  const routeEconomyLatticeIssues = validateRouteEconomyDecisionLattice(plan.route_economy, plan.proof_field);
+  if (routeEconomyLatticeIssues.length) issues.push(...routeEconomyLatticeIssues.map((issue) => `route_economy.decision_lattice:${issue}`));
   if (plan.no_unrequested_fallback_code !== true || !plan.invariants?.includes('no_unrequested_fallback_code')) issues.push('fallback_guard');
   if (!plan.next_actions?.length) issues.push('next_actions');
   return { ok: issues.length === 0, issues };
 }
 
+function validateRouteEconomyDecisionLattice(routeEconomy = {}, proof = {}) {
+  const lattice = routeEconomy.decision_lattice;
+  if (!lattice) return [];
+  const issues = [];
+  if (routeEconomy.report_only !== true || routeEconomy.mode !== 'report_only') issues.push('requires_report_only_route_economy');
+  if (lattice.report_only !== true) issues.push('report_only');
+  if (!lattice.selected_path) issues.push('selected_path');
+  if (!Number.isFinite(Number(lattice.selected_f_score))) issues.push('selected_f_score');
+  if (!Number.isFinite(Number(lattice.frontier_count)) || Number(lattice.frontier_count) < 1) issues.push('frontier_count');
+  if (!Number.isFinite(Number(lattice.rejected_alternatives_count))) issues.push('rejected_alternatives_count');
+  if (proof?.attached && proof.decision_lattice) {
+    const source = proof.decision_lattice;
+    if (lattice.selected_path !== source.selected_path?.id) issues.push('selected_path_mismatch');
+    if (Number(lattice.frontier_count) !== Number(source.frontier?.expanded_order?.length || 0)) issues.push('frontier_count_mismatch');
+    if (Number(lattice.rejected_alternatives_count) !== Number(source.rejected_alternatives?.length || 0)) issues.push('rejected_alternatives_count_mismatch');
+  }
+  return issues;
+}
+
 function normalizeAmbiguity(value = {}, route) {
   const required = value.required ?? !CLARIFICATION_BYPASS_ROUTES.has(route?.id);
   const slots = Number(value.slots || 0);
@@ -173,7 +194,8 @@ function normalizeProofField(report) {
     contract_clarity: report.contract_clarity || null,
     workflow_complexity: report.workflow_complexity || null,
     team_trigger_matrix: report.team_trigger_matrix || null,
-    verification_stage_cache: report.verification_stage_cache || null
+    verification_stage_cache: report.verification_stage_cache || null,
+    decision_lattice: report.decision_lattice || null
   };
 }
 
@@ -199,6 +221,13 @@ function routeEconomyPlan(proof = {}) {
     team_trigger_count: triggers.length,
     active_team_triggers: triggers,
     verification_stage_cache_key: proof.verification_stage_cache?.cache_key || null,
+    decision_lattice: proof.decision_lattice ? {
+      selected_path: proof.decision_lattice.selected_path?.id || null,
+      selected_f_score: proof.decision_lattice.selected_path?.cost?.f ?? null,
+      frontier_count: proof.decision_lattice.frontier?.expanded_order?.length || 0,
+      rejected_alternatives_count: proof.decision_lattice.rejected_alternatives?.length || 0,
+      report_only: proof.decision_lattice.report_only === true
+    } : null,
     deletion_policy: 'do_not_delete_or_skip_pipeline_stages_until_report_only_metrics_are_calibrated'
   };
 }

package/src/core/proof-field.mjs

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { nowIso, readText, rel, runProcess, sha256, writeJsonAtomic } from './fsx.mjs';
+import { buildDecisionLatticeReport, validateDecisionLatticeReport } from './decision-lattice.mjs';
 
 export const PROOF_FIELD_SCHEMA_VERSION = 1;
 export const FAST_LANE_MIN_SCORE = 0.75;
@@ -88,6 +89,20 @@ export async function buildProofField(root, opts = {}) {
   const verificationStageCache = verificationStageCachePlan({ sourceHash, changedFiles, verification: fastLane.verification });
   const simplicity = outcomeScorecard({ intent, changedFiles, selectedCones, risk, negativeWork, fastLane, workflowComplexity });
   const executionLane = executionLaneDecision({ fastLane, simplicity, workflowComplexity, teamTriggerMatrix });
+  const decisionLattice = normalizeDecisionLatticeReport(await buildDecisionLatticeReport({
+    intent,
+    changed_files: changedFiles,
+    proof_cones: selectedCones,
+    risk,
+    contract_clarity: contractClarity,
+    workflow_complexity: workflowComplexity,
+    team_trigger_matrix: teamTriggerMatrix,
+    verification_stage_cache: verificationStageCache,
+    simplicity_scorecard: simplicity,
+    fast_lane_decision: fastLane,
+    execution_lane: executionLane,
+    scoring_formula: 'simplicity_scorecard.score + contract_clarity.score - workflow_complexity.score - active_team_trigger_penalty'
+  }));
   return {
     schema_version: PROOF_FIELD_SCHEMA_VERSION,
     generated_at: nowIso(),
@@ -102,6 +117,7 @@ export async function buildProofField(root, opts = {}) {
     workflow_complexity: workflowComplexity,
     team_trigger_matrix: teamTriggerMatrix,
     verification_stage_cache: verificationStageCache,
+    decision_lattice: decisionLattice,
     simplicity_scorecard: simplicity,
     execution_lane: executionLane,
     proof_cones: selectedCones,
@@ -133,6 +149,8 @@ export function validateProofFieldReport(report = {}) {
   if (!Number.isFinite(Number(report.workflow_complexity?.score))) issues.push('workflow_complexity');
   if (!Array.isArray(report.team_trigger_matrix?.triggers)) issues.push('team_trigger_matrix');
   if (report.verification_stage_cache?.report_only !== true || !report.verification_stage_cache?.cache_key) issues.push('verification_stage_cache');
+  const latticeValidation = validateDecisionLatticeReport(report.decision_lattice);
+  if (!latticeValidation.ok) issues.push(`decision_lattice:${latticeValidation.issues.join('|')}`);
   if (!report.execution_lane?.lane) issues.push('execution_lane');
   if (report.execution_lane?.lane === SPEED_LANE_POLICY.fast_lane && report.execution_lane?.score < FAST_LANE_MIN_SCORE) issues.push('execution_lane_score');
   if (!Array.isArray(report.proof_cones)) issues.push('proof_cones');
@@ -158,12 +176,25 @@ export async function proofFieldFixture() {
       outcome_rubric_present: report.outcome_rubric.length === OUTCOME_RUBRIC.length,
       adversarial_lenses_present: report.outcome_rubric.every((item) => item.adversarial_lens) && report.simplicity_scorecard.criteria.every((item) => item.adversarial_lens),
       route_economy_present: report.contract_clarity?.report_only === true && report.workflow_complexity?.report_only === true && report.team_trigger_matrix?.report_only === true && report.verification_stage_cache?.report_only === true,
+      decision_lattice_present: validateDecisionLatticeReport(report.decision_lattice).ok,
+      decision_lattice_report_only: report.decision_lattice?.report_only === true,
+      decision_lattice_selected_path: Boolean(report.decision_lattice?.selected_path?.id),
+      decision_lattice_frontier_present: Array.isArray(report.decision_lattice?.frontier?.expanded_order) && report.decision_lattice.frontier.expanded_order.length > 0,
+      decision_lattice_rejections_present: Array.isArray(report.decision_lattice?.rejected_alternatives),
+      decision_lattice_scoring_formula_present: Boolean(report.decision_lattice?.scoring_formula),
       simplicity_score_usable: Number(report.simplicity_scorecard?.score) >= FAST_LANE_MIN_SCORE,
       execution_fast_lane_selected: report.execution_lane?.lane === SPEED_LANE_POLICY.fast_lane
     }
   };
 }
 
+function normalizeDecisionLatticeReport(report = {}) {
+  return {
+    ...report,
+    scoring_formula: report.scoring_formula || report.research_basis?.scoring_formula || null
+  };
+}
+
 async function gitChangedFiles(root) {
   const result = await runProcess('git', ['diff', '--name-only', 'HEAD', '--'], { cwd: root, timeoutMs: 10000, maxOutputBytes: 128 * 1024 });
   if (result.code !== 0) return [];