@ngockhoale/ukit 2.7.13 → 3.0.0

package/templates/.claude/ukit/runtime/execution-ledger.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
 import path from 'node:path';
@@ -482,7 +483,7 @@ function compactReceipt(receipt) {
     kind: receipt.kind,
     success: receipt.success,
   };
-  for (const key of ['toolName', 'toolUseId', 'file', 'command', 'exitCode', 'scope', 'error']) {
+  for (const key of ['toolName', 'toolUseId', 'file', 'command', 'exitCode', 'scope', 'error', 'verdict']) {
     if (receipt[key] !== undefined && receipt[key] !== null && receipt[key] !== '') {
       compact[key] = receipt[key];
     }
@@ -490,6 +491,139 @@ function compactReceipt(receipt) {
   return compact;
 }
 
+// --- Typed verdicts (SPEC-typed-verdicts §2) -----------------------------------
+// One optional verdict record rides the ledger entry — additive, no new store.
+// kind: 'live-verified' | 'test-verified' | 'check-only' | 'blocked' | 'failed'.
+// Currency is proven by headSha + baseSha + patch-id, not by commit messages or a
+// green check from an older SHA.
+const VERDICT_KINDS = new Set(['live-verified', 'test-verified', 'check-only', 'blocked', 'failed']);
+const VERDICT_SATISFYING_KINDS = new Set(['test-verified', 'live-verified']);
+const MAX_VERDICT_HISTORY = 8;
+
+function gitOutput(args, cwd) {
+  try {
+    const out = execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    });
+    return String(out).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// A diff whose changed paths are all tests/docs/lint-format config is
+// stale-but-recoverable: one rebuild at current head restores currency.
+const RECOVERABLE_DIFF_PATH = /(^|\/)(docs\/|[^/]*\.md$)|\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(tests?|specs?|__tests__)\/|(?:^|\/)\.?eslint|\.prettierrc|biome\.json|\.editorconfig|tsconfig.*\.json$/i;
+
+function isRecoverableDiffPath(filePath) {
+  return RECOVERABLE_DIFF_PATH.test(String(filePath || '').replace(/\\/g, '/'));
+}
+
+// `git diff` names changed files in `diff --git a/<old> b/<new>` headers — parse them
+// instead of spending a third git call on --name-only.
+function diffChangedPaths(diffText) {
+  const paths = new Set();
+  for (const line of String(diffText || '').split('\n')) {
+    const match = line.match(/^diff --git a\/(.+) b\/(.+)$/);
+    if (match) {
+      paths.add(match[1]);
+      paths.add(match[2]);
+    }
+  }
+  return [...paths];
+}
+
+function gitPatchId(diffText) {
+  if (!diffText) return null;
+  try {
+    const out = execFileSync('git', ['patch-id', '--stable'], {
+      input: diffText,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore'],
+      timeout: 5000,
+    });
+    return String(out).trim().split(/\s+/)[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+// SPEC §2.2 — is this verdict still valid at the current head?
+// Returns { status, current, headSha } where status is one of:
+//   'current' | 'stale' | 'stale-recoverable' | 'untracked' (no git / no sha data).
+// Cost: one `rev-parse` fast path; when head moved, one `git diff` + one `patch-id`.
+export function verdictCurrent(verdict, { cwd = process.cwd() } = {}) {
+  if (!verdict || typeof verdict !== 'object') {
+    return { status: 'untracked', current: false, headSha: null };
+  }
+  const currentHead = gitOutput(['rev-parse', 'HEAD'], cwd);
+  if (!currentHead) {
+    // No git repo (or git unavailable): currency cannot be proven either way —
+    // null-safe per spec non-goals; do not invent staleness on lanes without git.
+    return { status: 'untracked', current: true, headSha: null };
+  }
+  if (!verdict.headSha) {
+    return { status: 'untracked', current: true, headSha: currentHead };
+  }
+  if (verdict.headSha === currentHead) {
+    return { status: 'current', current: true, headSha: currentHead };
+  }
+  // Head moved. With no base/patch-id recorded there is nothing to compare — stale.
+  if (!verdict.baseSha || !verdict.patchId) {
+    return { status: 'stale', current: false, headSha: currentHead };
+  }
+  const diff = gitOutput(['diff', `${verdict.baseSha}..${currentHead}`], cwd);
+  const patchId = gitPatchId(diff);
+  if (patchId && patchId === verdict.patchId) {
+    // Rebase/reorder only — same patch, still current.
+    return { status: 'current', current: true, headSha: currentHead };
+  }
+  // Recoverability is judged on the delta SINCE the verdict (headSha..HEAD): when
+  // only tests/docs/lint-config moved, one rebuild at current head restores currency.
+  const delta = gitOutput(['diff', `${verdict.headSha}..${currentHead}`], cwd);
+  const changed = diffChangedPaths(delta);
+  if (changed.length > 0 && changed.every(isRecoverableDiffPath)) {
+    return { status: 'stale-recoverable', current: false, headSha: currentHead };
+  }
+  return { status: 'stale', current: false, headSha: currentHead };
+}
+
+// Mint the verdict record for a verification receipt. Explicit payload fields win
+// (a hook or subagent can attest its own kind/verifier); otherwise the kind is
+// derived from the command shape — test runners prove `test-verified`, a run that
+// only type-checks/lints is honestly `check-only`.
+const TEST_RUNNER_COMMAND = /(?:^|\s)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$)|(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+test(?:\s|$)/i;
+
+function mintVerificationVerdict(receipt, payload, projectRoot) {
+  const supplied = payload?.verdict && typeof payload.verdict === 'object' ? payload.verdict : {};
+  const cwd = projectRoot || payload?.cwd || process.cwd();
+  const headSha = supplied.headSha || gitOutput(['rev-parse', 'HEAD'], cwd);
+  const baseSha = supplied.baseSha !== undefined
+    ? supplied.baseSha
+    : (headSha ? gitOutput(['merge-base', 'HEAD', '@{upstream}'], cwd) : null);
+  let patchId = supplied.patchId || null;
+  if (!patchId && headSha && baseSha) {
+    patchId = gitPatchId(gitOutput(['diff', `${baseSha}..${headSha}`], cwd));
+  }
+  let kind = supplied.kind;
+  if (!VERDICT_KINDS.has(kind)) {
+    if (receipt.success !== true) kind = 'failed';
+    else kind = TEST_RUNNER_COMMAND.test(receipt.command || '') ? 'test-verified' : 'check-only';
+  }
+  return {
+    kind,
+    evidence: supplied.evidence || receipt.command || null,
+    verifier: supplied.verifier || 'self',
+    headSha: headSha || null,
+    baseSha: baseSha || null,
+    patchId,
+    ts: supplied.ts || new Date().toISOString(),
+  };
+}
+
 /**
  * Target-aware matching between a receipt's file and a routed expected file. Both sides
  * may disagree about absolute vs relative spelling (hook payloads carry absolute paths,
@@ -735,6 +869,11 @@ function carriedEvidenceLedger(fresh, current) {
     verificationAttempted: fresh.verificationAttempted || current.verificationAttempted === true,
     verificationSucceeded: fresh.verificationSucceeded || current.verificationSucceeded === true,
     verificationFailed: fresh.verificationFailed || current.verificationFailed === true,
+    // Typed verdicts belong to the same logical request: a re-key must keep the latest
+    // verdict and its history or the gate would re-demand verification mid-request.
+    verdict: fresh.verdict || current.verdict || null,
+    verdictHistory: [...(current.verdictHistory || []), ...(fresh.verdictHistory || [])]
+      .slice(-MAX_VERDICT_HISTORY),
     receipts: [...(current.receipts || [])].slice(-MAX_RECEIPTS),
     // The continuation budget belongs to the same logical request (promptKey), so a re-key
     // must keep counting toward the cap. Resetting it here made the cap unreachable and the
@@ -800,6 +939,8 @@ function freshLedger(payload, routeState, harness) {
     verificationFailed: false,
     receipts: [],
     blocker: null,
+    verdict: null,
+    verdictHistory: [],
     continuationCount: 0,
     noProgressCount: 0,
     lastProgressDigest: null,
@@ -1181,6 +1322,13 @@ function applyReceiptToLedger(ledger, receipt, { vibecode = false } = {}) {
       );
       if (banked) next.bankedVerifications = banked;
     }
+    // SPEC-typed-verdicts §2.1: the latest verdict is the ledger's verdict; superseded
+    // ones are kept in a bounded history so "one rebuild restores currency" has data.
+    if (receipt.verdict && typeof receipt.verdict === 'object') {
+      const history = Array.isArray(next.verdictHistory) ? next.verdictHistory : [];
+      next.verdictHistory = [...history, ...(next.verdict ? [next.verdict] : [])].slice(-MAX_VERDICT_HISTORY);
+      next.verdict = receipt.verdict;
+    }
 
     // Verification-loop tracking. `terminalShellCommandUnit` gives the loop identity:
     // the same failing check rerun — `setup && yarn test` and `yarn test 2>&1 | tail`
@@ -1420,6 +1568,10 @@ export async function recordExecutionReceipt({
       const matched = routedCommands.find((cmd) => matchesRoutedCommand(receipt.command, cmd));
       receipt.scope = matched ? 'targeted' : 'broad';
     }
+    // SPEC-typed-verdicts §2.1: every verification receipt mints a typed verdict record
+    // (kind/evidence/verifier/headSha/baseSha/patchId/ts). Explicit payload.verdict
+    // fields win so a hook or subagent verifier can attest its own kind and identity.
+    receipt.verdict = mintVerificationVerdict(receipt, payload, projectRoot);
   } else {
     // Untracked tool: no event, no lock, no write — same as the old unlocked early return.
     return { rejected: true, eventId: null };
@@ -1482,10 +1634,21 @@ function requiredEvidence(state = {}) {
   return [...new Set(routeSummary.completionState?.missingEvidence || [])];
 }
 
-function evidenceSatisfied(evidence, ledger = {}, state = {}) {
+function evidenceSatisfied(evidence, ledger = {}, state = {}, { cwd } = {}) {
   const routeSummary = state?.routeSummary || {};
   if (evidence === 'write-evidence') return ledger.writeSucceeded === true;
   if (evidence === 'verification-evidence') {
+    // SPEC-typed-verdicts §2.3: when a verdict record exists it governs — only a
+    // CURRENT test-verified/live-verified verdict satisfies the gate. A stale or
+    // check-only verdict does not, no matter what the legacy booleans say. With no
+    // verdict record the boolean path below is unchanged (backward compatible).
+    const verdicts = [ledger.verdict, ...(ledger.verdictHistory || [])].filter(Boolean);
+    if (verdicts.length > 0) {
+      return verdicts.some(
+        (verdict) => VERDICT_SATISFYING_KINDS.has(verdict.kind)
+          && verdictCurrent(verdict, { cwd }).current === true,
+      );
+    }
     // WS-C: when the route names concrete verification commands, only a receipt that ran
     // one of them counts — an unrelated `yarn test` no longer satisfies the gate.
     // F-15: unless the user explicitly requested/approved a broad suite — the same
@@ -1513,7 +1676,7 @@ function evidenceSatisfied(evidence, ledger = {}, state = {}) {
   return false;
 }
 
-function recoveryInstruction(missingEvidence, ledger = {}, routeSummary = {}) {
+function recoveryInstruction(missingEvidence, ledger = {}, routeSummary = {}, { cwd } = {}) {
   let instruction = null;
   if (missingEvidence.includes('write-evidence')) {
     if (!ledger.sourceSucceeded) {
@@ -1524,9 +1687,23 @@ function recoveryInstruction(missingEvidence, ledger = {}, routeSummary = {}) {
       instruction = 'Make the smallest correct Edit/Write now; do not end after more read-only analysis.';
     }
   } else if (missingEvidence.includes('verification-evidence')) {
-    if (ledger.verificationFailed) {
+    // SPEC-typed-verdicts §2.3: a verdict record names its own recovery — stale gets
+    // the stale-specific instruction, check-only names the missing surface. These
+    // take precedence over the generic "run verification" wording below.
+    if (!instruction && ledger.verdict && typeof ledger.verdict === 'object') {
+      if (ledger.verdict.kind === 'check-only') {
+        instruction = 'check-only does not satisfy this lane; verify on the real surface (run the feature / inspect the artifact).';
+      } else {
+        const currency = verdictCurrent(ledger.verdict, { cwd });
+        if (currency.current !== true) {
+          const sha = ledger.verdict.headSha ? String(ledger.verdict.headSha).slice(0, 12) : 'unknown';
+          instruction = `Verification verdict is stale (head moved since ${sha}). Re-run the routed verification at current head.`;
+        }
+      }
+    }
+    if (!instruction && ledger.verificationFailed) {
       instruction = 'Use the latest failed verification output, fix the failure, and rerun targeted verification.';
-    } else {
+    } else if (!instruction) {
       const routedCommands = routedVerificationCommands(routeSummary);
       if (routedCommands.length > 0 && ledger.verificationSucceeded && !ledger.targetedVerificationSucceeded) {
         instruction = `Verification ran but did not match the routed plan (${routedCommands.slice(0, 3).join('; ')}). Run one of those and inspect its result before stopping.`;
@@ -1549,7 +1726,7 @@ function recoveryInstruction(missingEvidence, ledger = {}, routeSummary = {}) {
   return instruction ?? 'Complete the current routed milestone before stopping.';
 }
 
-export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
+export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
   const routeSummary = state?.routeSummary || {};
   // Explicit vibecode autonomy: the user asked UKit to run one prompt to a finished result,
   // so the completion gate keeps pushing instead of releasing at the continuation cap.
@@ -1620,7 +1797,7 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
     || ledger.requestKey === state.requestKey
     || (ledger.promptKey && evidencePromptKey(state) === ledger.promptKey);
   const effectiveLedger = sameRequest ? ledger : {};
-  const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger, state));
+  const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger, state, { cwd }));
   if (missingEvidence.length === 0) {
     // Silent success: the route is present and every required evidence is satisfied. Marked
     // `complete` so the CLI dispatch recognizes it BEFORE the loud final else — otherwise a
@@ -1742,7 +1919,7 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
   }
 
   const finalAttempt = !vibecode && continuationCount === MAX_CONTINUATIONS - 1;
-  const instruction = recoveryInstruction(missingEvidence, effectiveLedger, routeSummary);
+  const instruction = recoveryInstruction(missingEvidence, effectiveLedger, routeSummary, { cwd });
   return {
     continue: true,
     missingEvidence,
@@ -1886,7 +2063,7 @@ async function runEvaluateStop() {
     return;
   }
 
-  const result = evaluateCompletion({ state, ledger });
+  const result = evaluateCompletion({ state, ledger, cwd: projectRoot });
 
   // A reentrant Stop (Claude Code re-fires Stop after this hook already blocked once) is
   // gated exactly like any other Stop: while evidence is still missing it blocks again with
@@ -1937,6 +2114,58 @@ async function main() {
 // Compare real paths: a project under a symlinked root (macOS /tmp -> /private/tmp, or a
 // symlinked work directory) makes import.meta.url resolve to the real path while argv[1]
 // keeps the symlinked spelling. Without realpath the guard silently never runs the CLI.
+// --- decision log (v3, pstack show-me-your-work port) -------------------------
+// Append-only TSV at .ukit/storage/decisions.tsv. Columns: ts / phase / decision /
+// why / evidence / result. Evidence is a pointer (SHA, file:line, artifact path),
+// never prose. A wrong call is a NEW row whose result supersedes — there is no
+// update/delete path by design.
+
+const DECISION_LOG_HEADER = 'ts\tphase\tdecision\twhy\tevidence\tresult';
+
+function decisionLogPath(projectRoot) {
+  return path.join(projectRoot, '.ukit', 'storage', 'decisions.tsv');
+}
+
+// Cells may carry attacker-influenceable strings (PR titles, filenames). A cell
+// starting with = + - @ executes as a formula when a reviewer opens the TSV in a
+// spreadsheet — prefix with ' (pstack log.sh does the same).
+function sanitizeDecisionCell(value) {
+  let cell = String(value ?? '').replace(/[\t\n\r]+/g, ' ').trim();
+  if (/^[=+\-@]/.test(cell)) cell = `'${cell}`;
+  return cell;
+}
+
+export async function appendDecision(projectRoot, {
+  phase = '',
+  decision = '',
+  why = '',
+  evidence = '',
+  result = '',
+  now = Date.now(),
+} = {}) {
+  if (!projectRoot || !decision) return { appended: false, reason: 'invalid-decision' };
+  const target = decisionLogPath(projectRoot);
+  const row = [
+    new Date(now).toISOString(),
+    phase,
+    decision,
+    why,
+    evidence,
+    result,
+  ].map(sanitizeDecisionCell).join('\t');
+  try {
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    let needsHeader = true;
+    try {
+      needsHeader = (await fs.stat(target)).size === 0;
+    } catch {}
+    await fs.appendFile(target, `${needsHeader ? `${DECISION_LOG_HEADER}\n` : ''}${row}\n`, 'utf8');
+    return { appended: true, path: target };
+  } catch (error) {
+    return { appended: false, reason: error?.message ?? String(error) };
+  }
+}
+
 function isDirectRun() {
   const argvPath = process.argv[1];
   if (!argvPath) return false;

package/templates/ukit/README.md

@@ -12,3 +12,34 @@ The compact-pressure state is used to trigger conservative auto-compact behavior
 - preserve active task, rules, decisions, and current code focus first
 
 This folder is generated by `ukit install` and is safe to keep local-only.
+
+## Two layers
+
+UKit state lives at two levels:
+
+- **Project level** — `<project>/.ukit/` (this folder). Refreshed by every
+  `ukit install` / `ukit update`; treat it as generated.
+- **User level** — `~/.ukit/` (your home directory). Seeded once by
+  `ukit install` and **never overwritten** afterwards — every user item is
+  `mergeStrategy: skip`. Per `manifests/platform.user.yaml` the seeds are:
+  `README.md`, `storage/config.json`, `playbooks/bug-fix.md`,
+  `playbooks/issue-implementation.md`.
+
+Precedence (per key / per id):
+
+- **Config**: built-in defaults < `~/.ukit/storage/config.json` <
+  `.ukit/storage/config.json` — project wins every key. `version` and `agent`
+  are project-managed and ignored in the user file.
+- **Playbooks**: built-in < `~/.ukit/playbooks/` < `.ukit/playbooks/` — a
+  project playbook with the same id overrides the user's for that project.
+- **Memory**: project records ++ user records — the user record wins on id
+  collision.
+
+CLI surface:
+
+- `ukit memory --user [v2] <list|add|get|update|forget|stats>` — operate on the
+  user-level memory store (`~/.ukit/storage/memory/v2/records.json`).
+- `ukit playbook list` / `ukit playbook show <id>` — inspect resolved playbooks
+  across all three levels.
+- `ukit doctor` — prints a `User layer:` health line (presence, config state,
+  playbook and memory-record counts).

package/templates/ukit/storage/config.json

@@ -83,6 +83,16 @@
     "enabled": true,
     "defaultModel": "claude-sonnet-5"
   },
+  "routing": {
+    "routeSchema": { "stage": "off" }
+  },
+  "modelRoles": {
+    "code": "code",
+    "judgment": "smart",
+    "review-panel": ["smart", "code", "lite"],
+    "fast-worker": "lite",
+    "vision": "vision"
+  },
   "orchestration": {
     "enabled": true,
     "orchestratorModel": "claude-sonnet-5",

package/templates/user/README.md

@@ -0,0 +1,21 @@
+# UKit User Layer (~/.ukit)
+
+This folder is **yours — ukit never overwrites it**. `ukit install` / `ukit update`
+seed missing files only (`mergeStrategy: skip`); anything already here is left
+untouched, so edits, additions, and deletions are safe.
+
+## Layout
+
+- `storage/config.json` — personal defaults merged **under** the project config
+  (`.ukit/storage/config.json`). Project keys win; `version` and `agent` are
+  project-managed and stripped from this file at load.
+- `playbooks/<id>.md` — personal workflow policies. Frontmatter `id` + `lanes`,
+  then the markdown body.
+- `storage/memory/` — cross-project memory (`v2/records.json`), written by
+  `ukit memory --user`.
+
+## Precedence
+
+Playbooks: built-in < user (`~/.ukit/playbooks/`) < project (`.ukit/playbooks/`).
+Config: user defaults < project config (per-key merge).
+Memory: project records ++ user records (user wins on id collision).

package/templates/user/playbooks/bug-fix.md

@@ -0,0 +1,18 @@
+---
+id: bug-fix
+lanes: [find-cause]
+---
+You own this bug. Reproduce, root-cause, fix, verify on the same surface.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Reproduce it yourself on the matching surface — ask the user only with a stated
+   reason the surface cannot reach the target.
+2. Binary-search the cause: form candidate hypotheses, rule them out until one
+   survives; confirm the surviving mechanism with runtime evidence.
+3. Make the smallest fix that kills the mechanism — belt-and-suspenders that
+   "might help" is a hypothesis, not a fix; it does not ship.
+4. Verify on the same surface: the original repro now passes. "Inconclusive" or
+   wrong-surface is not a pass. A unit test shows branch behavior, not bug absence.
+5. Keep the rejected hypotheses — one line each, why ruled out.
+Reply: what was broken, root cause, fix, how verified — paste failing-then-passing
+repro output verbatim.
+Ask the human only for: irreversible writes, a genuine preference call no experiment settles, or a real dead end. Everything else: do it, report it.

package/templates/user/playbooks/issue-implementation.md

@@ -0,0 +1,14 @@
+---
+id: issue-implementation
+lanes: [local-build, shared-edit, map-impact]
+---
+You own this task. Normalize the goal, build, verify.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. State the done condition as a checkable predicate before writing code.
+2. Find the established analog — follow it unless you name why it does not fit.
+3. Name the data shape and its organizing structure before writing logic.
+4. Implement the smallest change satisfying the predicate.
+5. Verify against the predicate on the real artifact — not "it compiles".
+6. Widen once: check the impact surface the route named, no broader.
+Reply: what changed, the predicate, the evidence it now holds.
+Ask the human only for: irreversible writes, a genuine preference call no experiment settles, or a real dead end. Everything else: do it, report it.

package/templates/user/storage/config.json

@@ -0,0 +1,16 @@
+{
+  "modelRoles": {
+    "code": "code",
+    "judgment": "smart",
+    "review-panel": ["smart", "code", "lite"],
+    "fast-worker": "lite",
+    "vision": "vision"
+  },
+  "autonomy": {
+    "level": "balanced"
+  },
+  "compact": {
+    "tokenThreshold": 150000,
+    "hardCapTokens": 500000
+  }
+}