@goodbones/cli 0.1.0-beta.10 → 0.1.0-beta.12

package/build/esm/run.js

@@ -1,8 +1,8 @@
-import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
-import { allowed, baselineOf, campaignsSelecting, CONFORMANCE_MEASURES, coverageOf, cyclesIn, decodeBaseline, decodeManifest, EMPTY_BASELINE, entryOf, evaluateCampaigns, evaluateGraph, evaluateMemberSite, evaluateResolvedEdge, evaluateSelectedBindings, evaluateStructure, evaluateSurface, explainCampaign, exportRulesSelecting, findManifestFile, fingerprintOf, formatManifestYaml, formatMessage, fractionsOf, hasGraphRules, heightOf, isComplete, isStalled, leafTermsOf, ledgerArithmeticHolds, ledgerOf, listSourceFiles, makeBaselineFilter, MANIFEST_FILENAMES, MANIFEST_SCHEMA_ID, memberRulesSelecting, progressOf, pruned, readManifestFile, reconcile, reportSpecsOf, requiredSiblingsOf, residueOf, rulesSelecting, serializeBaseline, serializeLedger, slackOf, SNAPSHOT_VERSION, staleEntriesOf, surfaceRulesSelecting, vacancyOf, } from "@goodbones/core";
+import { attest, authorOf, baseSideAt, campaignFailuresOf, campaignReportsOf, campaignsOf, campaignsSelecting, clear, concede, evaluateCampaigns, explainCampaignLines, explainObjective, historyOf, hitsInWindow, ledgeredFilter, note, nudgeOf, readDiff, renderCampaignReports, renderCampaignRows, renderHistory, renderNudge, reportSpecsOf, snapshotCampaignsOf, widenedExtensions, } from "@goodbones/campaigns";
+import { baselineOf, CONFORMANCE_MEASURES, coverageOf, cyclesIn, decodeBaseline, decodeManifest, EMPTY_BASELINE, evaluateGraph, evaluateMemberSite, evaluateResolvedEdge, evaluateSelectedBindings, evaluateStructure, evaluateSurface, exportRulesSelecting, findManifestFile, fingerprintOf, formatManifestYaml, formatMessage, fractionsOf, hasGraphRules, heightOf, listSourceFiles, makeBaselineFilter, MANIFEST_FILENAMES, MANIFEST_SCHEMA_ID, memberRulesSelecting, readManifestFile, requiredSiblingsOf, residueOf, rulesSelecting, serializeBaseline, slackOf, SNAPSHOT_VERSION, staleEntriesOf, surfaceRulesSelecting, vacancyOf, } from "@goodbones/core";
 import * as Effect from "effect/Effect";
 import * as Result from "effect/Result";
 import { loadPolicyFromFile, manifestPathOf } from "./config-loader.js";
@@ -11,9 +11,12 @@ import { infer } from "./infer.js";
 import { sourceFactsOf } from "./source-facts.js";
 const fail = (message) => ({ _tag: "CliFailure", message });
 export const collectFindings = (policy, roots, options = {}) => {
-    const files = listSourceFiles(policy.repoRoot, roots, policy.languages);
+    // A campaign may widen the walk past the packs' extensions; a file only a
+    // campaign asked for is seen by the campaigns and by no other family.
+    const walked = listSourceFiles(policy.repoRoot, roots, policy.languages, widenedExtensions(policy));
+    const known = new Set(policy.languages.flatMap((one) => one.extensions));
+    const files = walked.filter((file) => known.has(path.extname(file)));
     const violations = [];
-    const campaigns = [];
     const unresolved = [];
     const edges = [];
     // Each file is read and parsed at most once, whether the per-file
@@ -45,30 +48,12 @@ export const collectFindings = (policy, roots, options = {}) => {
         for (const violation of evaluateGraph(policy.graph, graph))
             violations.push(violation);
     }
+    // The campaigns, over every walked file, through the same caches.
+    const campaigns = evaluateCampaigns(policy, roots, walked, { textOf, factsOf });
     for (const file of files) {
         for (const violation of evaluateStructure(policy.structure, policy.fileSystem, file)) {
             violations.push(violation);
         }
-        // A campaign selects by its scope. The file is parsed by the scope's
-        // matcher once, and only when a term of some selected campaign reads the
-        // syntax tree.
-        const selectedCampaigns = campaignsSelecting(policy.campaignRules, file);
-        if (selectedCampaigns.length > 0) {
-            const text = textOf(file);
-            const needsSyntax = selectedCampaigns.some((rule) => leafTermsOf(rule.detect).some((leaf) => leaf === "syntax" || leaf === "report" || leaf === "fn"));
-            for (const hit of evaluateCampaigns(selectedCampaigns, {
-                file,
-                text,
-                facts: factsOf(file),
-                resolver: policy.resolver,
-                fileSystem: policy.fileSystem,
-                syntax: needsSyntax ? policy.syntax.parse(file, text) : null,
-                functions: policy.functions,
-                reports: policy.reports,
-            })) {
-                campaigns.push(hit);
-            }
-        }
         const selectedImports = rulesSelecting(policy.importRules, file);
         const selectedExports = exportRulesSelecting(policy.exportRules, file);
         const selectedMembers = memberRulesSelecting(policy.memberRules, file);
@@ -139,66 +124,6 @@ const report = (lines) => Effect.sync(() => {
         process.stdout.write(`${line}\n`);
 });
 const describe = (violation) => `  ${violation.file}\n      ${formatMessage(violation)}`;
-// Each campaign's hits against its ledger. A campaign with no ledger has
-// every hit new; one with no hits and no ledger has nothing to say.
-const campaignReportsOf = (policy, hits) => policy.campaignRules.map((rule) => {
-    const own = hits.filter((hit) => hit.campaign === rule.id).map((hit) => hit.violation);
-    const ledger = policy.ledgers.get(rule.id);
-    if (ledger === undefined) {
-        return {
-            id: rule.id,
-            count: own.length,
-            new: [...new Set(own.map(entryOf))].sort(),
-            stale: [],
-            drifted: 0,
-            missingLedger: true,
-            arithmetic: true,
-            complete: own.length === 0,
-            stalled: false,
-            onComplete: rule.onComplete,
-        };
-    }
-    const state = reconcile(ledger, own, rule.unit);
-    return {
-        id: rule.id,
-        count: own.length,
-        new: [...new Set(state.unrecorded.map(entryOf))].sort(),
-        stale: state.stale,
-        drifted: state.drifted.length,
-        missingLedger: false,
-        arithmetic: ledgerArithmeticHolds(ledger),
-        complete: isComplete(ledger) && own.length === 0,
-        stalled: isStalled(rule, ledger, policy.now),
-        onComplete: rule.onComplete,
-    };
-});
-// Whether a campaign hit is carried by its ledger — exactly, or by anchor.
-const ledgeredFilter = (policy, hits) => {
-    const carried = new Set();
-    for (const rule of policy.campaignRules) {
-        const ledger = policy.ledgers.get(rule.id);
-        if (ledger === undefined)
-            continue;
-        const own = hits.filter((hit) => hit.campaign === rule.id).map((hit) => hit.violation);
-        for (const one of reconcile(ledger, own, rule.unit).ledgered)
-            carried.add(one);
-    }
-    return (hit) => carried.has(hit.violation);
-};
-// Why a campaign report is not ok, in the order `check` explains it.
-const campaignFailuresOf = (campaigns) => [
-    ...campaigns.filter((one) => one.stale.length > 0).map(() => "stale ledger entries"),
-    ...campaigns.filter((one) => !one.arithmetic).map(() => "ledger arithmetic does not hold"),
-    ...campaigns
-        .filter((one) => one.missingLedger && one.count > 0)
-        .map((one) => `campaign ${one.id} has no ledger`),
-    ...campaigns
-        .filter((one) => !one.missingLedger && one.new.length > 0)
-        .map(() => "unrecorded campaign growth"),
-    ...campaigns
-        .filter((one) => one.complete && !one.missingLedger && one.onComplete === "remove")
-        .map((one) => `campaign ${one.id} is complete and declared onComplete: remove`),
-];
 const COVERAGE_FAMILIES = [
     "imports",
     "structure",
@@ -248,12 +173,17 @@ const reportOf = (policy, roots, manifestPath, findings) => {
             baselined: isBaselined(violation),
             ledgered: false,
         })),
-        ...findings.campaigns.map((hit) => ({
+        // The hits that count: those whose objective is in window for the
+        // sector they fall in.
+        ...findings.campaigns.flatMap((evaluation) => hitsInWindow(evaluation).map((hit) => ({
             ...hit.violation,
             fingerprint: fingerprintOf(hit.violation),
             baselined: false,
             ledgered: isLedgered(hit),
-        })),
+            objective: hit.objective,
+            sector: hit.sector,
+            entry: hit.entry,
+        }))),
     ];
     const campaigns = campaignReportsOf(policy, findings.campaigns);
     // The floors. A policy states how much of the tree it reaches, per
@@ -350,66 +280,20 @@ const describeExcess = (one) => {
     const [singular, plural] = MEASURE_NOUNS[one.measure];
     return `  ${one.measure}: ${count(one.count, singular, plural)}, ceiling ${String(one.ceiling)}`;
 };
-// A campaign hit, with the campaign's `how` as its instruction.
-const describeHit = (violation) => `  ${violation.file}${violation.subject === null ? "" : `  (${violation.subject})`}\n      ${formatMessage(violation)}`;
-const renderCampaigns = (report) => {
-    const hits = report.violations.filter((one) => one.kind === "campaign");
-    return report.campaigns.flatMap((campaign) => {
-        const rule = `campaign/${campaign.id}`;
-        const fresh = new Set(campaign.new);
-        const own = hits.filter((one) => one.ruleName === rule && fresh.has(entryOf(one)));
-        if (campaign.missingLedger && campaign.count > 0) {
-            return [
-                "",
-                `campaign ${campaign.id}: ${count(campaign.count, "hit")} and no ledger. Record them before they count as growth:`,
-                "",
-                `  architecture campaigns init ${campaign.id}`,
-            ];
-        }
-        const complete = campaign.complete && !campaign.missingLedger;
-        return [
-            ...(campaign.new.length === 0
-                ? []
-                : [
-                    "",
-                    `campaign ${campaign.id}: ${count(campaign.new.length, "new hit")} the ledger does not carry. Fix them, or record why the count may rise:`,
-                    ...own.map(describeHit),
-                    "",
-                    `  architecture campaigns allow ${campaign.id} --reason "<why>"`,
-                ]),
-            ...(campaign.stale.length === 0
-                ? []
-                : [
-                    "",
-                    `campaign ${campaign.id}: ${count(campaign.stale.length, "ledger entry", "ledger entries")} no longer fire. The code was fixed; prune them:`,
-                    ...campaign.stale.map((entry) => `  ${entry}`),
-                    "",
-                    `  architecture campaigns prune ${campaign.id}`,
-                ]),
-            ...(campaign.arithmetic
-                ? []
-                : [
-                    "",
-                    `campaign ${campaign.id}: the ledger does not add up (entries ≠ initial + allowed − fixed). An entry was added by hand; remove it, or record it with \`campaigns allow\`.`,
-                ]),
-            ...(complete && campaign.onComplete === "remove"
-                ? [
-                    "",
-                    `campaign ${campaign.id} is complete and declares onComplete: remove. Delete it from the manifest, and its ledger.`,
-                ]
-                : []),
-            ...(campaign.stalled
-                ? [
-                    "",
-                    `notice: campaign ${campaign.id} has stalled — no entry has left its ledger within its staleAfter.`,
-                ]
-                : []),
-            ...(complete && campaign.onComplete === "keep"
-                ? ["", `notice: campaign ${campaign.id} is complete, and stays as a guard.`]
-                : []),
-        ];
-    });
-};
+const renderCampaigns = (report) => renderCampaignReports(report.campaigns, report.violations.flatMap((one) => one.kind === "campaign" &&
+    one.objective !== undefined &&
+    one.sector !== undefined &&
+    one.entry !== undefined
+    ? [
+        {
+            violation: one,
+            objective: one.objective,
+            sector: one.sector,
+            entry: one.entry,
+            ledgered: one.ledgered,
+        },
+    ]
+    : []));
 const renderText = (report) => {
     const reportable = report.violations.filter((one) => one.kind !== "campaign" && !one.baselined);
     const carried = report.violations.filter((one) => one.kind !== "campaign").length - reportable.length;
@@ -484,41 +368,7 @@ export const snapshotOf = (policy, roots, manifestPath) => {
         const byHeight = heightOfViolation(left) - heightOfViolation(right);
         return byHeight !== 0 ? byHeight : left.fingerprint.localeCompare(right.fingerprint);
     });
