changeledger 0.8.0 → 0.10.0

package/src/fix.mjs

@@ -0,0 +1,127 @@
+// Mechanical, unambiguous repairs for format defects `changeledger check` can
+// only diagnose. Pure text-in/text-out — no IO. The `fix` command (and its
+// `--dry-run`) do the reading/writing; `check` reuses `hasFixableDefects` to
+// print a hint without duplicating the repair rules.
+//
+// Repairs (in order, per `## Plan` task line):
+//   1. Checkbox marker variants `[ x ]` / `[X]` -> `[x]`.
+//   2. A `(CRn) — verify: X` block reordered to `; verify: X (CRn)`.
+//   3. A resolution suffix using a single hyphen instead of an em dash.
+//   4. A near-ISO resolution timestamp normalized to strict ISO 8601 UTC.
+//
+// A task whose CR reference is not declared in `## Specification` is left
+// completely untouched and reported under `manual` — the defect requires
+// judgment (unknown criterion), not a mechanical rewrite.
+import { parseChange } from './change.mjs';
+
+const TASK_LINE = /^(\s*-\s)\[([^\]]*)\](\s+)(.*)$/;
+const REORDERED_VERIFY = /^(.*?)\s*\(([^)]*\bCR\d+[^)]*)\)\s*—\s*verify:\s*(.+)$/;
+const NEAR_ISO = /^(\d{4})-(\d{1,2})-(\d{1,2})[ T](\d{1,2}):(\d{2}):(\d{2})(?:\.\d+)?(Z)?$/;
+
+export function computeFixes(text) {
+  const criteria = new Set(parseChange(text).criteria ?? []);
+  const lines = text.split('\n');
+  const outLines = [];
+  const applied = [];
+  const manual = [];
+  let inPlan = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i];
+    if (/^##\s+/.test(rawLine)) {
+      inPlan = /^##\s+Plan\s*$/.test(rawLine);
+      outLines.push(rawLine);
+      continue;
+    }
+    if (!inPlan) {
+      outLines.push(rawLine);
+      continue;
+    }
+    const result = fixTaskLine(rawLine, criteria, i + 1);
+    outLines.push(result.line);
+    applied.push(...result.applied);
+    manual.push(...result.manual);
+  }
+
+  return { text: outLines.join('\n'), applied, manual, changed: applied.length > 0 };
+}
+
+export function hasFixableDefects(text) {
+  if (typeof text !== 'string') return false;
+  try {
+    return computeFixes(text).changed;
+  } catch {
+    return false;
+  }
+}
+
+function fixTaskLine(rawLine, declaredCR, lineNo) {
+  const m = rawLine.match(TASK_LINE);
+  if (!m) return { line: rawLine, applied: [], manual: [] };
+  const [, prefix, markerRaw, gap, restRaw] = m;
+
+  // A task referencing an undeclared criterion needs judgment, not a rewrite —
+  // leave the entire line untouched.
+  const referenced = restRaw.match(/CR\d+/g) ?? [];
+  const unknown = [...new Set(referenced.filter((cr) => !declaredCR.has(cr)))];
+  if (unknown.length) {
+    return {
+      line: rawLine,
+      applied: [],
+      manual: [`line ${lineNo}: references unknown criterion ${unknown.join(', ')}`],
+    };
+  }
+
+  const applied = [];
+  let rest = restRaw;
+
+  let marker = markerRaw;
+  if (marker.trim().toLowerCase() === 'x' && marker !== 'x') {
+    marker = 'x';
+    applied.push(`line ${lineNo}: checkbox marker normalized to [x]`);
+  }
+  const state = marker === 'x' ? 'done' : marker === '!' ? 'blocked' : 'todo';
+
+  const reorder = rest.match(REORDERED_VERIFY);
+  if (reorder) {
+    const [, target, crBlock, verify] = reorder;
+    rest = `${target.trim()}; verify: ${verify.trim()} (${crBlock.trim()})`;
+    applied.push(`line ${lineNo}: reordered verify suffix before (${crBlock.trim()})`);
+  }
+
+  // The resolution suffix is the LAST separator: a description may legitimately
+  // contain an em dash, so only a hyphen sitting after every em dash is a defect.
+  if (
+    (state === 'done' || state === 'blocked') &&
+    rest.lastIndexOf(' - ') > rest.lastIndexOf(' — ')
+  ) {
+    const hyphenIdx = rest.lastIndexOf(' - ');
+    if (hyphenIdx !== -1) {
+      rest = `${rest.slice(0, hyphenIdx)} — ${rest.slice(hyphenIdx + 3)}`;
+      applied.push(`line ${lineNo}: resolution suffix hyphen normalized to em dash`);
+    }
+  }
+
+  if (state === 'done') {
+    const dash = rest.lastIndexOf(' — ');
+    if (dash !== -1) {
+      const suffix = rest.slice(dash + 3);
+      const normalized = normalizeIsoTimestamp(suffix);
+      if (normalized && normalized !== suffix) {
+        rest = `${rest.slice(0, dash)} — ${normalized}`;
+        applied.push(`line ${lineNo}: resolution timestamp normalized to ISO 8601 UTC`);
+      }
+    }
+  }
+
+  if (!applied.length) return { line: rawLine, applied: [], manual: [] };
+  return { line: `${prefix}[${marker}]${gap}${rest}`, applied, manual: [] };
+}
+
+function normalizeIsoTimestamp(text) {
+  const m = text.trim().match(NEAR_ISO);
+  if (!m) return null;
+  const [, y, mo, d, h, mi, s] = m;
+  const pad = (v) => v.padStart(2, '0');
+  return `${y}-${pad(mo)}-${pad(d)}T${pad(h)}:${mi}:${s}Z`;
+}

package/src/framing.mjs

@@ -0,0 +1,30 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { packageRoot } from './paths.mjs';
+
+// Single source of the installed version and the anti-truncation sentinels, so
+// `context`, `agent-prompt` and `agent-context` share framing and never diverge
+// through independent copies.
+export const VERSION = JSON.parse(
+  fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'),
+).version;
+
+const TRUNCATION_SUFFIX = 'if this line is missing, the output was truncated: stop and re-run';
+
+// `kind` names the payload (e.g. "CONTEXT", "AGENT PROMPT"); `meta` is the
+// already-formatted descriptor (e.g. "mode: implement — v0.8.0").
+export function beginSentinel(kind, meta) {
+  return `===== CHANGELEDGER ${kind} BEGIN — ${meta} =====`;
+}
+
+export function endSentinel(kind) {
+  return `===== CHANGELEDGER ${kind} END — ${TRUNCATION_SUFFIX} =====`;
+}
+
+// 12-hex-char content revision for a composed body. Callers hash the body
+// only (never the BEGIN/END lines themselves) so the revision never
+// references its own framing.
+export function contentRev(body) {
+  return crypto.createHash('sha256').update(body).digest('hex').slice(0, 12);
+}

package/src/git.mjs

@@ -6,8 +6,56 @@ import { execFileSync } from 'node:child_process';
 
 const SEP = String.fromCharCode(31); // ASCII unit separator — safe field delimiter
 
-function defaultRun(args, cwd) {
-  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+// Repo-location env vars git itself exports while running a hook (e.g. this
+// project's own pre-commit). Left inherited, a child `git` call would silently
+// target the hook's repo/worktree instead of the given `cwd` — strip them so
+// every invocation stays anchored on `cwd`.
+const GIT_LOCATION_ENV_VARS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_COMMON_DIR',
+  'GIT_CEILING_DIRECTORIES',
+];
+
+function sanitizedEnv() {
+  const env = { ...process.env };
+  for (const key of GIT_LOCATION_ENV_VARS) delete env[key];
+  return env;
+}
+
+// Exported so other commands (e.g. `changeledger commit`) share the same
+// GIT_* sanitization instead of re-implementing it.
+export function defaultRun(args, cwd) {
+  return execFileSync('git', args, {
+    cwd,
+    env: sanitizedEnv(),
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+}
+
+// Run variant for mutating git commands (e.g. `commit`), where git's stderr is
+// the only clue to a failure (failed hook, nothing staged, missing identity,
+// lock). Pipes stderr and, on failure, throws an Error whose message includes
+// the captured diagnostic. Query paths keep `defaultRun` and degrade silently.
+export function mutatingRun(args, cwd) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      env: sanitizedEnv(),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (e) {
+    const detail = [e.stderr, e.stdout]
+      .map((s) => (typeof s === 'string' ? s.trim() : ''))
+      .filter(Boolean)
+      .join('\n');
+    throw new Error(detail ? `${e.message}\n${detail}` : e.message, { cause: e });
+  }
 }
 
 // Local git identity (`git config user.name`), or '' if unavailable. Tolerant.
@@ -39,6 +87,75 @@ export function ownerHandle(cwd, run = defaultRun, ghRun = defaultGhRun) {
   return githubLogin(ghRun) || gitUser(cwd, run);
 }
 
+// Detects the branch `changeledger check --commits` should diff against when
+// no base is given: the remote's HEAD if configured, else a local `main` or
+// `master`. Throws with actionable guidance if neither is resolvable.
+export function defaultBaseBranch(repoRoot, run = defaultRun) {
+  try {
+    const out = run(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], repoRoot);
+    const name = out.trim().replace(/^origin\//, '');
+    if (name) return name;
+  } catch {
+    // no configured remote HEAD — fall through to local candidates
+  }
+  for (const candidate of ['main', 'master']) {
+    try {
+      run(['rev-parse', '--verify', '--quiet', candidate], repoRoot);
+      return candidate;
+    } catch {
+      // candidate branch does not exist locally — try the next one
+    }
+  }
+  throw new Error(
+    'Could not detect a default branch (no origin/HEAD, main, or master); pass one explicitly: changeledger check --commits <base>',
+  );
+}
+
+// Commits in `range` (e.g. `main..HEAD`): sha, subject and whether each is a
+// merge (more than one parent) — the git metadata `check --commits` lints.
+export function commitsInRange(repoRoot, range, run = defaultRun) {
+  let out;
+  try {
+    out = run(['log', range, `--pretty=format:%H${SEP}%P${SEP}%s`], repoRoot);
+  } catch (e) {
+    throw new Error(`git log failed for range "${range}": ${e.message}`);
+  }
+  return out
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const [sha, parents, subject] = line.split(SEP);
+      return {
+        sha,
+        subject,
+        isMerge: parents.trim().split(/\s+/).filter(Boolean).length > 1,
+      };
+    });
+}
+
+// A well-formed marker is one or more `[#id]` groups, each separated by a
+// single space, terminating the subject — the canonical multi-id shape is
+// separate brackets (`[#A] [#B]`), never a comma list in one bracket.
+const MARKER_RE = /(\[#[^\]\s]+\])(\s\[#[^\]\s]+\])*$/;
+export function hasCommitMarker(subject) {
+  return MARKER_RE.test(subject.trim());
+}
+
+// Lints `range`: every non-merge commit must carry a well-formed `[#id]`
+// marker, except `chore(release)` prep commits. Returns only the violations
+// (sha + subject); never throws for a clean range.
+export function lintCommitRange(repoRoot, range, run = defaultRun) {
+  const commits = commitsInRange(repoRoot, range, run);
+  const violations = [];
+  for (const c of commits) {
+    if (c.isMerge) continue;
+    if (/^chore\(release\):/.test(c.subject)) continue;
+    if (!hasCommitMarker(c.subject))
+      violations.push({ sha: c.sha.slice(0, 7), subject: c.subject });
+  }
+  return violations;
+}
+
 export function gitRefs(repoRoot, id, run = defaultRun) {
   const refs = { commits: [], branches: [] };
   if (!id) return refs;

package/src/lifecycle.mjs

@@ -1,7 +1,7 @@
 // The change lifecycle as an explicit, testable graph — the single authority on
 // which status moves are legal. Shared by the CLI (`changeledger status`) and the viewer
 // so both decide validity the same way. The viewer layers an extra human-only
-// policy on top (approval plus final acceptance/rejection); it never relaxes
+// policy on top (approval plus final acceptance); it never relaxes
 // this graph.
 
 export const CANONICAL_STATUSES = [
@@ -21,7 +21,7 @@ export const CANONICAL_STATUSES = [
 // `in-validation` is the universal human gate before done. Review or validation
 // may route back to in-progress, while review may also block. `discarded` is a
 // terminal tombstone reachable only before either closing gate. `done` has one
-// policy-gated human reopen edge; generic agent commands do not own it.
+// policy-gated provisional reopen edge; generic status commands do not own it.
 const TRANSITIONS = {
   draft: ['approved', 'discarded'],
   approved: ['in-progress', 'discarded'],

package/src/metrics.mjs

@@ -70,6 +70,29 @@ function avg(nums) {
   return nums.length ? Math.round(nums.reduce((a, b) => a + b, 0) / nums.length) : 0;
 }
 
+// Nearest-rank percentile over an ascending-sorted array; 0 for an empty input
+// so callers never divide by zero or render NaN.
+function percentile(sorted, p) {
+  if (!sorted.length) return 0;
+  const rank = Math.min(sorted.length, Math.max(1, Math.ceil((p / 100) * sorted.length)));
+  return sorted[rank - 1];
+}
+
+// Count of `review → in-progress` verdicts (the `fail --retry` outcome) — the
+// same event grammar as lifecycle transitions, filtered to the implicit
+// review-verdict shape so an explicit `status:` move or a validation verdict
+// isn't miscounted as a retry.
+function reviewRetryCount(change) {
+  let count = 0;
+  for (const line of logBody(change).split('\n')) {
+    const event = parseLogEvent(line);
+    if (event && !event.explicit && event.from === 'in-review' && event.to === 'in-progress') {
+      count++;
+    }
+  }
+  return count;
+}
+
 export function computeMetrics(changes = [], { now } = {}) {
   const nowIso = now ?? '9999-12-31T23:59:59Z';
 
@@ -80,12 +103,17 @@ export function computeMetrics(changes = [], { now } = {}) {
   const aging = [];
   let blockedMs = 0;
   const byType = new Map(); // type → { closed, cycles:[] }
+  const byOwner = new Map(); // owner → { closed, cycles:[] }
+  let reviewRetries = 0;
 
   for (const c of changes) {
     const status = c.frontmatter?.status;
     const type = c.frontmatter?.type ?? 'unknown';
+    const owner = c.frontmatter?.owner || 'unassigned';
     const created = c.frontmatter?.created;
 
+    reviewRetries += reviewRetryCount(c);
+
     if (ACTIVE.includes(status)) wip[status] = (wip[status] ?? 0) + 1;
 
     const segs = statusTimeline(c, nowIso);
@@ -114,6 +142,11 @@ export function computeMetrics(changes = [], { now } = {}) {
         bt.closed += 1;
         bt.cycles.push(cycleMs);
         byType.set(type, bt);
+
+        const bo = byOwner.get(owner) ?? { closed: 0, cycles: [] };
+        bo.closed += 1;
+        bo.cycles.push(cycleMs);
+        byOwner.set(owner, bo);
       }
     }
   }
@@ -130,17 +163,26 @@ export function computeMetrics(changes = [], { now } = {}) {
   const byTypeArr = [...byType.entries()]
     .map(([type, v]) => ({ type, closed: v.closed, avgCycleMs: avg(v.cycles) }))
     .sort((a, b) => b.closed - a.closed);
+  const byOwnerArr = [...byOwner.entries()]
+    .map(([owner, v]) => ({ owner, closed: v.closed, avgCycleMs: avg(v.cycles) }))
+    .sort((a, b) => b.closed - a.closed);
+  const validationWaitMs = timeInStatus.find((t) => t.state === 'in-validation')?.avgMs ?? 0;
 
   return {
     count: perChange.length,
     avgCycleMs: avg(cycles),
     medianCycleMs: median(cycles),
+    p50CycleMs: percentile(cycles, 50),
+    p85CycleMs: percentile(cycles, 85),
     perChange,
     throughput,
     timeInStatus,
     wip,
     aging: aging.sort((a, b) => b.ms - a.ms),
     blockedMs,
+    validationWaitMs,
+    reviewRetries,
     byType: byTypeArr,
+    byOwner: byOwnerArr,
   };
 }

package/src/search.mjs

@@ -0,0 +1,162 @@
+// Deterministic lexical search over changes and specs. No embeddings, no
+// network — a fixed-boost term-frequency score (title x3, headings/CR x2,
+// body x1) with a stable tie-break, so repeated runs are byte-for-byte
+// identical. See change 20260711-103758.
+
+const ACCENTS = /[̀-ͯ]/g;
+const CR_HEADING = /^###\s+CR\d+.*$/gm;
+const MARKDOWN_HEADING = /^#{1,6}\s+(.+)$/gm;
+
+// Lowercase + strip diacritics so "búsqueda" and "busqueda" match the same term.
+export function normalize(text) {
+  return (text ?? '').normalize('NFD').replace(ACCENTS, '').toLowerCase();
+}
+
+function tokenize(query) {
+  return normalize(query)
+    .split(/\s+/)
+    .map((t) => t.trim())
+    .filter(Boolean);
+}
+
+function countOccurrences(haystackNormalized, term) {
+  if (!term) return 0;
+  let count = 0;
+  let idx = 0;
+  for (;;) {
+    const found = haystackNormalized.indexOf(term, idx);
+    if (found === -1) break;
+    count++;
+    idx = found + term.length;
+  }
+  return count;
+}
+
+// Locates the first case/accent-insensitive occurrence of `term` in `rawText`
+// and returns a short surrounding snippet, or null when there is no match.
+function findSnippet(rawText, term, span = 40) {
+  const normalized = normalize(rawText);
+  const idx = normalized.indexOf(term);
+  if (idx === -1) return null;
+  const start = Math.max(0, idx - span);
+  const end = Math.min(rawText.length, idx + term.length + span);
+  const prefix = start > 0 ? '…' : '';
+  const suffix = end < rawText.length ? '…' : '';
+  return `${prefix}${rawText.slice(start, end).replace(/\s+/g, ' ').trim()}${suffix}`;
+}
+
+// Splits a change's stages into a heading/CR bucket (boost x2) and a body
+// bucket (boost x1). CR heading lines are lifted out of the body so they are
+// scored once, at the heading boost, not twice.
+function changeHeadingsAndBody(stages) {
+  const headings = [];
+  const bodyParts = [];
+  for (const stage of stages) {
+    headings.push(stage.heading);
+    const crHeadings = stage.body.match(CR_HEADING) ?? [];
+    headings.push(...crHeadings);
+    bodyParts.push(stage.body.replace(CR_HEADING, ''));
+  }
+  return { headings: headings.join('\n'), body: bodyParts.join('\n\n') };
+}
+
+// Same split for a spec's free-form body: its own `#`..`######` headings
+// (boost x2) versus the remaining prose (boost x1).
+function specHeadingsAndBody(body) {
+  const headings = [...body.matchAll(MARKDOWN_HEADING)].map((m) => m[1]);
+  const stripped = body.replace(MARKDOWN_HEADING, '');
+  return { headings: headings.join('\n'), body: stripped };
+}
+
+// Builds the searchable corpus from a loaded repo (see repo.mjs `loadRepo`):
+// every change — including archived ones — and every spec, reduced to the
+// fields the scorer needs.
+export function buildCorpus({ changes, specs }) {
+  const fromChanges = changes.map((c) => {
+    const { headings, body } = changeHeadingsAndBody(c.stages);
+    return {
+      ref: `#${c.frontmatter.id}`,
+      kind: 'change',
+      title: c.frontmatter.title ?? '',
+      status: c.frontmatter.status ?? null,
+      type: c.frontmatter.type ?? null,
+      headings,
+      body,
+    };
+  });
+
+  const fromSpecs = specs.map((s) => {
+    const slug = s.name.replace(/\.md$/, '');
+    const { headings, body } = specHeadingsAndBody(s.body);
+    return {
+      ref: `spec:${slug}`,
+      kind: 'spec',
+      title: s.frontmatter.title ?? slug,
+      status: null,
+      type: null,
+      headings,
+      body,
+    };
+  });
+
+  return [...fromChanges, ...fromSpecs];
+}
+
+function scoreDocument(doc, terms) {
+  const titleN = normalize(doc.title);
+  const headingsN = normalize(doc.headings);
+  const bodyN = normalize(doc.body);
+  let score = 0;
+  for (const term of terms) {
+    score += countOccurrences(titleN, term) * 3;
+    score += countOccurrences(headingsN, term) * 2;
+    score += countOccurrences(bodyN, term) * 1;
+  }
+  return score;
+}
+
+function buildSnippet(doc, terms) {
+  for (const field of [doc.title, doc.headings, doc.body]) {
+    for (const term of terms) {
+      const snippet = findSnippet(field, term);
+      if (snippet) return snippet;
+    }
+  }
+  return '';
+}
+
+// Scores and ranks `docs` (as produced by `buildCorpus`) against `query`.
+// On an equal score, a spec sorts before a change — specs are the current
+// persistent truth, so that's what an agent should read first. Among equals
+// of the same kind, ties break by `ref` descending so the same repo state
+// always yields the same byte-for-byte output.
+export function searchDocuments(docs, query, { limit = 10, type, status } = {}) {
+  const terms = tokenize(query);
+  if (!terms.length) return [];
+
+  const hits = [];
+  for (const doc of docs) {
+    if (type && doc.type !== type) continue;
+    if (status && doc.status !== status) continue;
+    const score = scoreDocument(doc, terms);
+    if (score <= 0) continue;
+    hits.push({
+      ref: doc.ref,
+      kind: doc.kind,
+      title: doc.title,
+      type: doc.type,
+      status: doc.status,
+      score,
+      snippet: buildSnippet(doc, terms),
+    });
+  }
+
+  hits.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    if (a.kind !== b.kind) return a.kind === 'spec' ? -1 : 1;
+    if (a.ref === b.ref) return 0;
+    return a.ref < b.ref ? 1 : -1;
+  });
+
+  return hits.slice(0, limit);
+}

package/src/viewer/domain.mjs

@@ -130,7 +130,7 @@ export function changeStatus(projects, { project, id, status, reason }) {
   }
   try {
     if (current === 'draft' && status === 'approved') {
-      applyStatusCmd(id, status, proj.path);
+      applyStatusCmd(id, status, proj.path, { actor: 'human' });
     } else if (current === 'in-validation' && status === 'done') {
       applyValidation(id, 'pass', {}, proj.path);
     } else if (current === 'in-validation' && status === 'in-progress') {
@@ -407,7 +407,7 @@ export function previewConfigMigration(projects, id, rev) {
   return {
     code: 200,
     body: {
-      summary: `Config migration 0 → ${SUPPORTED_SCHEMA_VERSION} (dry run)`,
+      summary: `Config migration ${migrationResult.fromVersion} → ${SUPPORTED_SCHEMA_VERSION} (dry run)`,
       changes: migrationResult.changes,
       yaml: migrationResult.yaml,
     },