changeledger 0.9.0 → 0.10.0

package/src/viewer/public/view-renderers.js

@@ -1,8 +1,49 @@
 import { cssIdent } from './security.js';
 import { html, nothing, svg } from './templates.js';
+import { splitGraduationHistory } from './view-parts.js';
 
 const clip = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
 
+// Plain-text excerpt for spec cards: strips the leading graduation-history
+// blockquote, picks the first prose paragraph (skipping headings, remaining
+// blockquotes and code fences) and removes inline Markdown syntax. The result
+// is interpolated as text (lit-html), never as HTML.
+function firstProseParagraph(text) {
+  const paragraphs = String(text ?? '').split(/\n\s*\n/);
+  for (const para of paragraphs) {
+    const trimmed = para.trim();
+    if (!trimmed) continue;
+    if (/^#{1,6}\s/.test(trimmed)) continue;
+    if (/^>/.test(trimmed)) continue;
+    if (/^```/.test(trimmed)) continue;
+    return trimmed;
+  }
+  return '';
+}
+
+function stripMarkdown(text) {
+  return text
+    .replace(/`([^`]*)`/g, '$1')
+    .replace(/\*\*([^*]+)\*\*/g, '$1')
+    .replace(/__([^_]+)__/g, '$1')
+    .replace(/\*([^*]+)\*/g, '$1')
+    .replace(/_([^_]+)_/g, '$1')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+export function specExcerpt(body, maxLen = 160) {
+  const { after } = splitGraduationHistory(body);
+  return clip(stripMarkdown(firstProseParagraph(after)), maxLen);
+}
+
+// Most recently updated truth first.
+export function sortSpecsByUpdated(specs) {
+  const time = (s) => Date.parse(s?.updated || '') || 0;
+  return [...specs].sort((a, b) => time(b) - time(a));
+}
+
 export function graphSvg(changes) {
   if (!changes.length) {
     return html`<p class="empty">No changes match the current filters.</p>`;
@@ -79,17 +120,19 @@ export function graphSvg(changes) {
 }
 
 export function specsListHtml(specs, fmtDateTime) {
-  return specs.length
-    ? specs.map(
-        (s, i) => html`<div class="spec-card" data-i=${i}>
-          <div class="spec-title">${s.title}</div>
-          <div class="card-meta">
-            <span title=${s.updated || ''}>${fmtDateTime(s.updated)}</span>
-            ${(s.tags || []).map((t) => html`<span class="pill">${t}</span>`)}
-          </div>
-        </div>`,
-      )
-    : html`<p class="empty">No specs yet. Truth graduates here as changes complete.</p>`;
+  if (!specs.length) {
+    return html`<p class="empty">No specs yet. Truth graduates here as changes complete.</p>`;
+  }
+  return sortSpecsByUpdated(specs).map(
+    (s, i) => html`<div class="spec-card" data-i=${i}>
+      <div class="spec-title">${s.title}</div>
+      <div class="card-meta">
+        <span title=${s.updated || ''}>${fmtDateTime(s.updated)}</span>
+        ${(s.tags || []).map((t) => html`<span class="pill">${t}</span>`)}
+      </div>
+      <p class="spec-excerpt">${specExcerpt(s.body)}</p>
+    </div>`,
+  );
 }
 
 export function fmtDuration(ms) {
@@ -111,15 +154,86 @@ function barRows(items, label, value, fmt = (v) => v) {
   );
 }
 
-export function metricsHtml(metrics = {}) {
+// Hand-rolled SVG bar chart for throughput: one bar per day, a date label and
+// the numeric count both drawn as text so the value is visible without a
+// tooltip (no charting dependency — same precedent as `graphSvg`).
+function throughputSvg(tp) {
+  if (!tp.length) return html`<p class="empty">No closed changes yet.</p>`;
+
+  const width = 640;
+  const height = 180;
+  const padTop = 22;
+  const padBottom = 30;
+  const padSide = 12;
+  const plotWidth = Math.max(1, width - padSide * 2);
+  const plotHeight = Math.max(1, height - padTop - padBottom);
+  const max = Math.max(1, ...tp.map((t) => t.count));
+  const slot = plotWidth / tp.length;
+  const barWidth = Math.max(2, Math.min(48, slot - 8));
+
+  const bars = tp.map((t, i) => {
+    const barHeight = (t.count / max) * plotHeight;
+    const x = padSide + i * slot + (slot - barWidth) / 2;
+    const y = height - padBottom - barHeight;
+    return svg`<g class="tp-bar">
+        <rect class="tp-rect" x=${x} y=${y} width=${barWidth} height=${barHeight}></rect>
+        <text class="tp-value" x=${x + barWidth / 2} y=${Math.max(12, y - 6)} text-anchor="middle">${t.count}</text>
+        <text class="tp-date" x=${x + barWidth / 2} y=${height - padBottom + 16} text-anchor="middle">${t.date}</text>
+      </g>`;
+  });
+
+  return html`<svg
+    class="throughput-svg"
+    viewBox=${`0 0 ${width} ${height}`}
+    height=${height}
+    role="img"
+    aria-label="Throughput per day"
+  >
+    <line
+      class="tp-axis"
+      x1=${padSide}
+      y1=${height - padBottom}
+      x2=${width - padSide}
+      y2=${height - padBottom}
+    ></line>
+    ${bars}
+  </svg>`;
+}
+
+function metricsTable(rows, columnLabel, labelOf) {
+  return rows.length
+    ? html`<table class="grid">
+        <thead>
+          <tr><th>${columnLabel}</th><th>Closed</th><th>Avg cycle</th></tr>
+        </thead>
+        <tbody>
+          ${rows.map(
+            (r) => html`<tr>
+              <td>${labelOf(r)}</td>
+              <td class="mono">${r.closed}</td>
+              <td class="mono">${fmtDuration(r.avgCycleMs)}</td>
+            </tr>`,
+          )}
+        </tbody>
+      </table>`
+    : html`<p class="empty">No closed changes yet.</p>`;
+}
+
+export function metricsHtml(metrics = {}, totalChanges = 0) {
+  if (!totalChanges) {
+    return html`<p class="empty">No changes match the current filters.</p>`;
+  }
+
   const wip = metrics.wip || {};
   const wipTotal = Object.values(wip).reduce((a, b) => a + b, 0);
   const cards = [
     ['Closed', metrics.count ?? 0],
-    ['Avg cycle', fmtDuration(metrics.avgCycleMs)],
-    ['Median cycle', fmtDuration(metrics.medianCycleMs)],
+    ['Cycle p50', fmtDuration(metrics.p50CycleMs)],
+    ['Cycle p85', fmtDuration(metrics.p85CycleMs)],
     ['WIP', wipTotal],
     ['Blocked time', fmtDuration(metrics.blockedMs)],
+    ['Validation wait', fmtDuration(metrics.validationWaitMs)],
+    ['Review retries', metrics.reviewRetries ?? 0],
   ].map(
     ([label, val]) =>
       html`<div class="metric-card">
@@ -140,15 +254,6 @@ export function metricsHtml(metrics = {}) {
       )
     : html`<p class="empty">No data yet.</p>`;
 
-  const tp = metrics.throughput || [];
-  const tpBars = tp.length
-    ? barRows(
-        tp,
-        (t) => html`<span class="mono">${t.date}</span>`,
-        (t) => t.count,
-      )
-    : html`<p class="empty">No closed changes yet.</p>`;
-
   const aging = metrics.aging || [];
   const agingRows = aging.length
     ? html`<ul class="git-commits">
@@ -160,32 +265,39 @@ export function metricsHtml(metrics = {}) {
     : html`<p class="empty">Nothing in progress.</p>`;
 
   const byType = metrics.byType || [];
-  const typeRows = byType.length
-    ? html`<table class="grid">
-        <thead>
-          <tr><th>Type</th><th>Closed</th><th>Avg cycle</th></tr>
-        </thead>
-        <tbody>
-          ${byType.map(
-            (t) => html`<tr>
-              <td><span class="type-tag" style=${`--type-color: var(--${cssIdent(t.type)})`}>${t.type}</span></td>
-              <td class="mono">${t.closed}</td>
-              <td class="mono">${fmtDuration(t.avgCycleMs)}</td>
-            </tr>`,
-          )}
-        </tbody>
-      </table>`
-    : html`<p class="empty">No closed changes yet.</p>`;
+  const typeRows = metricsTable(
+    byType,
+    'Type',
+    (t) =>
+      html`<span class="type-tag" style=${`--type-color: var(--${cssIdent(t.type)})`}>${t.type}</span>`,
+  );
+
+  const byOwner = metrics.byOwner || [];
+  const ownerRows = metricsTable(byOwner, 'Owner', (o) =>
+    o.owner === 'unassigned' ? html`<span class="muted">Unassigned</span>` : o.owner,
+  );
 
   return html`
     <div class="metrics-cards">${cards}</div>
-    ${wipChips.length ? html`<div class="detail-meta">${wipChips}</div>` : nothing}
-    <h3 class="metrics-h">Avg time in status (lead time per stage)</h3>
-    <div>${leadBars}</div>
-    <h3 class="metrics-h">Throughput (closed per day)</h3>
-    <div>${tpBars}</div>
-    <h3 class="metrics-h">Aging — in progress</h3>
-    ${agingRows}
-    <h3 class="metrics-h">By type</h3>
-    ${typeRows}`;
+    <div class="metrics-grid">
+      <section class="metrics-panel">
+        <h3 class="metrics-h">Throughput (closed per day)</h3>
+        ${throughputSvg(metrics.throughput || [])}
+      </section>
+      <section class="metrics-panel">
+        <h3 class="metrics-h">Avg time in status (lead time per stage)</h3>
+        <div>${leadBars}</div>
+      </section>
+      <section class="metrics-panel">
+        <h3 class="metrics-h">Aging — in progress</h3>
+        ${wipChips.length ? html`<div class="detail-meta">${wipChips}</div>` : nothing}
+        ${agingRows}
+      </section>
+      <section class="metrics-panel">
+        <h3 class="metrics-h">By type</h3>
+        ${typeRows}
+        <h3 class="metrics-h">By owner</h3>
+        ${ownerRows}
+      </section>
+    </div>`;
 }

package/src/viewer/server/router.mjs

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { gitRefs } from '../../git.mjs';
-import { publicDir } from '../../paths.mjs';
+import { packageRoot, publicDir } from '../../paths.mjs';
 import { loadRepoAsync } from '../../repo.mjs';
 import {
   applyConfigMigration,
@@ -49,10 +49,21 @@ function vendorFile(route) {
 const MIME = {
   '.html': 'text/html; charset=utf-8',
   '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
   '.css': 'text/css; charset=utf-8',
   '.json': 'application/json; charset=utf-8',
 };
 
+// The pure metrics module is shared verbatim between the CLI and the browser:
+// the client dynamic-imports it so filtered metrics reuse the exact same
+// computation as the server payload (no reimplementation). `lifecycle.mjs` is
+// its only relative import, so both must be reachable under the same route
+// prefix for the browser's module resolution to find it. Neither file is
+// under `publicDir`; this is a narrow, explicit allowlist rather than opening
+// up the rest of `src/` the way `publicDir` static assets are.
+const SHARED_MODULES_DIR = path.join(packageRoot, 'src');
+const SHARED_MODULES = new Set(['metrics.mjs', 'lifecycle.mjs']);
+
 // Defensive headers for a local-only UI: never sniff types, never cache, and
 // forbid embedding in a frame (clickjacking).
 const SECURITY_HEADERS = {
@@ -215,6 +226,13 @@ export function createRequestListener(cwd, localOnly, token) {
         return;
       }
 
+      if (route.startsWith('/shared/')) {
+        const shared = sharedModuleFile(route);
+        if (shared) send(res, 200, MIME['.mjs'], fs.readFileSync(shared));
+        else send(res, 404, 'text/plain', 'Not found');
+        return;
+      }
+
       const vendor = vendorFile(route);
       if (vendor) {
         if (fs.existsSync(vendor)) send(res, 200, MIME['.js'], fs.readFileSync(vendor));
@@ -239,7 +257,10 @@ export function createRequestListener(cwd, localOnly, token) {
   };
 }
 
-export function staticFile(route) {
+// Resolves `route` to a file under `root`, refusing anything that decodes,
+// resolves, or (post-symlink) realpaths outside of it. Shared by the public
+// static assets and the narrower shared-module allowlist below.
+function assetFile(root, route) {
   let decoded;
   try {
     decoded = decodeURIComponent(route);
@@ -249,16 +270,29 @@ export function staticFile(route) {
   if (decoded.includes('\0')) return null;
 
   const rel = decoded.replace(/^\/+/, '');
-  const file = path.resolve(publicDir, rel);
-  if (!isInsidePath(publicDir, file)) return null;
+  const file = path.resolve(root, rel);
+  if (!isInsidePath(root, file)) return null;
   if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return null;
 
-  const realPublic = fs.realpathSync(publicDir);
+  const realRoot = fs.realpathSync(root);
   const realFile = fs.realpathSync(file);
-  if (!isInsidePath(realPublic, realFile)) return null;
+  if (!isInsidePath(realRoot, realFile)) return null;
   return file;
 }
 
+export function staticFile(route) {
+  return assetFile(publicDir, route);
+}
+
+// Serves only the whitelisted shared modules — never arbitrary files under
+// `src/` — even though containment is checked the same way as public assets.
+export function sharedModuleFile(route) {
+  if (!route.startsWith('/shared/')) return null;
+  const name = route.slice('/shared/'.length);
+  if (!SHARED_MODULES.has(name)) return null;
+  return assetFile(SHARED_MODULES_DIR, `/${name}`);
+}
+
 function isInsidePath(root, target) {
   const rel = path.relative(path.resolve(root), path.resolve(target));
   return rel === '' || (rel && !rel.startsWith('..') && !path.isAbsolute(rel));

package/templates/config.yml

@@ -3,7 +3,7 @@
 
 # Schema version — used to detect and migrate outdated configurations.
 # Run `changeledger config migrate --dry-run` to inspect available migrations.
-schema_version: 1
+schema_version: 2
 
 # Language for generated documentation CONTENT. Structure (headings, keys, enums)
 # is always English. See `changeledger context spec`.
@@ -23,6 +23,7 @@ release:
     audit: none
     refactor: none
     chore: none
+    quick: patch
 
 # Optional Definition of Ready path/command hints. When present, tasks that
 # reference CRs should name at least one target and one verification matching
@@ -58,3 +59,8 @@ types:
     review_required: true
   chore:
     stages: [request, plan]
+  # Small, reversible, single-concern work with no persistent-truth or public
+  # surface impact. If scope grows mid-execution, discard and recreate under
+  # the correct type — see `changeledger context spec`.
+  quick:
+    stages: [request, log]

package/templates/contract/agent-contexts/audit.md

@@ -0,0 +1,22 @@
+# Read-Only Audit Delegate
+
+This is a self-contained delegated context. It replaces the ChangeLedger core
+for this role; do not run `changeledger context` or load another ChangeLedger
+context.
+
+This is a post-review inspection of a change already sitting in
+`in-validation`, waiting for human acceptance. The review gate already ran;
+you do not repeat it and you do not move the change. This role is read-only:
+do not modify files, do not change Git state, do not mutate the ledger, do not
+change status, do not add Log entries, and do not delegate any part of the
+work.
+
+Inspect the selected change, every `CRn`, the actual diff, tests and Git
+history against what the document claims. Contrast criteria, code and
+evidence; note any drift, residue or unresolved risk.
+
+Return findings and evidence only — file:line references, what you confirmed,
+what you could not confirm. Do not decide or state whether the change should
+be accepted, sent back or blocked, and do not name or suggest a lifecycle
+command: that decision belongs to the human waiting at `in-validation`, not to
+this role.

package/templates/contract/agent-prompts/audit.md

@@ -0,0 +1,37 @@
+# Delegation skeleton — role: audit
+
+Fill every `{{placeholder}}` before handing this prompt to the subagent. Delete
+guidance in parentheses. The auditor is a read-only inspection of a change
+already sitting in `in-validation`, waiting for human acceptance; it is not a
+review and never moves the change.
+
+---
+
+You are a READ-ONLY AUDIT delegate. Do not delegate any part of this to
+another agent; execute it yourself.
+
+Why this is delegated: {{reason}} (independent inspection after review already
+passed and the change is waiting for a human at `in-validation`).
+
+Your prompt identifies you as a ChangeLedger delegate. As your only
+ChangeLedger load, run `changeledger agent-context audit {{change_id}}` and
+read it through its END sentinel; do not load the orchestrator core.
+
+Change under audit: {{change_id}}.
+
+Boundaries — expressed by effect, not by tool name: do not modify any file, do
+not change Git state, and do not mutate the ledger. You inspect and report
+only; the review gate already ran, so do not issue a verdict and do not name
+or suggest a lifecycle command.
+
+Expected output: {{expected_output}} (findings and evidence — file:line
+references, what was confirmed, what could not be, and any drift or residue).
+
+Difficulty or risk that set the model choice: {{difficulty_or_risk}}.
+
+Return to the orchestrator or the human waiting at `in-validation` the
+findings and evidence above; you never move the change.
+
+Integration criterion: {{integration}} (how the orchestrator or human uses the
+findings, e.g. it informs the human's accept/reject decision at
+`in-validation`).

package/templates/contract/agent-prompts/implementation.md

@@ -18,6 +18,10 @@ load, run `changeledger agent-context implementation {{change_id}}` and read it
 through its END sentinel; do not load the orchestrator core. It supplies the
 selected change with its acceptance criteria and Plan.
 
+If that command does not resolve the change, or the working tree does not
+contain its document, stop and report instead of proceeding: never reconstruct
+the change from memory, and never continue from another base.
+
 Files you own: {{files}} (the only paths you may modify).
 
 Boundaries — expressed by effect, not by tool name: modify only the files under

package/templates/contract/close.md

@@ -54,7 +54,7 @@ Operational inspection and visibility:
 
 - `changeledger list [--status S] [--type T] [--json]`
 - `changeledger show <id> [--json]`
-- `changeledger archive <id>` / `changeledger unarchive <id>`
+- `changeledger archive <id>` (reversible by manually editing `archived: false` in frontmatter)
 
 Use Mermaid where it communicates persistent relationships better than prose.
 After closure, share a brief retrospective. New work needs a newly authorized

package/templates/contract/core.md

@@ -16,6 +16,11 @@ While the complete core remains available in the active conversation, a new
 human message alone does not trigger a reload. Load only the specialized mode or
 change-id context required by a real task or lifecycle transition.
 
+Every BEGIN line carries `rev:<hash>`. After a compaction, retest a retained
+capture with `changeledger context [mode] --have <rev>` before recapturing it in
+full: a match returns a short `unchanged` confirmation, a mismatch returns the
+complete output, and the very first capture of a session is always full.
+
 1. Work starts with conversation. Read-only investigation may clarify a request,
    but create no change or implementation artifact until there is enough clarity
    to document faithfully **and** the human explicitly authorizes documentation. A direct request such
@@ -38,7 +43,9 @@ change-id context required by a real task or lifecycle transition.
 If no approved or in-progress change applies, do not silently edit repository
 files. Create or update a change, or ask the human whether a purely operational,
 reversible edit with no persistent truth or observable behavior change should be
-done directly. If unsure, document it in ChangeLedger.
+done directly. If unsure, document it in ChangeLedger. For small, reversible,
+single-concern work with observable behavior, use the `quick` type instead of
+bypassing documentation — see `changeledger context spec`.
 
 Humans consume changes in `changeledger view`; write for the rendered view.
 
@@ -51,9 +58,11 @@ transitions and task markers.
 Delegate only with a clear boundary and benefit. Each delegation prompt states at least
 ownership, expected output and integration criterion; the task context carries the full
 prompt contract. Get a complete role skeleton to fill in with `changeledger agent-prompt
-<role>` (investigation | implementation | review). Coding agents must know they share the
-codebase and must not revert others' work. Do not over-shard or overlap write surfaces
-without an explicit integration plan. Size the model to the task's difficulty and risk.
+<role>` (investigation | implementation | review | audit). Coding agents must know they
+share the codebase and must not revert others' work. Do not over-shard or overlap write
+surfaces without an explicit integration plan. Size the model to the task's difficulty
+and risk. `audit` is a read-only post-review inspection of a change already in
+`in-validation`; it never issues a verdict or moves the change.
 
 ## Lifecycle
 
@@ -108,6 +117,7 @@ Prefer structured CLI queries before scanning files:
 
 - `changeledger list --status approved`: find approved changes ready to implement.
 - `changeledger graduate --pending`: find accepted changes whose graduation decision is unresolved.
+- `changeledger search <terms...>`: find related changes (incl. archived) and specs by content before investigating from scratch.
 
 Run `changeledger help` or `changeledger <command> --help` for exact CLI syntax.
 Structure is always English. Each context delivers the effective policy that

package/templates/contract/delegation.md

@@ -50,7 +50,8 @@ Every prompt states:
 - the owned files, area or investigation question;
 - the expected output;
 - the difficulty or risk that informed model choice;
-- the integration criterion.
+- the integration criterion;
+- for roles that write, the expected baseline (branch or commit) the delegate must verify it is working from.
 
 Tell coding delegates they share the codebase: stay inside assigned ownership,
 do not revert others' edits and report overlapping changes instead of silently

package/templates/contract/implement.md

@@ -13,7 +13,9 @@ current throughout execution.
 ## Git protects traceability
 
 Never implement approved changes on `main`, `master`, or `dev`; create or switch
-to a work branch or ask the human before continuing. Inspect the worktree first. If
+to a work branch or ask the human before continuing. When the config declares
+`git.integration_branch`, create change branches from it and integrate the
+finished result into it; `main` stays reserved for releases. Inspect the worktree first. If
 unrelated changes exist, do not include them silently; ask the human whether to
 stash, commit, ignore or include them before changing the worktree.
 
@@ -35,7 +37,16 @@ Commit messages use the canonical shape:
 feat(scope): description [#20260629-234939]
 ```
 
-Use the actual change id and the appropriate conventional type. If shared files make a combined commit
+Use the actual change id and the appropriate conventional type. Referencing more
+than one change is separate brackets, one per id (`[#A] [#B]`) — never a comma
+list inside one bracket. Ledger meta-commits (status, review, log, archive)
+carry the marker like any other commit; only merge commits and `chore(release)`
+prep are exempt. `changeledger commit -m "<type>(<scope>): <desc>" [--id <id>]...`
+composes and creates the commit for you: it resolves the single `in-progress`
+change automatically when `--id` is omitted, and fails without committing if
+that is ambiguous or the subject isn't conventional. `changeledger check
+--commits [<base>]` lints `<base>..HEAD` for the marker with the same
+exemptions — run it before requesting review. If shared files make a combined commit
 unavoidable, record it in Log or the handoff and name every change sharing the
 surface.
 
@@ -53,6 +64,7 @@ Useful mutation commands:
 - `changeledger owner <id> <name|->`
 - `changeledger review <id> pass|fail`
 - `changeledger check [id]`
+- `changeledger commit -m "<type>(<scope>): <desc>" [--id <id>]...`
 
 When implementation and every task are complete, move to `in-review` if the type
 requires independent review by running this ordered gate — do not reconstruct it from memory:

package/templates/contract/spec.md

@@ -38,7 +38,7 @@ headings. Required and optional frontmatter:
 ---
 id: "20260613-134548"
 title: Short, clear title
-type: feature                  # feature | bug | audit | refactor | chore
+type: feature                  # feature | bug | audit | refactor | chore | quick
 status: draft                  # lifecycle value
 created: 2026-06-13T13:45:48Z # full ISO 8601 UTC
 depends_on: []                 # change ids or external project:id refs
@@ -78,11 +78,23 @@ Default activation matrix:
 | audit | ✓ | ✓ | — | — | — | ✓ |
 | refactor | ✓ | — | ✓ | — | ✓ | ✓ |
 | chore | ✓ | — | — | — | ✓ | — |
+| quick | ✓ | — | — | — | — | ✓ |
 
 The configured matrix is authoritative. For bugs, Investigation contains the
 root cause; for audits, it is the core analysis. Proposal includes the chosen
 solution, discarded alternatives and scenarios.
 
+`quick` is a lighter lane for small, reversible, single-concern work that does
+not expand public surface or persistent truth (`specs/`): document only
+Request and Log, ~10-15 lines. It keeps the same human `draft → approved` gate
+and `[#id]` commit marker as any other type, skipping only `in-review`. If
+scope grows mid-execution beyond that eligibility, discard the change and
+recreate it under the correct type instead of continuing under `quick`.
+
+Before writing Investigation, run `changeledger search <terms from the request>`
+and record anything relevant as `depends_on` or a mention — do not rediscover
+work another change or spec already covers.
+
 When a relationship, flow or architecture is clearer visually, use a Mermaid
 block and keep its text as the source; the viewer renders it.
 
@@ -155,6 +167,7 @@ title, stage prose, scenario content and task descriptions.
 - `changeledger check [id]` — validate one change or the repository.
 - `changeledger list [--status S] [--type T] [--json]` — inspect/filter changes.
 - `changeledger show <id> [--json]` — inspect one resolved change.
+- `changeledger search <terms...> [--type T] [--status S] [--json]` — find related changes and specs by content.
 - `changeledger owner <id> <name|->` — set or clear responsibility.
 
 Run `changeledger <command> --help` for exact options; the commands support the