-    const campaigns = policy.campaignRules.map((rule) => {
-        const ledger = policy.ledgers.get(rule.id);
-        const own = findings.campaigns.filter((hit) => hit.campaign === rule.id).length;
-        const base = {
-            id: rule.id,
-            ...(rule.title === null ? {} : { title: rule.title }),
-            ...(rule.owner === null ? {} : { owner: rule.owner }),
-            initial: own,
-            allowed: 0,
-            count: own,
-            fixed: 0,
-            progress: 0,
-            lastProgress: new Date(policy.now).toISOString(),
-            regressions: 0,
-            stalled: false,
-            complete: own === 0,
-            onComplete: rule.onComplete,
-            ledgered: false,
-        };
-        if (ledger === undefined)
-            return base;
-        return {
-            ...base,
-            initial: ledger.initial,
-            allowed: ledger.regressions.reduce((sum, one) => sum + one.delta, 0),
-            count: ledger.entries.length,
-            fixed: ledger.fixed,
-            progress: progressOf(ledger),
-            lastProgress: ledger.lastProgress,
-            regressions: ledger.regressions.length,
-            stalled: isStalled(rule, ledger, policy.now),
-            complete: isComplete(ledger),
-            ledgered: true,
-        };
-    });
+    const campaigns = snapshotCampaignsOf(policy, findings.campaigns);
     return {
         version: SNAPSHOT_VERSION,
         manifest: report_.manifest,
@@ -540,20 +390,6 @@ export const snapshotOf = (policy, roots, manifestPath) => {
         campaigns,
     };
 };
