@codyswann/lisa 4.19.0 → 4.21.0

package/package.json

@@ -74,6 +74,7 @@
     "verify:health-contract": "bun run build:dist && node scripts/verify-health-contract-built.mjs",
     "verify:health-deterministic": "bun run build:dist && node scripts/verify-health-deterministic-built.mjs",
     "verify:learner-frontmatter-built": "bun run build:dist && node scripts/verify-learner-frontmatter-built.mjs",
+    "verify:packed-learnings-contract": "bun run build:dist && node scripts/verify-packed-learnings-contract.mjs",
     "verify:health-agentic": "bun run build:dist && node scripts/verify-health-agentic-built.mjs",
     "verify:health-consumer": "bun run build:dist && node scripts/verify-health-consumer-built.mjs",
     "lint:staged": "lint-staged --config .lintstagedrc.json"
@@ -158,7 +159,7 @@
     "zod-validation-error": "^4.0.0"
   },
   "name": "@codyswann/lisa",
-  "version": "4.19.0",
+  "version": "4.21.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {
@@ -297,5 +298,5 @@
     "vite": "^8.0.16"
   },
   "type": "module",
-  "lisaReleaseCommit": "41fe63822ee1b74abcd798e71c25ebd33e12278b"
+  "lisaReleaseCommit": "f6790eefec944b90abd6c8536b01ca41c2203354"
 }

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.19.0",
+  "version": "4.21.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.19.0",
+  "version": "4.21.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/skills/lisa-debrief-apply/SKILL.md

@@ -51,15 +51,16 @@ For each such Accepted row:
    ```
 
 2. **Consolidation check (mandatory before writing).** Parse the existing entries with `parseLearningsFile` and look for one related to the row (same failure class, overlapping topic, or near-duplicate wording). Then write through the contract:
-   - **Related entry found** → consolidate via `persistConsolidatedLearning(projectRoot, entry, { supersede: [<related ids>] })`, merging the old entry's still-true content into the new rule. Never append a near-duplicate sibling — a sibling is a bug.
+   - **Related entry found** → consolidate with the exact parsed versions: `persistConsolidatedLearning(projectRoot, entry, { supersede: [{ id: <related id>, fingerprint: <related fingerprint> }], onStaleSupersede: targets => report(targets) })`. Every stamp is checked together inside the writer lock. If any is stale, the writer removes none, safely appends the new fingerprint, and reports the mismatch. Never append a near-duplicate sibling by choice — a sibling is a bug; the stale append is the deliberate concurrent-writer preservation path.
    - **No related entry** → append via `persistLearningEntry(projectRoot, entry)`.
 
-3. **Entry mapping (seven fields).**
-   - `id` — the entry id returned by the contract writer (report it in the run summary).
+3. **Entry mapping (eight fields).**
+   - `fingerprint` — `debrief-` + the first 12 hex characters of `sha1(normalized_rule + "\n" + sorted_provenance.join("\n"))`, where the rule is lowercased with whitespace collapsed and provenance is sorted by codepoint. Compute it mechanically, never estimate it.
+   - `id` — initially `id = fingerprint`. On an exact stamped consolidation the writer carries forward the deterministic primary target id; report the returned id in the run summary.
    - `rule` / `why` — from the row's `Summary` and the category-specific guidance in the routing table above (≤240 chars, ≤2 lines).
    - `provenance` — **the triage-doc row's evidence links**. This is the same evidence link that doubles as the idempotency fingerprint below, so the row's provenance is what a later re-apply scans for.
    - `first_learned` = `last_confirmed` = today (ISO date; on consolidation keep the superseded entry's earliest `first_learned`).
-   - `confidence` = **`high`**. A human marking the row **Accept** is corroboration — an independent human judgement that the learning is real — so a debrief-accepted entry starts higher than the learner's single-occurrence auto-capture (which defaults to `low`). The writer re-asserts the entry and token budgets; an over-budget failure means consolidate harder or drop, never truncate by hand.
+   - `confidence` = **`high`**. A human marking the row **Accept** is corroboration — an independent human judgement that the learning is real — so a debrief-accepted entry starts higher than the learner's single-occurrence auto-capture (which defaults to `low`). A duplicate fingerprint fails before mutation. The writer re-asserts the entry and token budgets; an over-budget failure means consolidate harder or drop, never truncate by hand.
 
 **Machine-local memory is no longer a knowledge destination.** Auto-memory (`project_*.md`, `MEMORY.md`) remains available only for the assistant's *personal* collaboration notes — it is invisible to cloud runs and to teammates, so it can never hold shared project knowledge. **`AGENTS.md` is human-authored** agent operating instruction — it is the source of truth, and `CLAUDE.md` is only a one-line `@AGENTS.md` pointer — and the host-rules directory `.agents/rules/` is durable human-authored guidance; `apply` never writes to any of the three for these categories.
 

package/plugins/lisa/.codex-plugin/skills/lisa-persist-learning/SKILL.md

@@ -171,9 +171,9 @@ No learning content is ever committed without a PR — there is no other write p
    ```
 
 3. **Consolidation check (mandatory before writing).** Parse the existing entries (`parseLearningsFile` from `@codyswann/lisa/learnings`) and look for entries related to the new rule (same failure class, overlapping topic, or near-duplicate wording). Then write through the executable contract — **never hand-edit the markdown**:
-   - **Related entry found** → consolidate via `persistConsolidatedLearning(projectRoot, entry, { supersede: [<related ids>] })`, merging the old entry's still-true content into the new rule. Never append a near-duplicate sibling — a sibling is a bug that fails review.
+   - **Related entry found** → consolidate with the exact versions returned by the parser: `persistConsolidatedLearning(projectRoot, entry, { supersede: [{ id: <related id>, fingerprint: <related fingerprint> }], onStaleSupersede: targets => report(targets) })`. The writer checks every stamp together inside the lock. If any target is absent or its fingerprint changed, the whole supersede is stale: it removes nothing, safely appends the new fingerprint, and reports the mismatch. Never append a near-duplicate sibling by choice — a sibling is a bug that fails review; the writer's stale append is the deliberate race-safe preservation path.
    - **No related entry** → append via `persistLearningEntry(projectRoot, entry)` and state in the PR body why appending was correct.
-   - Entry mapping: `id` = the fingerprint; `rule`/`why`/`provenance` from the candidate; `first_learned` = `last_confirmed` = today (ISO date; on consolidation keep the superseded entry's earliest `first_learned`); `confidence` = the judge's `high`/`low`. The writer re-asserts the entry and token budgets — an over-budget failure means consolidate harder or drop, never truncate by hand.
+   - Entry mapping (eight fields): `fingerprint` = the deterministic Phase 0 fingerprint and initial `id = fingerprint`; `rule`/`why`/`provenance` from the candidate; `first_learned` = `last_confirmed` = today (ISO date; on consolidation keep the superseded entry's earliest `first_learned`); `confidence` = the judge's `high`/`low`. On an exact stamped consolidation the writer carries forward the deterministic primary target id while persisting the new fingerprint as the version token. A duplicate fingerprint fails before mutation. The writer re-asserts the entry and token budgets — an over-budget failure means consolidate harder or drop, never truncate by hand.
    - **On a budget-forced drop, signal saturation once (never silent).** When the writer's budget re-assertion cannot fit the entry even after consolidating harder — a durable capture has to be DROPPED for budget — the ledger is saturated, and that pressure must be visible to an operator instead of swallowed. Emit **exactly one** tracker signal via `lisa-tracker-write` (`issue_type: Task`; GitHub trackers carry the `type:Task` label), then continue — dropping the capture never blocks the build. Follow the same marker-dedupe discipline as every other comment here (match on the **marker, never the title**; **exactly one marker per body**; the eventual-consistency guard when the search index is stale), with **one deliberate difference: dedupe against OPEN signals only.** A *closed* saturation ticket means room was already reclaimed, so a fresh saturation is a new actionable event — searching closed tickets too (as the drop/upstream markers do) would permanently suppress every later saturation.
 
      The saturation fingerprint keys on the **ledger, not the candidate**, so the signal fires once per saturation episode — never once per capture:

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/publish-aws-bootstrap.mjs

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+/**
+ * Publish a newly emitted remote-agent AWS bootstrap bundle to the configured
+ * secrets provider without creating a silent split brain.
+ *
+ * Infrastructure owns the IAM access key and usually emits the complete bundle
+ * to AWS Secrets Manager. Remote coding environments cannot use that store as
+ * their bootstrap provider: reading it already requires AWS credentials. The
+ * provider configured by lisa-secrets-access therefore needs the same bundle,
+ * and a manual copy leaves two ways for a rotation to stop halfway.
+ *
+ * This command makes that handoff one fail-closed operation:
+ *
+ * 1. prove the existing provider record is writable with a no-op write;
+ * 2. validate the candidate and assume every declared role with it;
+ * 3. replace the provider value;
+ * 4. read the value back exactly and assume every role again; and
+ * 5. restore the previous provider value if a post-write check fails.
+ *
+ * The candidate arrives on stdin so it never appears in a shell command or a
+ * temporary file. No credential value is written to stdout or stderr.
+ *
+ * Usage:
+ *   aws secretsmanager get-secret-value ... --query SecretString --output text \
+ *     | publish-aws-bootstrap.mjs publish
+ *   publish-aws-bootstrap.mjs verify
+ *   publish-aws-bootstrap.mjs preflight
+ * @module publish-aws-bootstrap
+ */
+
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import {
+  BOOTSTRAP_KEY,
+  parseBootstrap,
+  readProfiles,
+} from "./aws-bootstrap.mjs";
+import { fetchAll, writeSecret } from "./providers.mjs";
+import { readConfig } from "./surfaces.mjs";
+
+import { boundedChildOutput } from "../../lisa-setup-workstation/scripts/bounded-child.mjs";
+
+const PROFILE_NAME = /^[\w.@-]+$/;
+const ROLE_ARN =
+  /^arn:(?:aws|aws-us-gov|aws-cn):iam::\d{12}:role\/[\w+=,.@/-]+$/;
+
+/**
+ * Validate and normalize one complete bundle without changing its serialized
+ * representation.
+ * @param {string} raw Candidate JSON from stdin or the provider.
+ * @returns {{raw: string, bundle: object, profiles: Array<{name: string, roleArn: string, region: string}>}}
+ *   Validated candidate and its role entries.
+ */
+export function validateAwsBootstrap(raw) {
+  if (typeof raw !== "string" || !raw.trim()) {
+    throw new Error(
+      `${BOOTSTRAP_KEY} is empty; refusing to replace a working credential with nothing`
+    );
+  }
+
+  // AWS CLI's text output ends with one newline. It is transport framing, not
+  // part of the SecretString, so do not make every publication differ by one
+  // invisible byte from the value AWS emitted.
+  const normalized = raw.trim();
+  const bundle = parseBootstrap(normalized);
+  if (!bundle || Array.isArray(bundle)) {
+    throw new Error(`${BOOTSTRAP_KEY} is not a JSON object`);
+  }
+
+  const accessKeyId = bundle.accessKeyId ?? bundle.aws_access_key_id;
+  const secretAccessKey =
+    bundle.secretAccessKey ?? bundle.aws_secret_access_key;
+  for (const [field, value] of [
+    ["accessKeyId", accessKeyId],
+    ["secretAccessKey", secretAccessKey],
+    ["externalId", bundle.externalId],
+    ["roleName", bundle.roleName],
+  ]) {
+    if (typeof value !== "string" || !value.trim()) {
+      throw new Error(`${BOOTSTRAP_KEY}.${field} must be a non-empty string`);
+    }
+  }
+
+  const entries = Object.entries(readProfiles(bundle));
+  if (entries.length === 0) {
+    throw new Error(`${BOOTSTRAP_KEY}.profiles must declare at least one role`);
+  }
+
+  const profiles = entries.map(([name, entry]) => {
+    if (!PROFILE_NAME.test(name)) {
+      throw new Error(`AWS bootstrap profile name is not safe: ${name}`);
+    }
+    const roleArn = entry?.roleArn ?? entry?.role_arn;
+    if (typeof roleArn !== "string" || !ROLE_ARN.test(roleArn)) {
+      throw new Error(`AWS bootstrap profile ${name} has an invalid roleArn`);
+    }
+    if (typeof entry?.region !== "string" || !entry.region.trim()) {
+      throw new Error(`AWS bootstrap profile ${name} has no region`);
+    }
+    return { name, roleArn, region: entry.region };
+  });
+
+  return { raw: normalized, bundle, profiles };
+}
+
+/**
+ * Build the isolated environment used to prove one candidate. Ambient AWS
+ * variables are removed so a green result cannot come from the host identity.
+ * @param {object} bundle Validated bundle.
+ * @returns {NodeJS.ProcessEnv} Child environment containing only this identity.
+ */
+export function candidateAwsEnvironment(bundle) {
+  const env = { ...process.env };
+  for (const key of [
+    "AWS_PROFILE",
+    "AWS_DEFAULT_PROFILE",
+    "AWS_SESSION_TOKEN",
+    "AWS_SECURITY_TOKEN",
+  ]) {
+    delete env[key];
+  }
+  env.AWS_ACCESS_KEY_ID = String(
+    bundle.accessKeyId ?? bundle.aws_access_key_id
+  );
+  env.AWS_SECRET_ACCESS_KEY = String(
+    bundle.secretAccessKey ?? bundle.aws_secret_access_key
+  );
+  env.AWS_PAGER = "";
+  return env;
+}
+
+/**
+ * Prove that the candidate authenticates and can assume every declared role.
+ * Captures all child output so account ids and credential metadata never reach
+ * a shared log.
+ * @param {{bundle: object, profiles: Array<object>}} candidate Validated bundle.
+ * @param {(bin: string, args: string[], options: object) => string} [run]
+ *   Injectable child runner for tests.
+ */
+export function verifyAwsBootstrap(candidate, run = boundedChildOutput) {
+  const env = candidateAwsEnvironment(candidate.bundle);
+  for (const profile of candidate.profiles) {
+    const sessionName = `lisa-publish-${profile.name}`
+      .replace(/[^A-Za-z0-9_+=,.@-]/g, "-")
+      .slice(0, 64);
+    try {
+      run(
+        "aws",
+        [
+          "sts",
+          "assume-role",
+          "--role-arn",
+          profile.roleArn,
+          "--role-session-name",
+          sessionName,
+          "--external-id",
+          String(candidate.bundle.externalId),
+          "--region",
+          profile.region,
+          "--query",
+          "Credentials.Expiration",
+          "--output",
+          "text",
+        ],
+        { encoding: "utf8", env, stdio: ["ignore", "pipe", "pipe"] }
+      );
+    } catch (error) {
+      const reason =
+        error instanceof Error ? error.message.split("\n")[0] : String(error);
+      throw new Error(
+        `AWS bootstrap profile ${profile.name} failed STS verification: ${reason}`
+      );
+    }
+  }
+  return candidate.profiles.map(profile => profile.name);
+}
+
+/**
+ * Locate the provider record that owns the bundle.
+ * @param {object} cfg Resolved lisa-secrets-access configuration.
+ * @param {(cfg: object) => Map<string, object>} fetch Provider reader.
+ * @returns {{id: string, value: string}} Writable provider entry.
+ */
+function currentEntry(cfg, fetch) {
+  const entry = fetch(cfg).get(BOOTSTRAP_KEY);
+  if (!entry) {
+    throw new Error(
+      `${BOOTSTRAP_KEY} is not available through the configured provider boundary`
+    );
+  }
+  if (!entry.id) {
+    throw new Error(
+      `${BOOTSTRAP_KEY} has no provider identifier, so it cannot be published`
+    );
+  }
+  return { id: entry.id, value: entry.value };
+}
+
+/**
+ * Exercise the exact provider write permission without changing its value.
+ * @param {object} cfg Resolved configuration.
+ * @param {object} [operations] Injectable provider operations for tests.
+ * @returns {{id: string, value: string}} Current provider entry.
+ */
+export function preflightAwsBootstrap(cfg, operations = {}) {
+  const fetch = operations.fetch ?? fetchAll;
+  const write = operations.write ?? writeSecret;
+  const entry = currentEntry(cfg, fetch);
+  try {
+    write(cfg, entry.id, entry.value);
+  } catch (error) {
+    const reason =
+      error instanceof Error ? error.message.split("\n")[0] : String(error);
+    throw new Error(
+      `no write access to ${BOOTSTRAP_KEY}: ${reason}\n` +
+        `Refusing to continue because a rotated key that cannot be published would strand every remote session.`
+    );
+  }
+  return entry;
+}
+
+/**
+ * Restore the previous provider value and prove the restoration.
+ * @param {object} cfg Resolved configuration.
+ * @param {{id: string, value: string}} previous Previous entry.
+ * @param {Function} fetch Provider reader.
+ * @param {Function} write Provider writer.
+ * @returns {string} Human-readable rollback outcome with no secret material.
+ */
+function rollback(cfg, previous, fetch, write) {
+  try {
+    write(cfg, previous.id, previous.value);
+    const restored = currentEntry(cfg, fetch);
+    if (restored.value !== previous.value) {
+      return "the previous provider value could not be verified after rollback";
+    }
+    return "the previous provider value was restored";
+  } catch (error) {
+    const reason =
+      error instanceof Error ? error.message.split("\n")[0] : String(error);
+    return `rollback failed: ${reason}`;
+  }
+}
+
+/**
+ * Publish, read back, and verify a candidate. Any failure after the candidate
+ * write triggers a restoration of the previous provider value.
+ * @param {string} raw Candidate JSON.
+ * @param {object} cfg Resolved configuration.
+ * @param {object} [operations] Injectable provider/AWS operations for tests.
+ * @returns {{changed: boolean, profiles: string[]}} Publication outcome.
+ */
+export function publishAwsBootstrap(raw, cfg, operations = {}) {
+  const fetch = operations.fetch ?? fetchAll;
+  const write = operations.write ?? writeSecret;
+  const verify = operations.verify ?? verifyAwsBootstrap;
+  const previous = preflightAwsBootstrap(cfg, { fetch, write });
+  const candidate = validateAwsBootstrap(raw);
+
+  // Verify before the write. A candidate that cannot assume one of its roles
+  // never becomes the value every new remote session receives.
+  verify(candidate);
+
+  if (candidate.raw === previous.value) {
+    return {
+      changed: false,
+      profiles: candidate.profiles.map(profile => profile.name),
+    };
+  }
+
+  try {
+    write(cfg, previous.id, candidate.raw);
+    const stored = currentEntry(cfg, fetch);
+    if (stored.value !== candidate.raw) {
+      throw new Error("provider read-back did not match the candidate exactly");
+    }
+    const storedCandidate = validateAwsBootstrap(stored.value);
+    verify(storedCandidate);
+    return {
+      changed: true,
+      profiles: storedCandidate.profiles.map(profile => profile.name),
+    };
+  } catch (error) {
+    const reason =
+      error instanceof Error ? error.message.split("\n")[0] : String(error);
+    const rollbackOutcome = rollback(cfg, previous, fetch, write);
+    throw new Error(
+      `${BOOTSTRAP_KEY} publication failed: ${reason}; ${rollbackOutcome}`
+    );
+  }
+}
+
+/** Read a candidate from stdin without ever placing it in argv. */
+function readCandidate() {
+  return readFileSync(0, "utf8");
+}
+
+function main() {
+  const [operation] = process.argv.slice(2);
+  const cfg = readConfig();
+
+  if (operation === "preflight") {
+    const current = preflightAwsBootstrap(cfg);
+    const candidate = validateAwsBootstrap(current.value);
+    const profiles = verifyAwsBootstrap(candidate);
+    console.log(
+      `${BOOTSTRAP_KEY}: provider write path and ${profiles.length} AWS profile(s) verified; no value changed`
+    );
+    return;
+  }
+
+  if (operation === "verify") {
+    const current = currentEntry(cfg, fetchAll);
+    const candidate = validateAwsBootstrap(current.value);
+    const profiles = verifyAwsBootstrap(candidate);
+    console.log(`${BOOTSTRAP_KEY}: ${profiles.length} AWS profile(s) verified`);
+    return;
+  }
+
+  if (operation === "publish") {
+    const result = publishAwsBootstrap(readCandidate(), cfg);
+    console.log(
+      `${BOOTSTRAP_KEY}: ${result.changed ? "published" : "already current"}; ` +
+        `${result.profiles.length} AWS profile(s) verified`
+    );
+    return;
+  }
+
+  throw new Error("usage: publish-aws-bootstrap.mjs preflight|verify|publish");
+}
+
+function invokedAsScript(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsScript(import.meta.url)) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

package/plugins/lisa/.codex-plugin/skills/lisa-setup-remote-aws/SKILL.md

@@ -49,11 +49,29 @@ it to AWS Secrets Manager as `remote-agent-credentials`, but that is where it is
 *emitted*, not where it must *live*. Copy it once into the project's configured
 provider and read it from there.
 
-**Do not keep it in two stores.** A bundle sitting in Secrets Manager *and* in
-the platform's secret store is two live copies of one credential: rotate the
-IAM key and whichever copy you forget keeps authenticating until it doesn't,
-with nothing to say which is current. That is the drift the single-store rule in
-`lisa-secrets-access` exists to prevent, and this credential is not exempt.
+**Do not maintain two stores by hand.** A bundle sitting in Secrets Manager
+and in the platform's secret store is two live copies of one credential: rotate
+the IAM key and whichever copy you forget becomes stale, with nothing to say
+which is current. Treat the infrastructure secret as a short-lived deployment
+emission and the configured provider as the consumer-facing source of truth.
+
+Publish the emission as part of the same rotation automation. The publisher
+reads the candidate on stdin, proves every role before writing, reads the
+provider value back exactly, proves every stored role again, and restores the
+previous provider value if a post-write check fails:
+
+```bash
+aws --profile shared secretsmanager get-secret-value \
+  --secret-id remote-agent-credentials \
+  --query SecretString \
+  --output text \
+  | node .claude/skills/lisa-secrets-access/scripts/publish-aws-bootstrap.mjs publish
+```
+
+Resolve the script from the installed runtime or `node_modules` when the
+`.claude/skills` copy is not present. Never print or place the candidate in an
+argument or temporary file. A CDK deployment followed later by a human copy is
+not a completed rotation.
 
 **One provider cannot serve this particular secret.** If `secrets.provider` is
 `aws`, reading the bundle requires AWS credentials — and the bundle *is* the AWS

package/plugins/lisa/agents/learner.md

@@ -1,6 +1,6 @@
 ---
 name: learner
-description: "Post-implementation learning agent. Capture-only — collects task learnings, builds seven-field entries, and persists them to the machine-managed ledger through the executable contract with provenance. Never promotes: it creates no skills, appends no rules, files no upstream issues; promotion is exclusively the gardener's ticket-gated job."
+description: "Post-implementation learning agent. Capture-only — collects task learnings, builds eight-field entries, and persists them to the machine-managed ledger through the executable contract with provenance. Never promotes: it creates no skills, appends no rules, files no upstream issues; promotion is exclusively the gardener's ticket-gated job."
 ---
 
 # Learner Agent
@@ -22,11 +22,12 @@ Why this shape: promotion without a human gate lets agents unilaterally rewrite
 
 If no learnings exist, report "No learnings to process" and complete.
 
-### Step 2: Build the Seven-Field Entry
+### Step 2: Build the Eight-Field Entry
 
 For each `mistake`/`learning` candidate, build the ledger entry the executable contract validates. The `LEARNINGS_CONTRACT` caps apply — an over-cap entry cannot persist; tighten it or drop it, never truncate by hand:
 
-- `id` — a stable dedupe key. Use `learner-` + the first 12 hex chars of `sha1(normalized_rule)` so the same rule always yields the same id (this is what makes re-runs idempotent — the writer throws on a duplicate id).
+- `fingerprint` — the deterministic content-version token: `learner-` + the first 12 hex chars of `sha1(normalized_rule)`. Recompute it from the fully consolidated rule; never estimate it.
+- `id` — set `id = fingerprint` for a new capture. On an exact stamped consolidation the writer carries forward the deterministic primary target id, while `fingerprint` changes with the new content.
 - `rule` — the actionable learning, **≤ 240 characters and ≤ 2 lines** per `LEARNINGS_CONTRACT`.
 - `why` — the causal claim (why the rule holds).
 - `provenance` — stable refs behind the candidate: the originating task id(s), plus any PR/issue/commit refs the task recorded. At most 20 entries. This is also where scope markers live (below).
@@ -47,9 +48,9 @@ LEARNINGS_FILE=$(node -e 'import("@codyswann/lisa/learnings").then(async m => {
 For each candidate entry:
 
 1. **Consolidation check (mandatory before writing).** Parse existing entries with `parseLearningsFile` from `@codyswann/lisa/learnings` and look for a related entry — same failure class, overlapping topic, or near-duplicate wording.
-   - **Related entry found** → consolidate, do not sibling. Write via `persistConsolidatedLearning(projectRoot, entry, { supersede: [<related ids>] })`, merging the still-true content of the superseded entry into the new rule and keeping the earliest `first_learned`. A near-duplicate sibling is a bug, not an entry.
+   - **Related entry found** → consolidate, do not sibling. Copy each target's exact parsed version stamp and write via `persistConsolidatedLearning(projectRoot, entry, { supersede: [{ id: <related id>, fingerprint: <related fingerprint> }], onStaleSupersede: targets => report(targets) })`, merging the still-true content of the superseded entry into the new rule and keeping the earliest `first_learned`. Stamps are checked together inside the lock: if any is stale, the writer removes none, safely appends the new fingerprint, and reports the mismatch. A near-duplicate sibling is a bug, not an entry.
    - **No related entry** → append via `persistLearningEntry(projectRoot, entry)`.
-   - **Already present (same id)** → the writer throws on a duplicate id; treat that as a dropped-duplicate no-op and record it as such. Re-running over the same tasks leaves the ledger unchanged.
+   - **Already present (same fingerprint)** → the writer throws on a duplicate fingerprint before mutation; treat that as a dropped-duplicate no-op and record it as such. Re-running over the same tasks leaves the ledger unchanged.
 2. The writer re-asserts the entry and document budgets. An over-budget failure means consolidate harder or drop — never truncate by hand.
 
 Persistence rides the implement flow's normal branch/PR: the code change and its learnings land in the same PR (satisfying "every persistence is a PR" with no new machinery). Never commit the ledger straight to the default branch and never hand-edit it.
@@ -75,7 +76,7 @@ One row per collected learning, mapping it to its terminal disposition:
 - **Capture-only.** Create no skills, append to no human-authored rules file, file no issue anywhere — take no promotion decision of any kind. Every promotion (skill, eager rule, executable control, upstream ticket) is the gardener's ticket-gated job, and the ledger is your only output surface.
 - **One write path.** The ledger changes only through `persistLearningEntry` / `persistConsolidatedLearning` from `@codyswann/lisa/learnings`, inside a PR. Never hand-edit the file.
 - **Consolidate, never sibling.** A related existing entry is merged or superseded at write time (SLL-6 discipline), never duplicated.
-- **Idempotent.** Deduplicate before persisting; stable ids and consolidation guarantee re-runs over the same tasks leave the ledger unchanged.
+- **Idempotent.** Deduplicate before persisting; the deterministic fingerprint and stamped consolidation guarantee re-runs over the same tasks leave the ledger unchanged.
 - **Headless-safe.** No interactive prompts; runs identically under an intake cron.
 - **Never block the build.** If persistence fails, report the failure and let the primary flow continue — shipping the work outranks recording a learning about it.
 - **No learning loops about learning.** Gardener tickets and learning PRs are not themselves learnings; never capture them.

package/plugins/lisa/rules/reference/project-learnings.md

@@ -17,9 +17,10 @@ then recency — that fit the token/entry budget, plus how many were omitted).
 the bounded projection, not the full document. Do not duplicate numeric caps in
 rules or prompts; the exported contract is the source of truth.
 
-Each persisted entry has seven fields:
+Each persisted v2 entry has eight fields:
 
 - `id`
+- `fingerprint`
 - `rule`
 - `why`
 - `provenance`
@@ -27,6 +28,36 @@ Each persisted entry has seven fields:
 - `last_confirmed`
 - `confidence`
 
+`fingerprint` is the content-version token; `id` is the stable public identity.
+A new entry starts with `id = fingerprint`. Consolidation passes exact
+`{ id, fingerprint }` stamps copied from parsed entries. The writer checks the
+whole target set inside its lock: an exact set is replaced together while the
+deterministic primary id carries forward; any stale stamp removes nothing and
+the new fingerprint is appended safely. Fingerprints are unique, so an
+identical re-capture fails before mutation rather than gaining a sibling.
+
+## v1 compatibility and mutation-only migration
+
+`parseLearningsDocument` accepts both contract versions and reports
+`sourceVersion`, normalized `entries`, `canonicalSource`, and
+`sourceMaxTokens`. A v1 entry is normalized in memory with `fingerprint = id`,
+which records the version-token job its old id already performed. A read never
+rewrites the ledger. The next real writer mutation — append, exact stamped
+consolidation, confirmation, overflow drain, or merge — publishes one atomic v2
+document. Each source version is validated against its own derived budget; do
+not copy either numeric ceiling into instructions. Stable ids and fingerprints
+are bounded machine tokens, and the v2 budget is derived to absorb the maximum
+per-entry fingerprint expansion for every v1 document the compatibility parser
+accepts. That migration-closure invariant prevents an ordinary later mutation
+from discovering that a previously accepted legacy document cannot be
+published.
+
+The three-way merge understands mixed v1/v2 sides. When two branches both
+legitimately replace the same stable id from the same observed fingerprint, it
+keeps both successors deterministically: one retains the stable id and the
+other is keyed by its unique fingerprint. It never guesses when fingerprints
+collide.
+
 ## Who writes the ledger
 
 **Contract-mediated writers** — all going through the executable contract
@@ -34,6 +65,8 @@ Each persisted entry has seven fields:
 
 - The **learner agent** at capture time appends or consolidates new entries
   (`persistLearningEntry` / `persistConsolidatedLearning`) from task learnings.
+  Consolidations pass exact parsed `{ id, fingerprint }` stamps and report a
+  stale snapshot through `onStaleSupersede` instead of overwriting its winner.
   It is capture-only: it never appends to host rules, creates skills, or
   files upstream issues — promotion is the gardener's ticket-gated job.
 - **`lisa-debrief-apply`** routes accepted debrief findings in the three

package/plugins/lisa/skills/lisa-debrief-apply/SKILL.md

@@ -51,15 +51,16 @@ For each such Accepted row:
    ```
 
 2. **Consolidation check (mandatory before writing).** Parse the existing entries with `parseLearningsFile` and look for one related to the row (same failure class, overlapping topic, or near-duplicate wording). Then write through the contract:
-   - **Related entry found** → consolidate via `persistConsolidatedLearning(projectRoot, entry, { supersede: [<related ids>] })`, merging the old entry's still-true content into the new rule. Never append a near-duplicate sibling — a sibling is a bug.
+   - **Related entry found** → consolidate with the exact parsed versions: `persistConsolidatedLearning(projectRoot, entry, { supersede: [{ id: <related id>, fingerprint: <related fingerprint> }], onStaleSupersede: targets => report(targets) })`. Every stamp is checked together inside the writer lock. If any is stale, the writer removes none, safely appends the new fingerprint, and reports the mismatch. Never append a near-duplicate sibling by choice — a sibling is a bug; the stale append is the deliberate concurrent-writer preservation path.
    - **No related entry** → append via `persistLearningEntry(projectRoot, entry)`.
 
-3. **Entry mapping (seven fields).**
-   - `id` — the entry id returned by the contract writer (report it in the run summary).
+3. **Entry mapping (eight fields).**
+   - `fingerprint` — `debrief-` + the first 12 hex characters of `sha1(normalized_rule + "\n" + sorted_provenance.join("\n"))`, where the rule is lowercased with whitespace collapsed and provenance is sorted by codepoint. Compute it mechanically, never estimate it.
+   - `id` — initially `id = fingerprint`. On an exact stamped consolidation the writer carries forward the deterministic primary target id; report the returned id in the run summary.
    - `rule` / `why` — from the row's `Summary` and the category-specific guidance in the routing table above (≤240 chars, ≤2 lines).
    - `provenance` — **the triage-doc row's evidence links**. This is the same evidence link that doubles as the idempotency fingerprint below, so the row's provenance is what a later re-apply scans for.
    - `first_learned` = `last_confirmed` = today (ISO date; on consolidation keep the superseded entry's earliest `first_learned`).
-   - `confidence` = **`high`**. A human marking the row **Accept** is corroboration — an independent human judgement that the learning is real — so a debrief-accepted entry starts higher than the learner's single-occurrence auto-capture (which defaults to `low`). The writer re-asserts the entry and token budgets; an over-budget failure means consolidate harder or drop, never truncate by hand.
+   - `confidence` = **`high`**. A human marking the row **Accept** is corroboration — an independent human judgement that the learning is real — so a debrief-accepted entry starts higher than the learner's single-occurrence auto-capture (which defaults to `low`). A duplicate fingerprint fails before mutation. The writer re-asserts the entry and token budgets; an over-budget failure means consolidate harder or drop, never truncate by hand.
 
 **Machine-local memory is no longer a knowledge destination.** Auto-memory (`project_*.md`, `MEMORY.md`) remains available only for the assistant's *personal* collaboration notes — it is invisible to cloud runs and to teammates, so it can never hold shared project knowledge. **`AGENTS.md` is human-authored** agent operating instruction — it is the source of truth, and `CLAUDE.md` is only a one-line `@AGENTS.md` pointer — and the host-rules directory `.agents/rules/` is durable human-authored guidance; `apply` never writes to any of the three for these categories.
 

package/plugins/lisa/skills/lisa-persist-learning/SKILL.md

@@ -171,9 +171,9 @@ No learning content is ever committed without a PR — there is no other write p
    ```
 
 3. **Consolidation check (mandatory before writing).** Parse the existing entries (`parseLearningsFile` from `@codyswann/lisa/learnings`) and look for entries related to the new rule (same failure class, overlapping topic, or near-duplicate wording). Then write through the executable contract — **never hand-edit the markdown**:
-   - **Related entry found** → consolidate via `persistConsolidatedLearning(projectRoot, entry, { supersede: [<related ids>] })`, merging the old entry's still-true content into the new rule. Never append a near-duplicate sibling — a sibling is a bug that fails review.
+   - **Related entry found** → consolidate with the exact versions returned by the parser: `persistConsolidatedLearning(projectRoot, entry, { supersede: [{ id: <related id>, fingerprint: <related fingerprint> }], onStaleSupersede: targets => report(targets) })`. The writer checks every stamp together inside the lock. If any target is absent or its fingerprint changed, the whole supersede is stale: it removes nothing, safely appends the new fingerprint, and reports the mismatch. Never append a near-duplicate sibling by choice — a sibling is a bug that fails review; the writer's stale append is the deliberate race-safe preservation path.
    - **No related entry** → append via `persistLearningEntry(projectRoot, entry)` and state in the PR body why appending was correct.
-   - Entry mapping: `id` = the fingerprint; `rule`/`why`/`provenance` from the candidate; `first_learned` = `last_confirmed` = today (ISO date; on consolidation keep the superseded entry's earliest `first_learned`); `confidence` = the judge's `high`/`low`. The writer re-asserts the entry and token budgets — an over-budget failure means consolidate harder or drop, never truncate by hand.
+   - Entry mapping (eight fields): `fingerprint` = the deterministic Phase 0 fingerprint and initial `id = fingerprint`; `rule`/`why`/`provenance` from the candidate; `first_learned` = `last_confirmed` = today (ISO date; on consolidation keep the superseded entry's earliest `first_learned`); `confidence` = the judge's `high`/`low`. On an exact stamped consolidation the writer carries forward the deterministic primary target id while persisting the new fingerprint as the version token. A duplicate fingerprint fails before mutation. The writer re-asserts the entry and token budgets — an over-budget failure means consolidate harder or drop, never truncate by hand.
    - **On a budget-forced drop, signal saturation once (never silent).** When the writer's budget re-assertion cannot fit the entry even after consolidating harder — a durable capture has to be DROPPED for budget — the ledger is saturated, and that pressure must be visible to an operator instead of swallowed. Emit **exactly one** tracker signal via `lisa-tracker-write` (`issue_type: Task`; GitHub trackers carry the `type:Task` label), then continue — dropping the capture never blocks the build. Follow the same marker-dedupe discipline as every other comment here (match on the **marker, never the title**; **exactly one marker per body**; the eventual-consistency guard when the search index is stale), with **one deliberate difference: dedupe against OPEN signals only.** A *closed* saturation ticket means room was already reclaimed, so a fresh saturation is a new actionable event — searching closed tickets too (as the drop/upstream markers do) would permanently suppress every later saturation.
 
      The saturation fingerprint keys on the **ledger, not the candidate**, so the signal fires once per saturation episode — never once per capture: