@popovych.co/witness 0.22.0 → 0.23.0

package/README.md

@@ -274,10 +274,10 @@ the wrong file refuses. There are no `WITNESS_*` env vars for configuration.
 | verb | does |
 | --- | --- |
 | `init [--agent claude-code\|pi\|auto]` | scaffold config, principles, journal — one trailer commit; `--agent` also installs that harness's engine, guard and dashboard (idempotent) |
-| `recap [--amend] --file <json>` | validate + persist a scope recap; births the effort journal |
-| `write <id> --effort <e> --meta <json> --body <md>` | validated manifest → spec/plan on disk + journal entry |
-| `diff <spec-id>` | delta since the last realized state (plan pin → empty) |
-| `read <id> [--design] [--outline] [--lines <a>-<b>]` | print a spec/plan/design from the primary root — the read route, since a worktree carries no canon copy; `--outline` names each anchor's line range for fat artifacts |
+| `recap [--amend] --file <json>` | validate + persist a scope recap — class, goals, non-goals, constraints and numbered decisions; births the effort journal |
+| `write <id> --effort <e> --meta <json> --body <md>` | validated manifest → spec/plan on disk + journal entry; a spec's `covers` and `carries` map it to the recap's goals and decisions |
+| `diff <spec-id>` | delta since the last realized state (plan pin → empty), and the decisions that moved since that plan |
+| `read <id> [--design] [--outline] [--lines <a>-<b>] [--decisions]` | print a spec/plan/design from the primary root — the read route, since a worktree carries no canon copy; `--outline` names each anchor's line range for fat artifacts; `--decisions` prints the decisions a spec carries with its effort's constraints and non-goals, or an effort's whole recap |
 | `check` | schema, graph, invariants, needs, trailer audit, probes |
 | `index` | id · summary · status · depends across the canon, then each spec's plans |
 | `satisfy <id> --need <id\|n\|text>` | journal a manual need as met — the spec is never rewritten |

package/dist/abandon.js

@@ -34,10 +34,13 @@ function later(root, a, b) {
 // back under a later commit, whose parent was never the write's — so an amendment read as a create
 // and was deleted, and a create restored another effort's abandoned amendment. And the same bytes
 // written again later, by another effort, are that effort's: who may take them back is the
-// caller's question, asked of this answer.
-export function writeAct(root, id, sha, at = 'HEAD') {
+// caller's question, asked of this answer. `among` narrows the efforts asked (row 198 asks the
+// live ones first).
+export function writeAct(root, id, sha, at = 'HEAD', among) {
     let found;
     for (const effort of effortStreams(root)) {
+        if (among !== undefined && !among.has(effort))
+            continue;
         if (!readStream(root, effort).some((e) => isWrite(e, id, sha)))
             continue;
         for (const { entry, commit } of journalActs(root, effort, at)) {

package/dist/basis.js

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto';
+import { canonicalDecisions, carriedDecisions, decisionsSha } from './decisions.js';
+import { latestRecap } from './journal.js';
+import { effortOf } from './reviewed.js';
+import { canonicalJson, canonicalSha } from './sha.js';
+export function specBasis(root, doc) {
+    const decisions = decisionsSha(carriedDecisions(root, doc)?.decisions ?? []);
+    return { spec: canonicalSha(doc.meta, doc.body), ...(decisions !== undefined ? { decisions } : {}) };
+}
+export function planBasis(plan) {
+    const decisions = plan.meta['decisions-from'];
+    return { spec: String(plan.meta['derives-from']), ...(typeof decisions === 'string' ? { decisions } : {}) };
+}
+// The terms that moved, spec first; [] is fresh. An absent pin equals an absent current term.
+export function basisMoved(pinned, current) {
+    const moved = [];
+    if (pinned.spec !== current.spec)
+        moved.push('spec');
+    if (pinned.decisions !== current.decisions)
+        moved.push('decisions');
+    return moved;
+}
+// The decisions term of a plan's reviewed identity (Builder's call 6): what its parent carries,
+// and for a chore plan its chore's own decisions too, which the critic also reads. Never a pin —
+// a chore's decisions in `decisions-from` would re-queue the parent spec forever (call 4).
+// Undefined when neither carries any, so the identity's bytes are today's (c2).
+export function planDecisionsTerm(root, plan, parent) {
+    const carried = carriedDecisions(root, parent)?.decisions ?? [];
+    const effort = effortOf(root, String(plan.meta.id));
+    const recap = effort === undefined ? undefined : latestRecap(root, effort);
+    const chore = recap?.class === 'chore' ? recap.decisions ?? [] : [];
+    if (chore.length === 0)
+        return decisionsSha(carried);
+    return createHash('sha256').update(canonicalJson({ parent: canonicalDecisions(carried), chore: canonicalDecisions(chore) })).digest('hex');
+}

package/dist/cli.js

@@ -75,7 +75,7 @@ const VERB_USAGE = {
     migrate: 'witness migrate [--dry-run]',
     log: 'witness log <stream> [--all] [--lineage]',
     next: 'witness next',
-    read: 'witness read <id> [--design] [--outline] [--lines <a>-<b>]',
+    read: 'witness read <id> [--design] [--outline] [--lines <a>-<b>] [--decisions]',
     recap: 'witness recap --file <recap.json> [--ask <id>] [--amend]',
     recover: 'witness recover [--complete | --rollback]',
     rename: 'witness rename <old-id> <new-id>',

package/dist/decisions.js

@@ -0,0 +1,118 @@
+import { createHash } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeAct } from './abandon.js';
+import { effortAbandoned, journalRel, latestRecap, readStream, streamIds } from './journal.js';
+import { effortOf, effortWrites } from './reviewed.js';
+import { canonicalJson, canonicalSha } from './sha.js';
+import { kv, list, rows } from './toon.js';
+// Row 198 (Builder's call 2). What a doc carries is what the write that made its CURRENT
+// content said it carries — D168's act, so this adds no second derivation. Two efforts can
+// write identical content with different `carries`; the later act wins, and git is asked only
+// in that rare case. An abandoned effort's act is taken back (D168): while a live effort's write
+// made the same content, the live one carries; content only abandoned writes made is canon of
+// record, and so is what they carried. An id the effort's latest recap no longer holds is
+// history, not carried. A doc no journaled write made (a hand edit, an adopt) carries nothing.
+export function carriedDecisions(root, doc) {
+    const id = String(doc.meta.id);
+    const sha = canonicalSha(doc.meta, doc.body);
+    const index = writerIndex(root);
+    const all = index.writes.get(`${id}\0${sha}`) ?? [];
+    const live = all.filter((w) => !index.abandoned.has(w.effort));
+    const writers = live.length > 0 ? live : all;
+    if (writers.length === 0)
+        return undefined;
+    const effort = writers.length === 1 ? writers[0].effort
+        : writeAct(root, id, sha, 'HEAD', new Set(writers.map((w) => w.effort)))?.effort ?? writers[0].effort;
+    const carries = writers.find((w) => w.effort === effort)?.carries ?? [];
+    const decisions = (index.decisions.get(effort) ?? []).filter((d) => carries.includes(d.id));
+    return { effort, decisions };
+}
+let lastIndex;
+function writerIndex(root) {
+    const ids = streamIds(root);
+    const key = ids.map((id) => {
+        const st = statSync(join(root, journalRel(id)), { throwIfNoEntry: false });
+        return `${id}:${st?.size ?? '-'}:${st?.mtimeMs ?? '-'}`;
+    }).join('\n');
+    if (lastIndex?.root === root && lastIndex.index.key === key)
+        return lastIndex.index;
+    const index = { key, writes: new Map(), decisions: new Map(), abandoned: new Set() };
+    for (const effort of ids) {
+        const entries = readStream(root, effort);
+        if (entries[0]?.t !== 'recap')
+            continue;
+        if (effortAbandoned(entries))
+            index.abandoned.add(effort);
+        const last = new Map();
+        for (const e of entries) {
+            if (e.t === 'recap')
+                index.decisions.set(effort, e.decisions ?? []);
+            else if (e.t === 'write')
+                last.set(`${String(e.artifact)}\0${String(e.sha)}`, (e.carries ?? []));
+        }
+        for (const [k, carries] of last)
+            index.writes.set(k, [...(index.writes.get(k) ?? []), { effort, carries }]);
+    }
+    lastIndex = { root, index };
+    return index;
+}
+const byId = (a, b) => a.id.localeCompare(b.id, undefined, { numeric: true });
+// What a pin reads of a set of decisions: each id with its text, in id order. A recap may reorder
+// them or keep other keys beside the text (validation reads only id and text), and neither is a
+// changed decision — hashing the objects whole re-queued shipped specs with an empty delta.
+export function canonicalDecisions(decisions) {
+    return [...decisions].sort(byId).map(({ id, text }) => ({ id, text }));
+}
+// The pin a plan takes on what its parent carries — undefined for none, so a decision-free
+// basis is exactly the spec sha (c2).
+export function decisionsSha(decisions) {
+    if (decisions.length === 0)
+        return undefined;
+    return createHash('sha256').update(canonicalJson(canonicalDecisions(decisions))).digest('hex');
+}
+// Row 198. What moved in a spec's carried decisions since the base plan was derived: added,
+// then changed, then removed, each by id; a removed row shows the text the plan was derived
+// under. A base plan with no `decisions-from` was derived under none, so all it carries now is
+// added. Undefined when the plan pinned decisions but its write journaled no texts — unknown,
+// never guessed. One derivation for `witness diff` and the plan gate's delta block.
+export function decisionDelta(root, base, spec) {
+    const effort = base.planId === undefined ? undefined : effortOf(root, base.planId);
+    const journaled = effort === undefined ? undefined : effortWrites(root, effort).get(base.planId)?.decisions;
+    const before = journaled ?? (base.decisions === undefined ? [] : undefined);
+    if (before === undefined)
+        return undefined;
+    const now = carriedDecisions(root, spec)?.decisions ?? [];
+    const was = new Map(before.map((d) => [d.id, d.text]));
+    const is = new Set(now.map((d) => d.id));
+    return [
+        ...now.filter((d) => !was.has(d.id)).sort(byId).map((d) => ({ id: d.id, change: 'added', text: d.text })),
+        ...now.filter((d) => was.has(d.id) && was.get(d.id) !== d.text).sort(byId).map((d) => ({ id: d.id, change: 'changed', text: d.text })),
+        ...before.filter((d) => !is.has(d.id)).sort(byId).map((d) => ({ id: d.id, change: 'removed', text: d.text })),
+    ];
+}
+// Row 198. `witness read <spec> --decisions`: what the spec carries and the standing limits of
+// the effort whose write made its content. Every row prints even when empty, so a reader can
+// tell "none" from "not shown". One rendering for the verb and the plan critic's prompt.
+export function decisionLines(root, doc) {
+    const carried = carriedDecisions(root, doc);
+    const recap = carried === undefined ? undefined : latestRecap(root, carried.effort);
+    return [
+        carried === undefined ? 'carried-by: none — no journaled write made this content' : kv('carried-by', carried.effort),
+        ...rows('decisions', ['id', 'text'], carried?.decisions ?? []),
+        ...rows('constraints', ['id', 'text'], recap?.constraints ?? []),
+        ...rows('non_goals', ['id', 'text'], recap?.non_goals ?? []),
+    ];
+}
+// `witness read <effort> --decisions`: the effort's whole latest recap — what a chore plan
+// carries, since a chore writes no spec to carry it (§4.5).
+export function recapLines(recap) {
+    return [
+        `effort: ${recap.effort} · ${recap.class}`,
+        ...rows('goals', ['id', 'text'], recap.goals),
+        ...rows('decisions', ['id', 'text'], recap.decisions ?? []),
+        ...rows('constraints', ['id', 'text'], recap.constraints),
+        ...rows('non_goals', ['id', 'text'], recap.non_goals),
+        list('slices', recap.slices),
+    ];
+}

package/dist/fm.js

@@ -3,7 +3,7 @@ import { dirname } from 'node:path';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { ok, refuse, v } from './refusal.js';
 const FIELD_ORDER = [
-    'id', 'type', 'status', 'summary', 'ui', 'parent', 'derives-from', 'design-from',
+    'id', 'type', 'status', 'summary', 'ui', 'parent', 'derives-from', 'design-from', 'decisions-from',
     'supersedes', 'depends', 'needs', 'criteria', 'steps', 'pr', 'drift', 'design',
 ];
 export function splitDoc(raw) {

package/dist/gates/decompose.js

@@ -1,6 +1,6 @@
 import { ok, refuse, v } from '../refusal.js';
 import { serializeDoc } from '../fm.js';
-import { canonicalJson, canonicalSha } from '../sha.js';
+import { canonicalJson } from '../sha.js';
 import { contextDigest } from '../delta.js';
 import { snapshotFiles } from '../snapshot.js';
 import { latestRecap, streamExists } from '../journal.js';
@@ -8,6 +8,7 @@ import { findCycle, findById } from '../scan.js';
 import { effortReviewedSha, effortSpecs, effortWrites } from '../reviewed.js';
 import { validateDoc } from '../schemas.js';
 import { registerGate } from '../gate.js';
+import { basisMoved, planBasis, specBasis } from '../basis.js';
 function stampsFor(docs) {
     return docs
         .filter((d) => String(d.meta.status) === 'draft')
@@ -47,12 +48,19 @@ registerGate({
             detail: missing.length ? `uncovered goals: ${missing.join(' ')}` : `${goals.length} goals covered` });
         checks.push({ name: 'spec-coverage', ok: orphans.length === 0,
             detail: orphans.length ? `specs covering no goal: ${orphans.join(' ')}` : 'every spec covers ≥ 1 goal' });
+        // Row 198. Every recap decision lands in ≥ 1 spec. No reverse rule: a spec may carry none.
+        const decisions = (recap.decisions ?? []).map((d) => d.id);
+        const carried = new Set(docs.flatMap((d) => writes.get(String(d.meta.id))?.carries ?? []));
+        const uncarried = decisions.filter((d) => !carried.has(d));
+        checks.push({ name: 'decision-coverage', ok: uncarried.length === 0,
+            detail: decisions.length === 0 ? 'the recap carries no decisions'
+                : uncarried.length ? `uncarried decisions: ${uncarried.join(' ')}` : `${decisions.length} decisions carried` });
         const staleChildren = canon.docs
             .filter((p) => p.meta.type === 'plan' && String(p.meta.status) === 'in-progress')
             .filter((p) => docs.some((d) => String(d.meta.id) === String(p.meta.parent)))
             .filter((p) => {
             const parent = findById(canon, String(p.meta.parent));
-            return String(p.meta['derives-from']) !== canonicalSha(parent.meta, parent.body);
+            return basisMoved(planBasis(p), specBasis(root, parent)).length > 0;
         })
             .map((p) => String(p.meta.id));
         checks.push({ name: 'amendment-ack', ok: staleChildren.length === 0,
@@ -68,9 +76,14 @@ registerGate({
         const coverageTable = docs
             .map((d) => `${String(d.meta.id)}: covers ${(writes.get(String(d.meta.id))?.covers ?? []).join(' ') || '(none)'}`)
             .join('\n');
+        // Only when the recap carries decisions, so a decision-free effort's prompt is today's (c2).
+        const decisionTable = decisions.length === 0 ? undefined : docs
+            .map((d) => `${String(d.meta.id)}: carries ${(writes.get(String(d.meta.id))?.carries ?? []).join(' ') || '(none)'}`)
+            .join('\n');
         const promptBody = [
             '### Confirmed scope recap (latest)', canonicalJson(recap),
             '### Goal coverage (journaled)', coverageTable,
+            ...(decisionTable !== undefined ? ['### Decision coverage (journaled)', decisionTable] : []),
             ...docs.flatMap((d) => [`### Spec: ${String(d.meta.id)}`, serializeDoc({ meta: d.meta, body: d.body })]),
         ].join('\n\n');
         const { sha } = effortReviewedSha(root, canon, effort);
@@ -78,7 +91,7 @@ registerGate({
         return ok({
             class: (recap.class ?? 'feature'),
             reviewedSha: sha,
-            ...(tree ? { snapshot: { tree, context: contextDigest(canonicalJson(recap), coverageTable) } } : {}),
+            ...(tree ? { snapshot: { tree, context: contextDigest(canonicalJson(recap), coverageTable, ...(decisionTable !== undefined ? [decisionTable] : [])) } } : {}),
             reviewed: { kind: 'docs', docs: docs.map((d) => ({ id: String(d.meta.id), body: d.body })) },
             promptBody,
             checks,

package/dist/gates/plan.js

@@ -10,6 +10,9 @@ import { effortOf, planPairSha } from '../reviewed.js';
 import { validateDoc } from '../schemas.js';
 import { registerGate } from '../gate.js';
 import { designPending, designStamp } from '../design.js';
+import { basisMoved, planBasis, planDecisionsTerm, specBasis } from '../basis.js';
+import { decisionDelta, decisionLines, recapLines } from '../decisions.js';
+import { rows } from '../toon.js';
 // D167. One derivation for the gate's stamp and `decide`'s: a pass approves a draft and nothing
 // else. Row 95 keeps an in-flight status through a re-author, and a passing re-gate must not
 // take it back — nor stamp a finished plan approved again.
@@ -38,12 +41,20 @@ registerGate({
         const parentOk = plannableParent(parent);
         checks.push({ name: 'parent-approved', ok: parentOk,
             detail: `${String(parent.meta.id)} is ${parentStatus}` });
-        const parentSha = canonicalSha(parent.meta, parent.body);
-        const pin = String(plan.meta['derives-from']);
-        checks.push({ name: 'pin-fresh', ok: pin === parentSha,
-            detail: pin === parentSha
-                ? `pin ${short(parentSha)}`
-                : `derives-from ${short(pin)} but parent is at ${short(parentSha)} — rewrite the plan (witness write re-stamps the pin)` });
+        // Row 198. Fresh iff neither pin moved: the parent's content, nor the decisions it carries.
+        const pinned = planBasis(plan);
+        const current = specBasis(root, parent);
+        const parentSha = current.spec;
+        const moved = basisMoved(pinned, current);
+        const pin7 = (x) => (x === undefined ? 'none' : short(x));
+        const clause = {
+            spec: `derives-from ${short(pinned.spec)} but parent is at ${short(current.spec)} — rewrite the plan (witness write re-stamps the pin)`,
+            decisions: `decisions-from ${pin7(pinned.decisions)} but ${String(parent.meta.id)} carries decisions at ${pin7(current.decisions)} — rewrite the plan (witness write re-stamps the pins)`,
+        };
+        checks.push({ name: 'pin-fresh', ok: moved.length === 0,
+            detail: moved.length === 0
+                ? `pin ${short(parentSha)}${current.decisions !== undefined ? ` · decisions ${short(current.decisions)}` : ''}`
+                : moved.map((m) => clause[m]).join(' · ') });
         if (parent.meta.ui === true) {
             const stamp = designStamp(parent);
             const planPin = plan.meta['design-from'];
@@ -54,19 +65,40 @@ registerGate({
                         : designPending(root, parent) ? `${String(parent.meta.id)} design is stale — re-approve or reconfirm`
                             : `design-from ${short(String(planPin ?? 'absent'))} ≠ current design ${short(stamp.sha)}` });
         }
-        const base = baseForSpec(root, canon, String(parent.meta.id), planId);
+        const parentId = String(parent.meta.id);
+        const base = baseForSpec(root, canon, parentId, planId);
+        // Row 198 (g4). A plan re-queued because only the decisions moved is told what moved: its
+        // delta criteria are empty, so nothing else would check that it realizes the change.
+        const baseMoved = base.kind === 'empty' ? []
+            : basisMoved({ spec: base.sha, ...(base.decisions ? { decisions: base.decisions } : {}) }, current);
+        const delta = baseMoved.includes('decisions') ? decisionDelta(root, base, parent) : undefined;
+        const deltaBase = base.kind === 'empty'
+            ? 'new spec — the delta is the whole spec'
+            : [
+                `previous plan ${base.planId} pinned ${short(base.sha ?? '')} — the plan must realize what changed since`,
+                ...(!baseMoved.includes('decisions') ? []
+                    : delta === undefined ? [`decisions moved since ${base.planId} — witness read ${parentId} --decisions`]
+                        : [`decisions moved since ${base.planId}:`, ...rows('decisions-delta', ['id', 'change', 'text'], delta)]),
+            ].join('\n');
+        // What the parent's slicing settled and its effort's standing limits — shown only when it
+        // holds any, so a plan on a decision-free, limit-free effort reads today's prompt (c2). A
+        // chore plan also reads its chore's whole recap: a chore writes no spec to carry it.
+        const carried = decisionLines(root, parent);
+        const sections = [
+            ...(carried.some((l) => l.startsWith('  ')) ? [`### Decisions ${parentId} carries — witness read ${parentId} --decisions`, carried.join('\n')] : []),
+            ...(recap?.class === 'chore' ? [`### The chore's recap — witness read ${effort} --decisions`, recapLines(recap).join('\n')] : []),
+        ];
         const promptBody = [
-            `### Parent spec: ${String(parent.meta.id)}`, serializeDoc({ meta: parent.meta, body: parent.body }),
-            `### Delta base`, base.kind === 'empty'
-                ? 'new spec — the delta is the whole spec'
-                : `previous plan ${base.planId} pinned ${short(base.sha ?? '')} — the plan must realize what changed since`,
+            `### Parent spec: ${parentId}`, serializeDoc({ meta: parent.meta, body: parent.body }),
+            `### Delta base`, deltaBase,
+            ...sections,
             `### Plan: ${planId}`, serializeDoc({ meta: plan.meta, body: plan.body }),
         ].join('\n\n');
         const tree = snapshotFiles(root, [{ name: `${planId}.md`, content: serializeDoc({ meta: plan.meta, body: plan.body }) }]);
         return ok({
             class: (recap?.class ?? 'feature'),
-            reviewedSha: planPairSha(plan, parent),
-            ...(tree ? { snapshot: { tree, context: contextDigest(parentSha, canonicalJson(base)) } } : {}),
+            reviewedSha: planPairSha(plan, parent, planDecisionsTerm(root, plan, parent)),
+            ...(tree ? { snapshot: { tree, context: contextDigest(parentSha, canonicalJson(base), ...(sections.length ? [sections.join('\n\n')] : [])) } } : {}),
             artifactSha: canonicalSha(plan.meta, plan.body),
             reviewed: {
                 kind: 'docs',
@@ -80,10 +112,10 @@ registerGate({
             stamps: draftApproval(plan),
         });
     },
-    currentSha(_root, canon, _cfg, planId) {
+    currentSha(root, canon, _cfg, planId) {
         const plan = findById(canon, planId);
         const parent = plan ? findById(canon, String(plan.meta.parent)) : undefined;
-        return plan && parent ? planPairSha(plan, parent) : undefined;
+        return plan && parent ? planPairSha(plan, parent, planDecisionsTerm(root, plan, parent)) : undefined;
     },
     upstreamOf(_root, canon, planId) {
         const plan = findById(canon, planId);

package/dist/history.js

@@ -41,5 +41,9 @@ export function baseForSpec(root, canon, specId, excludePlanId) {
     });
     stamped.sort((a, b) => b.at - a.at || String(b.p.meta.id).localeCompare(String(a.p.meta.id)));
     const latest = stamped[0].p;
-    return { kind: 'plan-pin', sha: String(latest.meta['derives-from']), planId: String(latest.meta.id) };
+    const decisions = latest.meta['decisions-from'];
+    return {
+        kind: 'plan-pin', sha: String(latest.meta['derives-from']), planId: String(latest.meta.id),
+        ...(typeof decisions === 'string' ? { decisions } : {}),
+    };
 }

package/dist/reviewed.js

@@ -75,9 +75,12 @@ export function effortWrites(root, effort) {
         if (e.t !== 'write')
             continue;
         const w = e;
-        // D168. Latest write wins for sha and covers, but a revision does not un-create: the effort
-        // created the artifact if any of its writes did.
-        out.set(w.artifact, { sha: w.sha, covers: w.covers, created: w.created ?? out.get(w.artifact)?.created });
+        // D168. Latest write wins for sha, covers and carries, but a revision does not un-create:
+        // the effort created the artifact if any of its writes did.
+        out.set(w.artifact, {
+            sha: w.sha, covers: w.covers, carries: w.carries, decisions: w.decisions,
+            created: w.created ?? out.get(w.artifact)?.created,
+        });
     }
     return out;
 }
@@ -110,14 +113,25 @@ function sha256(parts) {
 export function effortReviewedSha(root, canon, effort) {
     const recap = latestRecap(root, effort);
     const docs = effortSpecs(root, canon, effort);
+    const writes = effortWrites(root, effort);
+    // Row 198 (Builder's call 7). The decision mapping is judged content, so a carries-only
+    // rewrite moves the identity rather than resuming into row 112's `cached` replay — a spec
+    // that carries nothing keeps today's bytes (c2). `covers` keeps the replay row 112 records.
     const lines = docs
-        .map((d) => `${String(d.meta.id)}:${canonicalSha(d.meta, d.body)}`)
+        .map((d) => {
+        const carries = writes.get(String(d.meta.id))?.carries ?? [];
+        return `${String(d.meta.id)}:${canonicalSha(d.meta, d.body)}${carries.length ? `:carries=${carries.join('+')}` : ''}`;
+    })
         .sort();
     return { sha: sha256([canonicalJson(recap ?? {}), '\n', lines.join('\n')]), docs };
 }
-export function planPairSha(plan, parent) {
+// Row 198. `decisions` is the plan's decisions term (basis.ts's `planDecisionsTerm`), taken as a
+// sha so this module never imports decisions.ts: design.ts → reviewed.ts sits inside abandon.ts's
+// import closure, which decisions.ts imports. Undefined hashes exactly today's two parts (c2).
+export function planPairSha(plan, parent, decisions) {
     return sha256([
         `${String(plan.meta.id)}:${canonicalSha(plan.meta, plan.body)}\n`,
         `${String(parent.meta.id)}:${canonicalSha(parent.meta, parent.body)}`,
+        ...(decisions !== undefined ? [`\ndecisions:${decisions}`] : []),
     ]);
 }

package/dist/schemas.js

@@ -73,6 +73,9 @@ export function validateDoc(meta, body) {
         if (meta['design-from'] !== undefined && (typeof meta['design-from'] !== 'string' || !/^[0-9a-f]{64}$/.test(String(meta['design-from'])))) {
             out.push(v('design-from', 'shape', String(meta['design-from']), '64-hex design artifact sha'));
         }
+        if (meta['decisions-from'] !== undefined && (typeof meta['decisions-from'] !== 'string' || !/^[0-9a-f]{64}$/.test(String(meta['decisions-from'])))) {
+            out.push(v('decisions-from', 'shape', String(meta['decisions-from']), '64-hex carried-decisions sha'));
+        }
         out.push(...validateSteps(meta.steps, body));
     }
     if (type === 'principles' && meta.criteria !== undefined) {

package/dist/verbs/check.js

@@ -15,6 +15,7 @@ import { designPending } from '../design.js';
 import { ASK_STREAM, reservedId } from '../ask.js';
 import { runDrift } from '../drift.js';
 import { auditStateCommits, dirtyStatePaths, divergence, primaryRoot, stateDirs, tryGit } from '../gitio.js';
+import { basisMoved, planBasis, specBasis } from '../basis.js';
 import { contentAtSha } from '../history.js';
 import { effortStreams, readStream } from '../journal.js';
 import { sourceTags } from '../matcher.js';
@@ -24,7 +25,6 @@ import { renderRefusal } from '../refusal.js';
 import { pendingDecision } from '../rounds.js';
 import { criteriaExcludes } from '../runner.js';
 import { findById, findCycle, loadCanon, planFinished } from '../scan.js';
-import { canonicalSha } from '../sha.js';
 import { lazyStamp } from '../stamp.js';
 import { kv, rows } from '../toon.js';
 import { pendingTxn } from '../txn.js';
@@ -175,8 +175,11 @@ export async function run(ctx, argv = []) {
         const id = String(plan.meta.id);
         if (String(plan.meta.status) === 'in-progress') {
             const parent = findById(canon, String(plan.meta.parent));
-            if (parent && canonicalSha(parent.meta, parent.body) !== String(plan.meta['derives-from'])) {
-                findings.push(f('warn', 'motion', id, 'mid-flight-amendment', `parent ${String(parent.meta.id)} moved off the pin — ship will re-verify against current content`));
+            const moved = parent ? basisMoved(planBasis(plan), specBasis(root, parent)) : [];
+            if (moved.length > 0) {
+                findings.push(f('warn', 'motion', id, 'mid-flight-amendment', moved.includes('spec')
+                    ? `parent ${String(parent.meta.id)} moved off the pin — ship will re-verify against current content`
+                    : `the decisions ${String(parent.meta.id)} carries moved off the pin — the plan was derived under the old ones · witness diff ${String(parent.meta.id)}`));
             }
             if (!existsSync(worktreePath(root, id))) {
                 findings.push(f('warn', 'motion', id, 'missing-worktree', `witness start ${id} recreates it`));

package/dist/verbs/diff.js

@@ -5,6 +5,8 @@ import { EXIT } from '../cli.js';
 import { serializeDoc } from '../fm.js';
 import { primaryRoot, tryGit } from '../gitio.js';
 import { baseForSpec, contentAtSha } from '../history.js';
+import { basisMoved, specBasis } from '../basis.js';
+import { carriedDecisions, decisionDelta } from '../decisions.js';
 import { renderRefusal, v } from '../refusal.js';
 import { findById, loadCanon } from '../scan.js';
 import { canonicalSha, short, VOLATILE_FIELDS } from '../sha.js';
@@ -37,13 +39,35 @@ export async function run(ctx, argv) {
         ctx.out(kv('base', 'empty (never realized)'));
         ctx.out(kv('sha', short(current)));
         ctx.out('delta: full content is the delta — new spec');
+        const carried = carriedDecisions(root, spec)?.decisions.length ?? 0;
+        if (carried > 0)
+            ctx.out(`decisions: ${carried} carried — all are the delta · witness read ${id} --decisions`);
         return EXIT.OK;
     }
     ctx.out(kv('base', `plan-pin ${base.planId} @ ${short(base.sha)}`));
-    if (base.sha === current) {
+    // Row 198. The delta is against the base plan's whole basis: its content pin and the
+    // decisions the spec carried when it was derived.
+    const moved = basisMoved({ spec: base.sha, ...(base.decisions ? { decisions: base.decisions } : {}) }, specBasis(root, spec));
+    if (moved.length === 0) {
         ctx.out('delta: none — no delta since the last plan');
         return EXIT.OK;
     }
+    const decisionsBlock = () => {
+        if (!moved.includes('decisions'))
+            return;
+        const delta = decisionDelta(root, base, spec);
+        if (delta === undefined) {
+            ctx.out(`decisions: moved since ${base.planId} — witness read ${id} --decisions`);
+            return;
+        }
+        ctx.out(`decisions: moved since ${base.planId}`);
+        rows('decisions-delta', ['id', 'change', 'text'], delta).forEach(ctx.out);
+    };
+    if (!moved.includes('spec')) {
+        ctx.out('delta: decisions only — the spec content is unchanged since the last plan');
+        decisionsBlock();
+        return EXIT.OK;
+    }
     const baseDoc = contentAtSha(root, spec.rel, base.sha);
     if (!baseDoc) {
         rows('findings', ['field', 'rule', 'detail'], [
@@ -56,5 +80,6 @@ export async function run(ctx, argv) {
     writeFileSync(join(tmp, 'current.md'), canonicalRender(spec.meta, spec.body));
     const diff = tryGit(root, 'diff', '--no-index', '--', join(tmp, 'base.md'), join(tmp, 'current.md'));
     ctx.out(diff.out);
+    decisionsBlock();
     return EXIT.OK;
 }

package/dist/verbs/log.js

@@ -14,11 +14,13 @@ function detail(e) {
     switch (e.t) {
         case 'recap': {
             const size = (k) => (Array.isArray(e[k]) ? e[k].length : 0);
-            return `class=${String(e.class)} goals=${size('goals')} non_goals=${size('non_goals')} slices=${size('slices')}`;
+            const decisions = size('decisions') > 0 ? ` decisions=${size('decisions')}` : '';
+            return `class=${String(e.class)} goals=${size('goals')}${decisions} non_goals=${size('non_goals')} slices=${size('slices')}`;
         }
         case 'write': {
             const covers = Array.isArray(e.covers) && e.covers.length ? ` covers=${e.covers.join('+')}` : '';
-            return `artifact=${String(e.artifact)} sha=${short(String(e.sha))}${covers}`;
+            const carries = Array.isArray(e.carries) && e.carries.length ? ` carries=${e.carries.join('+')}` : '';
+            return `artifact=${String(e.artifact)} sha=${short(String(e.sha))}${covers}${carries}`;
         }
         case 'write-refused': {
             const pairs = Array.isArray(e.rules)

package/dist/verbs/next.js

@@ -11,7 +11,7 @@ import { designArtifactCurrent, designCurrentSha, designPending, designUnseen }
 import { effortAbandoned, effortStreams, latestRecap, readStream } from '../journal.js';
 import { diffReviewedSha, effortOf, effortReviewedSha, effortSpecs, effortWrites, implementReviewedSha, planPairSha } from '../reviewed.js';
 import { baseForSpec } from '../history.js';
-import { canonicalSha } from '../sha.js';
+import { basisMoved, planDecisionsTerm, specBasis } from '../basis.js';
 import { changedFiles, diffBase, evidenceForDiff, isTestPath } from '../evidence.js';
 import { greenOwedOn, greenOwedStep, hasCriteriaStep, implementGated, lastRedVacuous, redCycleClosed, redInFlight, stepProgress, stepsLine, } from '../steps.js';
 import { SESSION_DEFAULT, stagePin } from '../model.js';
@@ -234,6 +234,49 @@ function liveEfforts(root) {
         .filter((e) => latestRecap(root, e.slug) !== undefined && !effortAbandoned(e.entries))
         .sort((a, b) => a.slug.localeCompare(b.slug));
 }
+// Row 52 (Builder's call 8, D198). An amendment no round has judged: ≥ 2 recaps, the last
+// after the last SETTLING decompose event — a passed round or an approve. Measured against
+// the last gate run instead, a stopped round followed by `revise` handed the effort back to
+// the fixture shortcut and `next` routed the plan write again.
+function amendedSinceSettled(entries) {
+    let recaps = 0;
+    let lastRecap = -1;
+    let lastSettled = -1;
+    entries.forEach((e, i) => {
+        if (e.t === 'recap') {
+            recaps++;
+            lastRecap = i;
+            return;
+        }
+        if (e.gate !== 'decompose')
+            return;
+        if ((e.t === 'gate-run' && e.outcome === 'passed') || (e.t === 'human-decision' && e.decision === 'approve'))
+            lastSettled = i;
+    });
+    return recaps >= 2 && lastRecap > lastSettled;
+}
+// A finished effort keeps the shortcut: re-arming one spends a critic round on shipped work,
+// and under autonomy a blocking finding would send a headless decompose session to rewrite
+// live specs (c2). A finished effort's change is a new effort.
+function effortFinished(specs, plans) {
+    const ids = new Set(specs.map((d) => String(d.meta.id)));
+    return specs.every((d) => String(d.meta.status) === 'live') &&
+        !plans.some((p) => ids.has(String(p.meta.parent)) && !planFinished(p));
+}
+// Whether an effort's decompose is owed. Settled either by a real gate-run+approve, or
+// (fixture/seed shortcuts) by every effort spec already being past draft — a plan can't
+// legally target a draft parent, so non-draft specs are proof decompose's outcome was
+// reached one way or another. The shortcut stands in for a gate-run, so an OPEN REOPEN
+// un-discharges it too: otherwise it short-circuits past gateSettled and the reopen is
+// never routed. Row 52: so does an amendment no round has settled, unless the effort is
+// finished.
+function decomposeOwed(root, canon, e, specs, plans) {
+    const reopened = openReopen(e.entries, 'decompose') !== undefined;
+    const specsApproved = !reopened && specs.length > 0 && specs.every((d) => String(d.meta.status) !== 'draft') &&
+        (!amendedSinceSettled(e.entries) || effortFinished(specs, plans));
+    return !specsApproved && !gateSettled(e.entries, 'decompose', effortReviewedSha(root, canon, e.slug).sha) &&
+        !gateParked(e.entries, 'decompose');
+}
 // The action for ONE flow. A flow is a plan with status `in-progress`: it begins at
 // `witness start` and ends at the merge stamp. Anything else returns undefined and is
 // not a flow. Exported because `--flow` and the dashboard must answer with the SAME
@@ -708,17 +751,8 @@ export function computeNext(root, ctx, canon, cfg, opts = {}) {
                 stage: 'decompose', target: e.slug,
             };
         }
-        // Settled either by a real gate-run+approve, or (fixture/seed shortcuts) by every
-        // effort spec already being past draft — a plan can't legally target a draft parent,
-        // so non-draft specs are proof decompose's outcome was reached one way or another.
-        // The shortcut stands in for a gate-run, so an OPEN REOPEN un-discharges it too:
-        // otherwise it short-circuits past gateSettled and the reopen is never routed.
-        const specs = effortSpecs(root, canon, e.slug);
-        const reopened = openReopen(e.entries, 'decompose') !== undefined;
-        const specsApproved = !reopened && specs.length > 0 && specs.every((d) => String(d.meta.status) !== 'draft');
-        const effortSha = effortReviewedSha(root, canon, e.slug).sha;
-        if (!specsApproved && !gateSettled(e.entries, 'decompose', effortSha) &&
-            !gateParked(e.entries, 'decompose')) {
+        if (decomposeOwed(root, canon, e, effortSpecs(root, canon, e.slug), plans)) {
+            const effortSha = effortReviewedSha(root, canon, e.slug).sha;
             return authoringOwed(e.entries, 'decompose', effortSha)
                 ? {
                     line: `witness write <spec-id> --effort ${e.slug} --meta m.json --body b.md`,
@@ -729,11 +763,24 @@ export function computeNext(root, ctx, canon, cfg, opts = {}) {
                     ...noteOf(judgeNote(e.entries, 'decompose', judge)) };
         }
     }
+    // Row 52 (Builder's call 8). While an effort owes the re-slice an amendment re-armed, the specs
+    // it wrote wait for it: a walk scoped to a spec never meets its effort's rung (`admits(e.slug)`
+    // is false there), so without this drive would plan a spec mid-re-slice and the chat would open
+    // a design session on the pre-amendment spec. Only the amendment's: a decompose owed for another
+    // reason (a sibling written after an approve) leaves the approved specs moving, as before. An
+    // admitted effort that owes decompose returned above, so only the efforts this walk does not
+    // admit can still owe it here. Flows, draft-plan gates and starts keep row 18's soft lock.
+    const reslicing = efforts
+        .filter((e) => !admits(e.slug) && latestRecap(root, e.slug)?.class !== 'chore' && effortWrites(root, e.slug).size > 0)
+        .filter((e) => amendedSinceSettled(e.entries) && decomposeOwed(root, canon, e, effortSpecs(root, canon, e.slug), plans));
+    const resliced = new Set(reslicing.flatMap((e) => [...effortWrites(root, e.slug).keys()]));
     for (const spec of specs) {
         if (String(spec.meta.status) !== 'approved')
             continue;
         if (!admits(String(spec.meta.id)))
             continue;
+        if (resliced.has(String(spec.meta.id)))
+            continue;
         if (!designPending(root, spec))
             continue;
         const id = String(spec.meta.id);
@@ -776,14 +823,17 @@ export function computeNext(root, ctx, canon, cfg, opts = {}) {
     // prints, because the effort ledger is not a readiness signal: an amendment can be
     // realized by a plan booked under a different effort (issue #25), and a plan count of
     // zero proves nothing either way. No pin at all means never realized, which is owed.
-    // Reaching this rung proves decompose is settled: rung 6 returns first otherwise.
+    // Reaching this rung proves decompose is settled for every effort the walk admits: rung 6
+    // returns first otherwise. A scoped walk relies on `resliced` for the efforts it does not.
     const unrealizedDelta = (d) => {
         const base = baseForSpec(root, canon, String(d.meta.id));
-        return base.kind === 'empty' || base.sha !== canonicalSha(d.meta, d.body);
+        return base.kind === 'empty' ||
+            basisMoved({ spec: base.sha, ...(base.decisions ? { decisions: base.decisions } : {}) }, specBasis(root, d)).length > 0;
     };
     const planless = canon.docs
         .filter((d) => d.meta.type === 'spec' && plannableParent(d))
         .filter((d) => admits(String(d.meta.id)))
+        .filter((d) => !resliced.has(String(d.meta.id)))
         .filter((d) => !plans.some((p) => String(p.meta.parent) === String(d.meta.id) && !planFinished(p)))
         .filter((d) => (d.meta.depends ?? []).every(ready))
         // last on purpose: the only filter that costs a subprocess — the in-memory ones above
@@ -822,7 +872,7 @@ export function computeNext(root, ctx, canon, cfg, opts = {}) {
         if (!admits(id))
             continue;
         const parent = findById(canon, String(plan.meta.parent));
-        const planSha = parent ? planPairSha(plan, parent) : undefined;
+        const planSha = parent ? planPairSha(plan, parent, planDecisionsTerm(root, plan, parent)) : undefined;
         const entries = readStream(root, id);
         // Parked skips for the same reason settled does — the gate is off the board until a
         // fresh run brings it back, and `status` is where it stays visible meanwhile.

package/dist/verbs/read.js

@@ -7,6 +7,8 @@ import { serializeDoc } from '../fm.js';
 import { primaryRoot } from '../gitio.js';
 import { renderRefusal, v } from '../refusal.js';
 import { findById, loadCanon } from '../scan.js';
+import { latestRecap } from '../journal.js';
+import { decisionLines, recapLines } from '../decisions.js';
 import { rows } from '../toon.js';
 // Row 132. `--outline` + `--lines` rather than `--section <anchor>`, deliberately: the
 // implement skill's fat-artifact rule was *grep for the anchors, then read those offsets*
@@ -47,11 +49,18 @@ function mdOutline(lines) {
 export async function run(ctx, argv) {
     const { values, positionals } = parseArgs({
         args: argv, allowPositionals: true,
-        options: { design: { type: 'boolean' }, outline: { type: 'boolean' }, lines: { type: 'string' } },
+        options: { design: { type: 'boolean' }, outline: { type: 'boolean' }, lines: { type: 'string' }, decisions: { type: 'boolean' } },
     });
     const id = positionals[0];
     if (!id) {
-        ctx.err('usage: witness read <id> [--design] [--outline] [--lines <a>-<b>]');
+        ctx.err('usage: witness read <id> [--design] [--outline] [--lines <a>-<b>] [--decisions]');
+        return EXIT.REFUSED;
+    }
+    // Row 198. A separate mode, never mixed into the artifact's lines: those are one array behind
+    // whole, outline and slice, and an extra row would shift every range `--outline` names.
+    const mixed = [values.design && '--design', values.outline && '--outline', values.lines !== undefined && '--lines'].filter(Boolean);
+    if (values.decisions && mixed.length > 0) {
+        renderRefusal([v('--decisions', 'exclusive', mixed.join(' '), "witness read <id> --decisions alone — a separate mode, never mixed into the artifact's lines")]).forEach(ctx.err);
         return EXIT.REFUSED;
     }
     // primaryRoot, never ctx.cwd: this verb exists BECAUSE a worktree carries no canon, so
@@ -64,6 +73,21 @@ export async function run(ctx, argv) {
     const root = rootR.value;
     const canon = loadCanon(root);
     const doc = findById(canon, id);
+    // Before the unknown-id refusal: an effort slug is the one non-canon id this mode takes (§11).
+    if (values.decisions) {
+        if (doc?.meta.type === 'plan') {
+            renderRefusal([v('id', 'not-a-spec', `${id} is a plan`, `its parent's — witness read ${String(doc.meta.parent)} --decisions`)]).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        const recap = doc === undefined ? latestRecap(root, id) : undefined;
+        if (doc === undefined && recap === undefined) {
+            renderRefusal([v('id', 'unknown-id', id, 'an id from witness index — or an effort slug with --decisions')]).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        ;
+        (doc !== undefined ? decisionLines(root, doc) : recapLines(recap)).forEach(ctx.out);
+        return EXIT.OK;
+    }
     if (!doc) {
         renderRefusal([v('id', 'unknown-id', id, 'an id from witness index')]).forEach(ctx.err);
         return EXIT.REFUSED;

package/dist/verbs/recap.js

@@ -52,6 +52,7 @@ export function validateRecap(raw) {
     out.push(...idTextList(e.goals, 'goals', 'g', true));
     out.push(...idTextList(e.non_goals, 'non_goals', 'n', false));
     out.push(...idTextList(e.constraints, 'constraints', 'c', false));
+    out.push(...idTextList(e.decisions, 'decisions', 'd', false));
     if (e.slices !== undefined && (!Array.isArray(e.slices) || e.slices.some((s) => typeof s !== 'string' || s === ''))) {
         out.push(v('slices', 'shape', JSON.stringify(e.slices), 'list of non-empty strings (non-binding)'));
     }
@@ -164,7 +165,10 @@ export async function run(ctx, argv) {
         }
         const entry = {
             t: 'recap', effort: recap.effort, class: recap.class,
-            goals: recap.goals, non_goals: recap.non_goals, constraints: recap.constraints, slices: recap.slices,
+            goals: recap.goals, non_goals: recap.non_goals, constraints: recap.constraints,
+            // Row 198: no key when there are none, so a decision-free recap journals today's bytes (c2).
+            ...(recap.decisions?.length ? { decisions: recap.decisions } : {}),
+            slices: recap.slices,
             ...(recap.ask !== undefined ? { ask: recap.ask } : {}),
         };
         // entryLine, never a second inline JSON.stringify — completeTxn re-appends when this
@@ -184,10 +188,12 @@ export async function run(ctx, argv) {
         ctx.out(kv('effort', recap.effort));
         ctx.out(kv('class', recap.class));
         ctx.out(kv('goals', recap.goals.length));
+        if (recap.decisions?.length)
+            ctx.out(kv('decisions', recap.decisions.length));
         if (recap.ask !== undefined)
             ctx.out(kv('ask', `${recap.ask} — answered`));
         if (values.amend)
-            ctx.out(kv('amended', 'latest recap wins; coverage re-validates against it'));
+            ctx.out(kv('amended', 'latest recap wins; coverage and decisions re-validate against it'));
         ctx.out(`next: witness write --effort ${recap.effort} --meta <m.json> --body <b.md> <spec-id>`);
         return EXIT.OK;
     }

package/dist/verbs/write.js

@@ -15,6 +15,7 @@ import { humanCall, renderRefusal, v } from '../refusal.js';
 import { baseForSpec, contentAtSha } from '../history.js';
 import { findById, findCycle, loadCanon, planFinished, plansOn } from '../scan.js';
 import { canonicalJson, canonicalSha, short } from '../sha.js';
+import { carriedDecisions, decisionsSha } from '../decisions.js';
 import { kv } from '../toon.js';
 import { crashPoint, guardTxn, withTxn } from '../txn.js';
 import { validateDoc } from '../schemas.js';
@@ -30,6 +31,15 @@ function buildSpecMeta(root, id, manifest, recap, canon, existing, body) {
         if (!goalIds.has(g))
             violations.push(v(`covers[${i}]`, 'unknown-goal', String(g), `a goal id from the latest recap: ${[...goalIds].join(' ')}`));
     });
+    // Row 198: the decisions this spec realizes ride covers' rail — journal only, never frontmatter.
+    // Journaled as a set in id order, so a reordered or repeated list is the same mapping.
+    const listed = Array.isArray(manifest.carries) ? manifest.carries : [];
+    const decisionIds = new Set((recap.decisions ?? []).map((d) => d.id));
+    listed.forEach((d, i) => {
+        if (!decisionIds.has(d))
+            violations.push(v(`carries[${i}]`, 'unknown-decision', String(d), `a decision id from the latest recap: ${[...decisionIds].join(' ') || '(none)'}`));
+    });
+    const carries = [...new Set(listed)].sort((a, b) => String(a).localeCompare(String(b), undefined, { numeric: true }));
     const meta = {
         id,
         type,
@@ -59,7 +69,7 @@ function buildSpecMeta(root, id, manifest, recap, canon, existing, body) {
     if (typeof manifest.supersedes === 'string' && !findById(canon, manifest.supersedes) && !streamExists(root, manifest.supersedes)) {
         violations.push(v('supersedes', 'unknown-ref', manifest.supersedes, 'an existing spec id or frozen journal stream'));
     }
-    return { meta, covers, violations, warnings: [] };
+    return { meta, covers, carries, violations, warnings: [] };
 }
 export async function run(ctx, argv) {
     const { values, positionals } = parseArgs({
@@ -237,7 +247,8 @@ export async function run(ctx, argv) {
             : canonicalSha(built.meta, body);
         const entry = {
             t: 'write', effort, artifact: id, sha,
-            ...(manifest.type === 'plan' ? {} : { covers: built.covers }),
+            ...(manifest.type === 'plan' ? {} : { covers: built.covers, ...(built.carries.length ? { carries: built.carries } : {}) }),
+            ...(built.decisions ? { decisions: built.decisions } : {}),
             ...(existing === undefined ? { created: true } : {}),
             ...(supersedes !== undefined ? { supersedes } : {}),
         };
@@ -304,7 +315,7 @@ function buildPlanMeta(root, id, manifest, recap, canon, existing, body) {
     const parent = parentId ? findById(canon, parentId) : undefined;
     if (!parent) {
         violations.push(v('parent', 'unknown-parent', parentId || 'absent', 'an existing spec id (or principles for chores)'));
-        return { meta: {}, covers: [], violations, warnings };
+        return { meta: {}, covers: [], carries: [], violations, warnings };
     }
     if (parent.meta.type === 'principles' && recap.class !== 'chore') {
         violations.push(v('parent', 'class-mismatch', `principles parent on a ${recap.class} effort`, 'feature and fix plans derive from a spec'));
@@ -320,6 +331,17 @@ function buildPlanMeta(root, id, manifest, recap, canon, existing, body) {
     if (typeof supplied === 'string' && supplied !== computed) {
         violations.push(v('derives-from', 'stale-derivation', short(supplied), `current parent content is ${short(computed)} — re-derive from witness diff ${parentId}`));
     }
+    // Row 198. The decisions the parent carries pin beside its content, absent when it carries
+    // none, so a decision-free plan keeps today's bytes (c2). A chore's own decisions never pin
+    // here (Builder's call 4): the chore plan would become its parent's base with a pin the
+    // parent's carried set never matches, and the parent would re-queue forever.
+    const carried = carriedDecisions(root, parent)?.decisions ?? [];
+    const decisionsFrom = decisionsSha(carried);
+    const suppliedDecisions = manifest['decisions-from'];
+    if (suppliedDecisions !== undefined && suppliedDecisions !== decisionsFrom) {
+        const pin7 = (x) => (x === undefined ? 'none' : short(String(x)));
+        violations.push(v('decisions-from', 'stale-decisions', pin7(suppliedDecisions), `the decisions ${parentId} carries are at ${pin7(decisionsFrom)} — omit decisions-from; witness write stamps it`));
+    }
     const parentUi = parent.meta.ui === true;
     const suppliedDesignFrom = manifest['design-from'];
     if (!parentUi && suppliedDesignFrom !== undefined) {
@@ -364,6 +386,7 @@ function buildPlanMeta(root, id, manifest, recap, canon, existing, body) {
         parent: parentId,
         'derives-from': computed,
         ...(designFrom !== undefined ? { 'design-from': designFrom } : {}),
+        ...(decisionsFrom !== undefined ? { 'decisions-from': decisionsFrom } : {}),
         depends: manifest.depends ?? [],
         needs: manifest.needs ?? [],
         steps: manifest.steps,
@@ -399,7 +422,7 @@ function buildPlanMeta(root, id, manifest, recap, canon, existing, body) {
     const cycle = findCycle(canon, { id, depends });
     if (cycle)
         violations.push(v('depends', 'cycle', cycle.join(' -> '), 'an acyclic depends graph'));
-    return { meta, covers: [], violations, warnings };
+    return { meta, covers: [], carries: [], ...(carried.length ? { decisions: carried } : {}), violations, warnings };
 }
 function deltaCriteriaIds(root, canon, parent, excludePlanId) {
     const current = Array.isArray(parent.meta.criteria)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popovych.co/witness",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Evidence-gated spec-driven development pipeline for AI coding agents: brainstorm to PR in six stages, where specs are state, plans are motion, and no transition passes without evidence. Drives from Claude Code or Pi.",
   "keywords": [
     "spec-driven-development",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "witness",
   "description": "Spec-driven development with evidence gates: brainstorm → PR through six stages and five gates. Skills author, the pinned witness CLI writes state and witnesses evidence; gates stop where judgment is owed.",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "author": {
     "name": "Kostiantyn Popovych"
   },

package/plugin/commands/witness.md

@@ -12,7 +12,7 @@ Any other words in `$ARGUMENTS` are the human's ask: run `$WITNESS ask "<those w
 Resolve the CLI once:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.22.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.23.0}"
 ```
 
 If the repo has no `witness.config.yaml`, run `$WITNESS init` first (one bootstrap commit), then proceed. If init or any verb refuses on a dirty tree, the human commits or cleans it — **never `git commit` yourself, anywhere, at any stage**: the CLI makes its own state commits, and the ship phase makes the sole code commit.

package/plugin/hooks/session-dashboard.sh

@@ -3,4 +3,4 @@
 # context). Silent everywhere that isn't a witness repo; failures swallowed:
 # session start must never hang or die on this.
 [ -f witness.config.yaml ] || exit 0
-${WITNESS_BIN:-npx -y @popovych.co/witness@0.22.0} 2>/dev/null || true
+${WITNESS_BIN:-npx -y @popovych.co/witness@0.23.0} 2>/dev/null || true

package/plugin/skills/witness-brainstorm/SKILL.md

@@ -15,7 +15,7 @@ witness: ends in a confirmed scope recap, writes no document. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.22.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.23.0}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

package/plugin/skills/witness-decompose/SKILL.md

@@ -10,7 +10,7 @@ description: Slice a witness effort's confirmed recap into vertical spec slices,
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.22.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.23.0}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.
@@ -27,7 +27,7 @@ WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.22.0}"
 ## Inputs (rebuild them, never remember them)
 
 ```bash
-$WITNESS log <effort>     # the latest recap entry is your contract: class, goals g*, non-goals n*, constraints c*
+$WITNESS read <effort> --decisions   # the latest recap: class, goals g*, decisions d*, constraints c*, non-goals n*
 $WITNESS index            # live canon: id · summary · status · depends, grouped by dir
 $WITNESS decide decompose <effort> --show   # ONLY when re-entered after a revise
 ```
@@ -47,7 +47,7 @@ The class comes from the recap. Never ask for it again.
 - Amending a living spec is the same write with the existing id — its status resets to `draft` (re-approval owed). If the CLI warns the spec has an in-flight child plan, surface that warning at the gate stop.
 - Boundary changes (split, merge, extraction out of a live spec) → the new spec's manifest carries `supersedes: <old-id>`; rewrite every dependent's `depends` in the same effort — the CLI refuses dangling edges. It also refuses `dangling-parent` while a plan of the old spec is still in motion: whether that plan ships first or is abandoned is the human's call, so stop and surface it — never abandon it yourself.
 - Cross-cutting changes → sequenced per-slice amendments ordered via `depends`, expand-contract style (accept both → switch → drop old), each step independently shippable.
-- Self-check totality before gating: every goal covered by ≥ 1 spec, every spec covers ≥ 1 goal.
+- Self-check totality before gating: every goal covered by ≥ 1 spec, every spec covers ≥ 1 goal, every decision carried by ≥ 1 spec. A decision no slice can carry was filed wrong — it is a constraint or a non-goal; say so at the gate stop, where `--revise --upstream` re-opens the recap.
 
 ## Author each spec
 
@@ -65,7 +65,8 @@ cat > "$DIR/meta.json" <<'EOF'
     { "id": "ac-rotate", "test": "@spec:auth-refresh" },
     { "id": "ac-smoke", "cmd": "npm run smoke:auth" }
   ],
-  "covers": ["g1"]
+  "covers": ["g1"],
+  "carries": ["d1"]
 }
 EOF
 cat > "$DIR/body.md" <<'EOF'
@@ -87,6 +88,7 @@ Get these right the first time — the dashboard trends your first-try valid rat
 - `summary` ≤ 120 chars: what the slice **is** (Motivation carries the why).
 - `criteria`: ≥ 1 entry, unique ids, each exactly one of `test` (value must be `@spec:<this-spec-id>`) or `cmd`. A criterion that cannot fail is not a criterion.
 - `covers`: the recap goal ids this spec honestly advances — the critic judges the mapping's quality.
+- `carries`: the recap decision ids this spec realizes. Every decision is carried by ≥ 1 spec (the gate's `decision-coverage`). A behavior decision is stated in that spec's `## Behavior`; an approach decision is not contradicted. The journal holds it, never frontmatter. Omit it when the recap has no decisions.
 - Body: exactly the `## Motivation` and `## Behavior` headings; behavior-only — internal interfaces never appear in a spec.
 - `id`: `[a-z0-9-]+`; new ids land at `specs/<id>.md` (or the repo's configured specs dir). An id that already names something is refused `id-taken` — a superseded spec, an effort's slug, witness's `floor` — and so is a path another doc holds (`path-taken`): choose a new id.
 - `needs`: external prerequisites only, machine-checkable (`env:` / `cmd:` / `manual:` + `satisfied`). A manual need the slice can still be built and shipped without carries an `id` and names the `cmd:` criteria it holds — `{ "id": "ses-prod", "manual": "SES production access", "satisfied": false, "holds": ["ac-baseline"] }` — and while it is unmet those criteria report `held` instead of failing. A need the slice cannot even start without belongs on its plan, where it blocks `witness start`.

package/plugin/skills/witness-design/SKILL.md

@@ -16,7 +16,7 @@ No text copied verbatim; the design-critic lens is new material. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.22.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.23.0}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

package/plugin/skills/witness-implement/SKILL.md

@@ -15,7 +15,7 @@ tests carry the parent spec's tag in their NAME. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.22.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.23.0}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

package/plugin/skills/witness-plan/SKILL.md

@@ -15,7 +15,7 @@ parent's criteria. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.22.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.23.0}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.
@@ -36,6 +36,8 @@ Everything below is rebuilt from `witness diff` and the CLI's read verbs — nev
 ```bash
 $WITNESS diff <spec-id>        # the delta this plan must realize (base: previous plan's pin → last live → empty)
 $WITNESS read <spec-id>        # the parent spec, current content (reading is fine — writing is not)
+$WITNESS read <spec-id> --decisions   # the decisions the spec carries + its effort's constraints and non-goals — the plan contradicts none (the critic blocks it)
+$WITNESS read <effort> --decisions    # a chore plan: the chore's whole recap, too
 $WITNESS index                 # the plans table names this spec's prior plans, if any
 $WITNESS read <plan-id>        # …then read the one you care about
 $WITNESS decide plan <plan-id> --show       # ONLY when re-entered after a revise
@@ -47,7 +49,7 @@ $WITNESS decide plan <plan-id> --show       # ONLY when re-entered after a revis
 
 ## Author the plan
 
-Every criterion in the delta must be realized by ≥ 1 step; every step maps to ≥ 1 criterion **or** is honestly `scaffolding: true` (rigging only — fixtures, wiring, config; never behavior a criterion owns). `derives-from` is **stamped by the CLI** from the parent's current content — never put it in the manifest; a supplied stale pin refuses.
+Every criterion in the delta must be realized by ≥ 1 step; every step maps to ≥ 1 criterion **or** is honestly `scaffolding: true` (rigging only — fixtures, wiring, config; never behavior a criterion owns). `derives-from` and `decisions-from` are **stamped by the CLI** from the parent's current content and the decisions it carries — never put either in the manifest; a supplied stale pin refuses.
 
 If the parent spec is `ui`-flagged, its **design must already be approved** (the design stage runs between decompose and plan). Read it with `$WITNESS read <spec-id> --design` (`--outline`, then `--lines <a>-<b>`, when it is fat) — your steps derive from that approved look, not a fresh invention — and put its approved artifact sha in the manifest as `"design-from"` (the CLI refuses a plan whose pin is missing, stale, or present on a non-ui parent; get it from the spec's `design.sha` stamp via `$WITNESS log <spec-id>`). A UI step names the design section (`design#<id>`) it realizes alongside its `@spec:` browser test.
 
@@ -94,6 +96,6 @@ $WITNESS gate plan <plan-id>    # append --manual when the run asked for it
 
 - **Auto-pass** → done; hand back to /witness.
 - **Stop** → render the gate output verbatim and in full, including its ranked options and `run:` line, and END YOUR TURN.
-- **Re-entered after `--revise`** → `decide --show` gives the verdict + note (findings anchor to `<plan-id> > ## Step: <id>`); rewrite via `witness write` with the same plan id; re-gate. A parent amended mid-flight fails `pin-fresh` — rewriting through `witness write` re-stamps the pin to current content; your body must then realize the *new* delta (`$WITNESS diff` again). `--show` also emits `state:` and `exits:` — a `reopened` or `settled` state means the verdict above it is history, so act on the `exits:` line, not on remembered findings.
+- **Re-entered after `--revise`** → `decide --show` gives the verdict + note (findings anchor to `<plan-id> > ## Step: <id>`); rewrite via `witness write` with the same plan id; re-gate. A parent amended mid-flight, or a decision it carries changed, fails `pin-fresh` — rewriting through `witness write` re-stamps the pin to current content; your body must then realize the *new* delta (`$WITNESS diff` again). `--show` also emits `state:` and `exits:` — a `reopened` or `settled` state means the verdict above it is history, so act on the `exits:` line, not on remembered findings.
 - Findings implicate the **spec** (plan faithful, spec wrong)? Tell the human `--revise --upstream <spec-id>` reopens decompose for it.
 - **Under `autonomy: on`** (printed by `gate`; not on a `--manual` run): the CLI settles this stop and prints `decided:`. If a `relay:` line printed under it, this session has reached its context limit: print that line verbatim and END YOUR TURN — a fresh session takes the revise. Otherwise, on `→ revise`, rewrite from the revise-context it printed and re-gate; on `→ approve`, `→ revise-upstream` or `→ stop`, hand back to /witness. Never run `witness decide`. End your turn only at a `kept-stop:` line, a `relay:` line, or a refusal you cannot repair.

package/plugin/skills/witness-ship/SKILL.md

@@ -15,7 +15,7 @@ model can. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.22.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.23.0}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

package/prompts/plan-critic.md

@@ -5,10 +5,11 @@ You judge a plan against its parent spec and the delta it claims to realize. You
 1. **Delta faithfulness.** The plan must realize the whole delta and nothing beyond it. Two blocking shapes: a step whose body implements something the delta never asked for (scope invention — plans derive from specs, never extend them), and a delta criterion whose mapped step is mapped on paper only (the body prose does something other than what would make that criterion pass).
 2. **Step quality.** Each step must be independently checkable: concrete behavior, an observable end state, right-sized. "Make it robust", "improve the handling", "clean up X" with no observable outcome — blocking. A step that presumes an artifact a *later* step creates (order broken) — blocking.
 3. **Honest scaffolding.** `scaffolding: true` exists for genuine rigging — fixtures, wiring, config. A scaffolding-marked step whose body carries behavior some criterion should own is dodging the mapping — blocking.
+4. **Decision fidelity.** When present, the decisions block lists what the parent's slicing settled (the recap decisions the parent carries) and its effort's standing limits (constraints and non-goals); a chore plan also gets the chore's whole recap. A step whose body builds what a non-goal rules out, breaks a constraint, or takes an approach a decision ruled out is blocking. When the delta base lists decisions added or changed since the previous plan, a plan whose steps realize none of them is blocking. Otherwise silence is not contradiction: a step need not restate a decision it does not touch. Anchor findings to `<plan-id> > ## Step: <id>`.
 
 Judge the body prose, not just the manifest: totality was checked mechanically over ids; you are the only reader comparing what the step *says it will do* against what the delta *needs done*.
 
-The reviewed content arrives as documents: the parent spec, the delta rendering, and the plan. Anchor findings to heading paths — plan findings usually anchor to `<plan-id> > ## Step: <id>`.
+The reviewed content arrives as documents: the parent spec, the delta rendering, the decisions block when the parent carries decisions or its effort has standing limits, and the plan. Anchor findings to heading paths — plan findings usually anchor to `<plan-id> > ## Step: <id>`.
 
 ## Verdict contract
 

package/prompts/slicing-critic.md

@@ -1,6 +1,6 @@
 # Slicing critic — witness decompose gate
 
-You judge a decompose result: the effort's confirmed scope recap (goals / non-goals / constraints as JSON, each item carrying an id like `g1`/`n1`/`c1`), the goal-coverage mapping, and every spec written for the effort. Mechanical checks already passed before you were invoked — schema, DAG acyclicity, criteria parse, and coverage totality (every goal covered by ≥ 1 spec, every spec covers ≥ 1 goal). You judge what machines cannot: quality. Scope approval is a human's call; your findings are what the human sees first.
+You judge a decompose result: the effort's confirmed scope recap (goals / non-goals / constraints / decisions as JSON, each item carrying an id like `g1`/`n1`/`c1`/`d1`), the goal-coverage mapping, the decision-carrying mapping when the recap has decisions, and every spec written for the effort. Mechanical checks already passed before you were invoked — schema, DAG acyclicity, criteria parse, coverage totality (every goal covered by ≥ 1 spec, every spec covers ≥ 1 goal), and decision-coverage totality (every decision carried by ≥ 1 spec). You judge what machines cannot: quality. Scope approval is a human's call; your findings are what the human sees first.
 
 Work every lens below over every spec, in this order:
 
@@ -12,12 +12,13 @@ Work every lens below over every spec, in this order:
 6. **Summary accuracy.** The frontmatter `summary` must say what the slice *is* and match the Behavior section. It feeds `witness index`, which routes every future fix — a summary promising more, less, or different misroutes forever: blocking.
 7. **Depends refs.** Missing edges are the dangerous direction: a spec whose behavior presumes another slice landed, with no `depends` edge, is blocking. Decorative extra edges are notes.
 8. **UI-flag honesty.** A spec whose `## Behavior` describes browser-rendered or interactive surface (a screen, a form, client-side interaction) must carry `ui: true` — it earns a design stage before its plan. A spec so flagged whose behavior is purely non-visual (a backend job, a data contract) must not. A missing flag on a UI slice, or a spurious flag on a non-UI slice, is blocking — the flag routes the whole design stage.
+9. **Decision fidelity.** A recap decision is a settled answer; a spec that `carries` it realizes it. A spec that contradicts a decision it carries is blocking. A decision that states observable behavior must appear in the `## Behavior` of every spec that carries it — missing is blocking. An approach decision needs no Behavior line, but no spec may contradict it. Anchor findings to the spec's heading.
 
 Also watch for **contradictions**: two specs stating rules that cannot both hold for the same subject — the same trigger with opposite outcomes, or two thresholds for one fact — with no spec stating which wins. Always **blocking**: duplication *may* drift, but a contradiction is already wrong, and a canon that contradicts itself is lying today. The remedy is a spec, never a later stage: which rule wins is behavior, and behavior lives in `## Behavior`. Anchor to the heading in either spec.
 
 Also watch for **duplicated facts**: one fact (a threshold, format, protocol) written into two specs. Recommend extraction into its own spec — blocking when the duplication would drift, a note otherwise.
 
-The reviewed content arrives as documents: the recap JSON, the coverage table, and each spec (frontmatter + body). Anchor doc findings to heading paths within the spec's document id.
+The reviewed content arrives as documents: the recap JSON, the coverage table, the decision table when the recap carries decisions, and each spec (frontmatter + body). Anchor doc findings to heading paths within the spec's document id.
 
 ## Verdict contract