-// The campaigns, stalled and complete first, then by progress.
-const renderCampaignRows = (campaigns) => {
-    const width = Math.max(0, ...campaigns.map((one) => one.id.length));
-    const state = (one) => !one.ledgered ? "no ledger" : one.complete ? "complete" : one.stalled ? "stalled" : "";
-    const ordered = [...campaigns].sort((left, right) => {
-        const rank = (one) => one.stalled ? 0 : one.complete && one.ledgered ? 1 : 2;
-        const byRank = rank(left) - rank(right);
-        return byRank !== 0 ? byRank : left.progress - right.progress;
-    });
-    return ordered.map((one) => `  ${one.id.padEnd(width)}  ${percent(one.progress).padStart(4)}  ${String(one.count).padStart(5)} left` +
-        `  ${String(one.fixed)} fixed  ${String(one.allowed)} allowed` +
-        (one.owner === undefined ? "" : `  ${one.owner}`) +
-        (state(one) === "" ? "" : `  ${state(one)}`));
-};
 const renderSnapshot = (snapshot) => {
     const reportable = snapshot.violations.filter((one) => !one.baselined && !one.ledgered);
     const carried = snapshot.violations.length - reportable.length;
@@ -687,7 +523,7 @@ export const writeBaseline = (policy, roots) => Effect.gen(function* () {
 });
 // The question a tree config makes harder to answer than a flat one: given a
 // file, what governs it? A flat config you grep; a tree you have to walk.
-export const explain = (policy, file) => Effect.gen(function* () {
+export const explain = (policy, file, roots = ["packages"]) => Effect.gen(function* () {
     const relative = path.relative(policy.repoRoot, path.resolve(policy.repoRoot, file));
     const selected = rulesSelecting(policy.importRules, relative);
     // An allowlist rule names no `to` — it fires when the target matches none of
@@ -719,10 +555,15 @@ export const explain = (policy, file) => Effect.gen(function* () {
             .map((rule) => `${named(rule)} (reach)`),
     ];
     const section = (title, lines) => lines.length === 0 ? [] : ["", title, ...lines];
-    // Each campaign selecting the file, with its truth table: one line per
-    // leaf term and what it answered here, so a detector that "should fire"
-    // and does not shows which term is not saying what its author thinks.
-    const selectedCampaigns = campaignsSelecting(policy.campaignRules, relative);
+    // Each campaign selecting the file: the sector the file is in, its
+    // phase and definedness, the objectives in window that fire on it and
+    // the nearest remaining holdouts — which needs the campaign evaluated
+    // over its files, since a sector's phase is derived from all of them —
+    // then each objective's truth table: one line per leaf term and what
+    // it answered here, so a detector that "should fire" and does not shows
+    // which term is not saying what its author thinks.
+    const selectedCampaigns = campaignsSelecting(campaignsOf(policy).campaignRules, relative);
+    const evaluations = selectedCampaigns.length === 0 ? [] : collectFindings(policy, roots).campaigns;
     const campaignLines = selectedCampaigns.flatMap((rule) => {
         const at = path.join(policy.repoRoot, relative);
         const text = existsSync(at) ? readFileSync(at, "utf8") : "";
@@ -733,13 +574,22 @@ export const explain = (policy, file) => Effect.gen(function* () {
             resolver: policy.resolver,
             fileSystem: policy.fileSystem,
             syntax: policy.syntax.parse(relative, text),
-            functions: policy.functions,
-            reports: policy.reports,
+            functions: campaignsOf(policy).functions,
+            reports: campaignsOf(policy).reports,
         };
-        const hits = evaluateCampaigns([rule], input);
+        const evaluation = evaluations.find((one) => one.rule.id === rule.id);
         return [
-            `    ${rule.name} — ${firstSentence(rule.why)} (${rule.unit}; ${hits.length === 0 ? "no hit" : count(hits.length, "hit")})`,
-            ...explainCampaign(rule, input).map((line) => `        ${line.answer ? "✓" : "✗"} ${line.term}${line.count === undefined ? "" : ` (${String(line.count)})`}`),
+            ...(evaluation === undefined ? [] : explainCampaignLines(policy, evaluation, relative)),
+            ...rule.objectives.flatMap((objective) => {
+                const table = explainObjective(objective, input);
+                if (table.length === 0)
+                    return [];
+                const fired = table.length > 0 && table.every((line) => line.answer);
+                return [
+                    `      ${objective.name} — ${firstSentence(objective.why ?? objective.message)} (${objective.holdout}; ${fired ? "fires here" : "no hit"})`,
+                    ...table.map((line) => `          ${line.answer ? "✓" : "✗"} ${line.term}${line.count === undefined ? "" : ` (${String(line.count)})`}`),
+                ];
+            }),
         ];
     });
     yield* report([
@@ -858,18 +708,23 @@ limits:
   unrestricted: 0
   partial: 0
 
-# Migrations the repository is running, each with a detector, a rationale, a
-# guide, an owner and a ledger of every place the pattern still occurs. Fill
-# one in, then \`architecture campaigns init <id>\` to write its ledger.
+# Refactors the repository is running, each an object: objectives (a
+# detector with a ledger under \`.architecture-campaigns/\` of every place the
+# pattern still occurs), over sectors the code births through a perimeter,
+# through phases toward an end. Fill one in, then
+# \`architecture objectives clear <id>\` to write its ledgers.
 # https://dataquail.github.io/goodbones/architecture-rules/manifest/campaigns/
 # campaigns:
-#   - id: js-to-ts
+#   js-to-ts:
 #     why: The strict tsconfig cannot land while any src file is JavaScript.
 #     how: Rename to .ts, add types at the module boundary, leave the body alone.
-#     scope: ["src/**"]
-#     unit: file
-#     detect: { path: { file: "\\.(js|jsx)$" } }
-#     probes: { fires: [{ path: src/legacy/util.js }], ignores: [{ path: src/util.ts }] }
+#     scope: { path: "src/**", extensions: [.js, .jsx] }
+#     perimeter: file
+#     objectives:
+#       is-ts:
+#         holdout: file
+#         match: { path: { file: "\\\\.(js|jsx)$" } }
+#         probes: { fires: [{ path: src/legacy/util.js }], ignores: [{ path: src/util.ts }] }
 #     staleAfter: 14d
 #     onComplete: remove
 
@@ -941,188 +796,361 @@ export const migrate = (repoRoot, configFilename) => Effect.gen(function* () {
         `Then delete ${path.basename(from)}: a repository with two manifests is refused.`,
     ]);
 });
-// The ledgers. `campaigns` alone is the status table; `init` writes a
-// campaign's first ledger from what fires today; `prune` removes what no
-// longer fires; `allow` is the one way an entry is added, and it records why.
-const ledgerPathOf = (policy, id) => path.resolve(policy.repoRoot, policy.ledgerDir, `${id}.json`);
-const writeLedger = (policy, ledger) => {
-    const at = ledgerPathOf(policy, ledger.id);
-    mkdirSync(path.dirname(at), { recursive: true });
-    writeFileSync(at, serializeLedger(ledger));
-};
-const campaignNamed = (policy, id) => policy.campaignRules.find((rule) => rule.id === id) ?? null;
-// The author of a regression: `--by`, else git's user.email, else the
-// GIT_AUTHOR_EMAIL the environment carries. Without one the record is refused
-// rather than written blank, since the record is the point.
-const authorOf = (given) => {
-    if (given !== undefined && given !== "")
-        return given;
-    try {
-        const email = execFileSync("git", ["config", "user.email"], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
-        if (email !== "")
-            return email;
-    }
-    catch {
-        // git absent, or no email configured
-    }
-    const fromEnvironment = process.env.GIT_AUTHOR_EMAIL;
-    return fromEnvironment === undefined || fromEnvironment === "" ? null : fromEnvironment;
-};
+// The campaign commands. `campaigns` alone is the status table; `status
+// --changed` is the nudge; `attest` and `note` write a sector's record;
+// `history` replays the ledgers' git history. The ledgers themselves are
+// written by `objectives clear` (the ledger reconciled with the code
+// wherever that is not a regression) and `objectives concede` (the one way
+// a holdout is added by hand, with a reason).
 const flagOf = (argv, flag) => {
     const at = argv.indexOf(flag);
     const value = at === -1 ? undefined : argv[at + 1];
     return value === undefined || value.startsWith("--") ? undefined : value;
 };
-const CAMPAIGN_SUBCOMMANDS = ["init", "prune", "allow"];
-const CAMPAIGN_VALUE_FLAGS = ["--reason", "--by", "--entries"];
-// `campaigns [init <id> | prune [<id>] | allow <id> --reason <text>] [roots…]`:
-// the subcommand and its id come first; whatever positional is left names
-// the roots to walk, as it does for every other command.
-export const campaignArgsOf = (argv, ids) => {
+const CAMPAIGN_SUBCOMMANDS = ["status", "attest", "note", "history", "clear", "concede"];
+const OBJECTIVE_SUBCOMMANDS = ["clear", "concede"];
+const VALUE_FLAGS = [
+    "--reason",
+    "--by",
+    "--holdouts",
+    "--entries",
+    "--sector",
+    "--campaign",
+    "--evidence",
+    "--base",
+    "--since",
+    "--hotfix",
+];
+// The verbs the family shipped with, refused by name: each has a new name
+// or no place.
+const RETIRED = {
+    init: "`campaigns init` is gone: `objectives clear <campaign>` writes a first ledger, recording each sector's initial.",
+    prune: "`campaigns prune` is now `objectives clear`.",
+    allow: "`campaigns allow` is now `objectives concede`.",
+};
+// The positionals after the subcommand, with the value flags and their
+// values stepped over: whatever is left names the roots to walk, as it
+// does for every other command.
+const positionalsOf = (argv) => {
     const positional = [];
     for (let at = 0; at < argv.length; at += 1) {
         const one = argv[at] ?? "";
-        if (CAMPAIGN_VALUE_FLAGS.includes(one)) {
+        if (VALUE_FLAGS.includes(one)) {
             at += 1;
             continue;
         }
         if (!one.startsWith("--"))
             positional.push(one);
     }
+    return positional;
+};
+// `campaigns [status | attest <sector> <phase> | note <sector> "<text>" |
+// history [<campaign>]] [roots…]`: the subcommand and its arguments come
+// first.
+export const campaignArgsOf = (argv, ids) => {
+    const positional = positionalsOf(argv);
+    const [first, ...rest] = positional;
+    if (first === undefined)
+        return { subcommand: undefined, args: [], roots: [] };
+    if (first in RETIRED)
+        return { subcommand: first, args: [], roots: rest };
+    if (!CAMPAIGN_SUBCOMMANDS.includes(first)) {
+        return { subcommand: undefined, args: [], roots: positional };
+    }
+    switch (first) {
+        case "attest":
+            return { subcommand: first, args: rest.slice(0, 2), roots: rest.slice(2) };
+        case "note":
+            return { subcommand: first, args: rest.slice(0, 2), roots: rest.slice(2) };
+        case "history": {
+            const [second] = rest;
+            return second !== undefined && ids.includes(second)
+                ? { subcommand: first, args: [second], roots: rest.slice(1) }
+                : { subcommand: first, args: [], roots: rest };
+        }
+        case "clear":
+        case "concede": {
+            const [second] = rest;
+            return second !== undefined && ids.includes(second.split("/")[0] ?? "")
+                ? { subcommand: first, args: [second], roots: rest.slice(1) }
+                : { subcommand: first, args: [], roots: rest };
+        }
+        default:
+            return { subcommand: first, args: [], roots: rest };
+    }
+};
+// `objectives [clear [<campaign>[/<objective>]] | concede <campaign>[/<objective>]
+// --reason <text>] [roots…]`.
+export const objectiveArgsOf = (argv, ids) => {
+    const positional = positionalsOf(argv);
     const [first, second, ...rest] = positional;
-    if (first === undefined || !CAMPAIGN_SUBCOMMANDS.includes(first)) {
-        return { subcommand: undefined, id: undefined, roots: positional };
+    if (first === undefined || !OBJECTIVE_SUBCOMMANDS.includes(first)) {
+        return { subcommand: first, target: null, roots: positional.slice(1) };
     }
-    // `prune` takes an optional id; the next word is one only if a campaign
-    // has that name, else it is a root.
-    const takesId = first !== "prune" || (second !== undefined && ids.includes(second));
-    return takesId
-        ? { subcommand: first, id: second, roots: rest }
-        : { subcommand: first, id: undefined, roots: second === undefined ? [] : [second, ...rest] };
+    const [campaign = "", objective] = (second ?? "").split("/");
+    const named = second !== undefined && ids.includes(campaign);
+    return {
+        subcommand: first,
+        target: named ? { campaign, objective: objective ?? null } : null,
+        roots: named ? rest : second === undefined ? [] : [second, ...rest],
+    };
 };
-export const campaigns = (policy, defaultRoots, argv) => Effect.gen(function* () {
-    const parsed = campaignArgsOf(argv, policy.campaignRules.map((rule) => rule.id));
-    const { id, subcommand } = parsed;
+// The one campaign, when there is one, else the one `--campaign` names.
+const campaignFor = (policy, argv) => {
+    const named = flagOf(argv, "--campaign");
+    if (named !== undefined) {
+        const found = campaignsOf(policy).campaignRules.find((rule) => rule.id === named);
+        return found === undefined
+            ? Result.fail(`no campaign is named "${named}"`)
+            : Result.succeed(found);
+    }
+    const [only] = campaignsOf(policy).campaignRules;
+    if (campaignsOf(policy).campaignRules.length === 1 && only !== undefined)
+        return Result.succeed(only);
+    return Result.fail(`this policy declares ${String(campaignsOf(policy).campaignRules.length)} campaigns; say which with --campaign <id>.`);
+};
+const objectiveFor = (rule, objective) => {
+    if (objective !== null) {
+        return rule.objectives.some((one) => one.id === objective)
+            ? Result.succeed(objective)
+            : Result.fail(`no objective of ${rule.id} is named "${objective}"`);
+    }
+    const [only] = rule.objectives;
+    if (rule.objectives.length === 1 && only !== undefined)
+        return Result.succeed(only.id);
+    return Result.fail(`campaign ${rule.id} declares ${String(rule.objectives.length)} objectives; say which as ${rule.id}/<objective>.`);
+};
+export const objectives = (policy, defaultRoots, argv) => Effect.gen(function* () {
+    const parsed = objectiveArgsOf(argv, campaignsOf(policy).campaignRules.map((rule) => rule.id));
     const roots = parsed.roots.length > 0 ? parsed.roots : defaultRoots;
-    if (policy.campaignRules.length === 0) {
+    if (campaignsOf(policy).campaignRules.length === 0) {
         return yield* report(["this policy declares no campaigns."]);
     }
-    const hitsOf = () => collectFindings(policy, roots).campaigns;
-    const own = (hits, campaign) => hits.filter((hit) => hit.campaign === campaign).map((hit) => hit.violation);
-    switch (subcommand) {
-        case undefined: {
-            const snapshot = snapshotOf(policy, roots, manifestPathOf(policy.repoRoot));
-            return yield* report([
-                `${count(snapshot.campaigns.length, "campaign")} under ${roots.join(", ")}`,
-                "",
-                ...renderCampaignRows(snapshot.campaigns),
-                "",
-                "  architecture campaigns init <id>                       # write a ledger from what fires today",
-                "  architecture campaigns prune [<id>]                    # drop entries that no longer fire",
-                '  architecture campaigns allow <id> --reason "<why>"     # record why the count may rise',
-            ]);
-        }
-        case "init": {
-            if (id === undefined)
-                return yield* Effect.fail(fail("campaigns init needs a campaign id"));
-            const rule = campaignNamed(policy, id);
-            if (rule === null)
-                return yield* Effect.fail(fail(`no campaign is named "${id}"`));
-            if (policy.ledgers.has(id)) {
-                return yield* Effect.fail(fail(`${path.relative(policy.repoRoot, ledgerPathOf(policy, id))} already exists. \`init\` ` +
-                    `writes a campaign's first ledger and does not overwrite one; \`prune\` and \`allow\` ` +
-                    `are how it changes.`));
-            }
-            const ledger = ledgerOf(id, own(hitsOf(), id), policy.now);
-            yield* Effect.sync(() => {
-                writeLedger(policy, ledger);
-            });
-            return yield* report([
-                `${count(ledger.entries.length, "hit")} recorded in ${path.relative(policy.repoRoot, ledgerPathOf(policy, id))}.`,
-                "Each one is a place the campaign has yet to reach. Fixing one means pruning its line.",
-            ]);
-        }
-        case "prune": {
-            const targets = id === undefined
-                ? policy.campaignRules
-                : [campaignNamed(policy, id)].filter((one) => one !== null);
-            if (id !== undefined && targets.length === 0) {
-                return yield* Effect.fail(fail(`no campaign is named "${id}"`));
-            }
-            const hits = hitsOf();
+    const evaluations = () => collectFindings(policy, roots).campaigns;
+    switch (parsed.subcommand) {
+        case "clear": {
+            const targets = parsed.target === null
+                ? campaignsOf(policy).campaignRules
+                : campaignsOf(policy).campaignRules.filter((rule) => rule.id === parsed.target?.campaign);
+            const by = authorOf(flagOf(argv, "--by")) ?? "unknown";
+            const all = evaluations();
             const lines = [];
             for (const rule of targets) {
-                const ledger = policy.ledgers.get(rule.id);
-                if (ledger === undefined) {
-                    lines.push(`${rule.id}: no ledger to prune (run \`campaigns init ${rule.id}\`).`);
-                    continue;
-                }
-                const next = pruned(ledger, own(hits, rule.id), rule.unit, policy.now);
-                const removed = ledger.entries.length - next.entries.length;
-                const rewritten = next.entries.filter((entry) => !ledger.entries.includes(entry)).length;
-                if (removed === 0 && rewritten === 0) {
-                    lines.push(`${rule.id}: nothing to prune.`);
+                const evaluation = all.find((one) => one.rule.id === rule.id);
+                if (evaluation === undefined)
                     continue;
+                const only = parsed.target?.objective ?? null;
+                if (only !== null && !rule.objectives.some((one) => one.id === only)) {
+                    return yield* Effect.fail(fail(`no objective of ${rule.id} is named "${only}"`));
                 }
-                yield* Effect.sync(() => {
-                    writeLedger(policy, next);
+                const outcomes = yield* Effect.try({
+                    try: () => clear(policy, evaluation, only, by),
+                    catch: (cause) => fail(String(cause)),
                 });
-                lines.push(`${rule.id}: ${count(removed, "entry", "entries")} pruned` +
-                    (rewritten > 0 ? `, ${count(rewritten, "entry", "entries")} rewritten` : "") +
-                    `; ${count(next.entries.length, "entry", "entries")} left.`);
+                for (const outcome of outcomes) {
+                    const parts = [
+                        ...(outcome.entered.length > 0
+                            ? [
+                                `${count(outcome.entered.length, "sector")} entered (${outcome.entered.join(", ")})`,
+                            ]
+                            : []),
+                        ...(outcome.cleared > 0 ? [`${count(outcome.cleared, "holdout")} cleared`] : []),
+                        ...(outcome.rewritten > 0
+                            ? [`${count(outcome.rewritten, "holdout")} rewritten`]
+                            : []),
+                        ...(outcome.closed > 0 ? [`${count(outcome.closed, "holdout")} closed`] : []),
+                        ...(outcome.rebaselined.length > 0
+                            ? [
+                                `${count(outcome.rebaselined.length, "sector")} re-baselined (${outcome.rebaselined.join(", ")})`,
+                            ]
+                            : []),
+                    ];
+                    lines.push(`${outcome.campaign}/${outcome.objective}: ${parts.length === 0 ? "nothing to clear" : parts.join(", ")}; ${count(outcome.left, "holdout")} left.`);
+                }
             }
             return yield* report(lines);
         }
-        case "allow": {
-            if (id === undefined)
-                return yield* Effect.fail(fail("campaigns allow needs a campaign id"));
-            const rule = campaignNamed(policy, id);
-            if (rule === null)
-                return yield* Effect.fail(fail(`no campaign is named "${id}"`));
-            const ledger = policy.ledgers.get(id);
-            if (ledger === undefined) {
-                return yield* Effect.fail(fail(`campaign ${id} has no ledger yet; run \`campaigns init ${id}\` first.`));
+        case "concede": {
+            if (parsed.target === null) {
+                return yield* Effect.fail(fail("objectives concede needs a campaign: `objectives concede <campaign>[/<objective>] --reason <text>`"));
             }
+            const rule = campaignsOf(policy).campaignRules.find((one) => one.id === parsed.target?.campaign);
+            if (rule === undefined)
+                return yield* Effect.fail(fail(`no campaign is named "${parsed.target.campaign}"`));
+            const objective = objectiveFor(rule, parsed.target.objective);
+            if (Result.isFailure(objective))
+                return yield* Effect.fail(fail(objective.failure));
             const reason = flagOf(argv, "--reason");
             if (reason === undefined) {
-                return yield* Effect.fail(fail("campaigns allow needs --reason <text>: growth is recorded with why, or not at all."));
+                return yield* Effect.fail(fail("objectives concede needs --reason <text>: growth is recorded with why, or not at all."));
             }
             const by = authorOf(flagOf(argv, "--by"));
             if (by === null) {
-                return yield* Effect.fail(fail("campaigns allow needs an author: pass --by <email>, or set git's user.email."));
+                return yield* Effect.fail(fail("objectives concede needs an author: pass --by <email>, or set git's user.email."));
             }
-            const state = reconcile(ledger, own(hitsOf(), id), rule.unit);
-            const unrecorded = [...new Set(state.unrecorded.map(entryOf))].sort();
-            // `--entries` allows a subset and refuses the rest: a pull request
-            // that legitimately adds one hit while another is an accident.
-            const chosen = flagOf(argv, "--entries")
+            const evaluation = evaluations().find((one) => one.rule.id === rule.id);
+            if (evaluation === undefined)
+                return yield* Effect.fail(fail(`campaign ${rule.id} was not evaluated`));
+            // `--holdouts` concedes a subset and refuses the rest: a pull
+            // request that legitimately adds one hit while another is an
+            // accident.
+            const chosen = (flagOf(argv, "--holdouts") ?? flagOf(argv, "--entries"))
                 ?.split(",")
-                .map((one) => one.trim()) ?? unrecorded;
-            const unknown = chosen.filter((entry) => !unrecorded.includes(entry));
-            if (unknown.length > 0) {
-                return yield* Effect.fail(fail(`these entries are not unrecorded hits of ${id}: ${unknown.join(", ")}`));
+                .map((one) => one.trim()) ?? null;
+            const outcome = concede(policy, evaluation, objective.success, chosen, flagOf(argv, "--sector") ?? null, {
+                at: policy.now,
+                by,
+                reason,
+            });
+            if (Result.isFailure(outcome))
+                return yield* Effect.fail(fail(outcome.failure));
+            if (outcome.success.conceded.length === 0) {
+                return yield* report([
+                    `${rule.id}/${objective.success}: nothing to concede; every hit is in the ledger.`,
+                ]);
+            }
+            return yield* report([
+                `${rule.id}/${objective.success}: ${count(outcome.success.conceded.length, "holdout")} conceded, recorded by ${by}.`,
+                ...outcome.success.conceded.map((one) => `  ${one.sector} · ${one.entry}`),
+                ...(outcome.success.left.length === 0
+                    ? []
+                    : [
+                        "",
+                        `${count(outcome.success.left.length, "hit")} left unrecorded; check still fails on them.`,
+                    ]),
+            ]);
+        }
+        default:
+            return yield* Effect.fail(fail(`unknown objectives subcommand "${parsed.subcommand ?? ""}". Try: objectives clear [<campaign>[/<objective>]] | objectives concede <campaign>[/<objective>] --reason <text> [--by <email>] [--sector <name>] [--holdouts a,b]`));
+    }
+});
+export const campaigns = (policy, defaultRoots, argv, configFilename) => Effect.gen(function* () {
+    const parsed = campaignArgsOf(argv, campaignsOf(policy).campaignRules.map((rule) => rule.id));
+    const roots = parsed.roots.length > 0 ? parsed.roots : defaultRoots;
+    if (campaignsOf(policy).campaignRules.length === 0) {
+        return yield* report(["this policy declares no campaigns."]);
+    }
+    const json = argv.includes("--json");
+    const retired = parsed.subcommand === undefined ? undefined : RETIRED[parsed.subcommand];
+    if (retired !== undefined)
+        return yield* Effect.fail(fail(retired));
+    switch (parsed.subcommand) {
+        case undefined: {
+            const snapshot = snapshotOf(policy, roots, manifestPathOf(policy.repoRoot, configFilename));
+            return yield* report([
+                `${count(snapshot.campaigns.length, "campaign")} under ${roots.join(", ")}`,
+                "",
+                ...renderCampaignRows(snapshot.campaigns),
+                "",
+                "  architecture campaigns status --changed [--base <ref>] [--json]   # what a diff touches, and what to do",
+                "  architecture objectives clear [<campaign>[/<objective>]]        # reconcile the ledgers with the code",
+                '  architecture objectives concede <campaign>[/<objective>] --reason "<why>"   # record why a count may rise',
+                '  architecture campaigns attest <sector> <phase> --reason "<why>" [--evidence <url>]',
+                '  architecture campaigns note <sector> "<text>"',
+                "  architecture campaigns history [<campaign>] [--since <ref>]",
+            ]);
+        }
+        case "status": {
+            if (!argv.includes("--changed")) {
+                return yield* Effect.fail(fail("campaigns status takes --changed: the nudge is scoped to a diff."));
             }
-            if (chosen.length === 0) {
-                return yield* report([`${id}: nothing to allow; every hit is in the ledger.`]);
+            const base = flagOf(argv, "--base") ?? null;
+            const diff = yield* Effect.try({
+                try: () => readDiff(policy.repoRoot, base),
+                catch: (cause) => fail(`could not read the diff: ${String(cause)}`),
+            });
+            const current = collectFindings(policy, roots).campaigns;
+            const baseSide = base === null
+                ? null
+                : yield* Effect.tryPromise({
+                    try: () => baseSideAt(policy, base, roots, (repoRoot) => loadPolicyFromFile(repoRoot, configFilename)),
+                    catch: (cause) => fail(`could not evaluate the base tree at ${base}: ${String(cause)}`),
+                });
+            const hotfix = flagOf(argv, "--hotfix") ?? null;
+            const nudge = nudgeOf(policy, current, diff, baseSide, hotfix, hotfix === null ? null : authorOf(flagOf(argv, "--by")));
+            yield* report(json ? [JSON.stringify(nudge, null, 2)] : renderNudge(nudge, policy.now));
+            if (!nudge.ok)
+                return yield* Effect.fail(fail("the diff sends a sector back under its onTouch"));
+            return;
+        }
+        case "attest": {
+            const [sector, phase] = parsed.args;
+            if (sector === undefined || phase === undefined) {
+                return yield* Effect.fail(fail('campaigns attest needs a sector and a phase: `campaigns attest <sector> <phase> --reason "<why>"`'));
             }
-            const next = allowed(ledger, chosen, { at: policy.now, by, reason });
-            yield* Effect.sync(() => {
-                writeLedger(policy, next);
+            const reason = flagOf(argv, "--reason");
+            if (reason === undefined)
+                return yield* Effect.fail(fail("campaigns attest needs --reason <text>."));
+            const by = authorOf(flagOf(argv, "--by"));
+            if (by === null)
+                return yield* Effect.fail(fail("campaigns attest needs an author: pass --by <email>, or set git's user.email."));
+            const rule = campaignFor(policy, argv);
+            if (Result.isFailure(rule))
+                return yield* Effect.fail(fail(rule.failure));
+            const evaluation = collectFindings(policy, roots).campaigns.find((one) => one.rule.id === rule.success.id);
+            if (evaluation === undefined)
+                return yield* Effect.fail(fail(`campaign ${rule.success.id} was not evaluated`));
+            const written = attest(policy, evaluation, sector, phase, {
+                reason,
+                evidence: flagOf(argv, "--evidence"),
+                by,
             });
-            const left = unrecorded.filter((entry) => !chosen.includes(entry));
+            if (Result.isFailure(written))
+                return yield* Effect.fail(fail(written.failure));
             return yield* report([
-                `${id}: ${count(chosen.length, "entry", "entries")} allowed, recorded as a regression by ${by}.`,
-                ...chosen.map((entry) => `  ${entry}`),
-                ...(left.length === 0
-                    ? []
-                    : ["", `${count(left.length, "hit")} left unrecorded; check still fails on them.`]),
+                `${rule.success.id}: sector ${sector} attested at ${phase} by ${by}, in ${written.success}.`,
+                "Run `objectives clear` to move it on.",
             ]);
         }
+        case "note": {
+            const [sector, text] = parsed.args;
+            if (sector === undefined || text === undefined) {
+                return yield* Effect.fail(fail('campaigns note needs a sector and a text: `campaigns note <sector> "<text>"`'));
+            }
+            const by = authorOf(flagOf(argv, "--by"));
+            if (by === null)
+                return yield* Effect.fail(fail("campaigns note needs an author: pass --by <email>, or set git's user.email."));
+            const rule = campaignFor(policy, argv);
+            if (Result.isFailure(rule))
+                return yield* Effect.fail(fail(rule.failure));
+            const evaluation = collectFindings(policy, roots).campaigns.find((one) => one.rule.id === rule.success.id);
+            if (evaluation === undefined)
+                return yield* Effect.fail(fail(`campaign ${rule.success.id} was not evaluated`));
+            const written = note(policy, evaluation, sector, text, by);
+            if (Result.isFailure(written))
+                return yield* Effect.fail(fail(written.failure));
+            return yield* report([
+                `${rule.success.id}: note left on ${sector}, in ${written.success}.`,
+            ]);
+        }
+        case "history": {
+            const [named] = parsed.args;
+            const targets = named === undefined
+                ? campaignsOf(policy).campaignRules
+                : campaignsOf(policy).campaignRules.filter((rule) => rule.id === named);
+            const manifestPath = path
+                .relative(policy.repoRoot, manifestPathOf(policy.repoRoot, configFilename))
+                .replaceAll(path.sep, "/");
+            const lines = [];
+            for (const rule of targets) {
+                const rows = historyOf(policy, rule, flagOf(argv, "--since") ?? null, [manifestPath]);
+                if (json) {
+                    lines.push(JSON.stringify({ campaign: rule.id, rows }, null, 2));
+                    continue;
+                }
+                if (lines.length > 0)
+                    lines.push("");
+                for (const line of renderHistory(rule, rows))
+                    lines.push(line);
+            }
+            return yield* report(lines);
+        }
+        case "clear":
+        case "concede":
+            // The ledger verbs answer under `objectives`; accepted here too.
+            return yield* objectives(policy, defaultRoots, argv);
         default:
-            return yield* Effect.fail(fail(`unknown campaigns subcommand "${subcommand}". Try: campaigns | campaigns init <id> | campaigns prune [<id>] | campaigns allow <id> --reason <text> [--by <email>] [--entries a,b]`));
+            return yield* Effect.fail(fail(`unknown campaigns subcommand "${parsed.subcommand}". Try: campaigns | campaigns status --changed | campaigns attest <sector> <phase> --reason <text> | campaigns note <sector> "<text>" | campaigns history [<campaign>]`));
     }
 });
 // The commands that judge a campaign, and so ask its report source.
@@ -1131,6 +1159,7 @@ const READS_REPORTS = new Set([
     "conformance",
     "baseline",
     "campaigns",
+    "objectives",
     "explain",
 ]);
 export const run = (repoRoot, argv, 
@@ -1173,7 +1202,7 @@ configFilename) => Effect.gen(function* () {
     // for the campaign to report; a report that does not parse is refused.
     if (READS_REPORTS.has(command)) {
         yield* Effect.tryPromise({
-            try: () => Promise.all(reportSpecsOf(policy.campaignRules).map((spec) => policy.reports.read?.(spec))),
+            try: () => Promise.all(reportSpecsOf(campaignsOf(policy).campaignRules).map((spec) => campaignsOf(policy).reports.read?.(spec))),
             catch: (cause) => fail(String(cause)),
         });
     }
@@ -1184,7 +1213,9 @@ configFilename) => Effect.gen(function* () {
     const roots = positional.length > 0 ? positional : ["packages"];
     switch (command) {
         case "campaigns":
-            return yield* campaigns(policy, ["packages"], rest);
+            return yield* campaigns(policy, ["packages"], rest, configFilename);
+        case "objectives":
+            return yield* objectives(policy, ["packages"], rest);
         case "check":
             return yield* check(policy, roots, {
                 format: json ? "json" : "text",
@@ -1198,10 +1229,10 @@ configFilename) => Effect.gen(function* () {
         case "baseline":
             return yield* writeBaseline(policy, roots);
         case "explain": {
-            const [file] = rest;
+            const [file, ...explainRoots] = positional;
             if (file === undefined)
                 return yield* Effect.fail(fail("explain needs a file path"));
-            return yield* explain(policy, file);
+            return yield* explain(policy, file, explainRoots.length > 0 ? explainRoots : ["packages"]);
         }
         case "coverage":
             return yield* coverage(policy, roots);
@@ -1212,7 +1243,7 @@ configFilename) => Effect.gen(function* () {
             return yield* facts(policy, file, json ? "json" : "text");
         }
         default:
-            return yield* Effect.fail(fail(`unknown command "${command}". Try: check [--json] | conformance [--json] [--against <manifest>] | baseline | campaigns [init <id> | prune [<id>] | allow <id> --reason <text>] | coverage | explain <file> | facts <file> [--json] | init | infer | migrate`));
+            return yield* Effect.fail(fail(`unknown command "${command}". Try: check [--json] | conformance [--json] [--against <manifest>] | baseline | campaigns [status --changed | attest | note | history] | objectives [clear | concede] | coverage | explain <file> | facts <file> [--json] | init | infer | migrate`));
     }
 });
 export const fingerprint = fingerprintOf;