@llblab/pi-kit 0.3.2 → 0.5.0

package/node_modules/@llblab/pi-telegram/lib/threads.ts

@@ -21,6 +21,7 @@ import {
   writeFile,
 } from "node:fs/promises";
 import { dirname } from "node:path";
+import { isDeepStrictEqual } from "node:util";
 
 import {
   isTelegramApiCommitUnknownError,
@@ -229,6 +230,11 @@ export interface TelegramTopicTargetStore {
   /** Discard process-local projections and reload owner-published state. */
   refresh?: () => Promise<void>;
   persist: () => Promise<void>;
+  invalidateTarget: (
+    target: TelegramTarget,
+    isCurrent: () => boolean,
+    lastSyncError: string,
+  ) => Promise<boolean>;
   list: () => TelegramTopicTargetRecord[];
   getFollowerRecoveryHintByTarget?: (
     target: TelegramTarget,
@@ -316,6 +322,53 @@ export function reconcileTelegramFreshAllocationCursor(
   return true;
 }
 
+export function createTelegramCleanupTargetProtection(
+  store: Pick<TelegramTopicTargetStore, "list"> & Partial<Pick<TelegramTopicTargetStore, "listReservations" | "listPendingProvisions" | "listPendingCleanups">>,
+  departingRecord?: TelegramTopicTargetRecord,
+): NonNullable<ThreadReconciler.ThreadReconciliationApplyPorts["isCleanupTargetProtected"]> {
+  const records = store.list();
+  const reservations = store.listReservations?.() ?? [];
+  const provisions = store.listPendingProvisions?.() ?? [];
+  const intents = store.listPendingCleanups?.() ?? [];
+  // Persistence may reconstruct keys in another order and omit undefined
+  // optional fields; neither changes the authority represented by a snapshot.
+  const sameSnapshot = (left: unknown, right: unknown): boolean =>
+    isDeepStrictEqual(JSON.parse(JSON.stringify(left)), JSON.parse(JSON.stringify(right)));
+  return (target, action) => {
+    for (const record of store.list()) {
+      if (!targetMatches(record.target, target)) continue;
+      // A persisted shutdown intent may retire only its original pre-intent
+      // binding. Registration/rebinding after that intent supersedes it.
+      const intent = action.kind === "close-delete-graceful-shutdown-topic"
+        ? intents.find((candidate) => candidate.id === action.cleanupIntentId && candidate.runtimeGeneration === action.runtimeGeneration)
+        : undefined;
+      const expectedDeparting = departingRecord ?? (intent && records.find((candidate) =>
+        candidate.instanceId === intent.instanceId && targetMatches(candidate.target, intent.target) &&
+        candidate.updatedAtMs <= intent.requestedAtMs));
+      if (expectedDeparting && "instanceId" in action &&
+        (action.kind === "close-delete-previous-leader-topic" || action.instanceId === expectedDeparting.instanceId) &&
+        sameSnapshot(record, expectedDeparting)) {
+        if (action.kind === "close-delete-previous-leader-topic" || action.kind === "close-stale-replaced-topic") continue;
+        if (action.kind === "close-delete-graceful-shutdown-topic" &&
+          store.listPendingCleanups?.().some((intent) => intent.id === action.cleanupIntentId &&
+            intent.instanceId === action.instanceId && intent.runtimeGeneration === action.runtimeGeneration &&
+            targetMatches(intent.target, target))) continue;
+      }
+      if (record.status === "active" || record.status === "starting" || record.status === "pending" || record.status === "probe-required") return true;
+    }
+    for (const reservation of store.listReservations?.() ?? []) {
+      if (!targetMatches(reservation.target, target)) continue;
+      if (action.kind !== "close-delete-reserved-topic" || !reservations.some((initial) => sameSnapshot(initial, reservation))) return true;
+    }
+    for (const provision of store.listPendingProvisions?.() ?? []) {
+      if (!provision.target || !targetMatches(provision.target, target)) continue;
+      if (action.kind !== "close-delete-expired-pending-provision-topic" || provision.id !== action.pendingProvisionId ||
+        !provisions.some((initial) => sameSnapshot(initial, provision))) return true;
+    }
+    return false;
+  };
+}
+
 export interface TelegramTopicTargetStoreOptions {
   path: string | (() => string);
   getNowMs?: () => number;
@@ -1230,7 +1283,11 @@ export function createTelegramTopicTargetStore(
       loaded = true;
       return;
     }
+    const revision = mutationRevision;
     const content = await readFile(path, "utf8");
+    // A read begun before a local mutation must not replace the newly admitted
+    // binding/cleanup state with its older disk snapshot.
+    if (mutationRevision !== revision || getPath() !== path) return;
     const rawFile: unknown = JSON.parse(content);
     const file = parseTopicTargetFile(rawFile);
     followerRecoveryHints = parseFollowerRecoveryHints(rawFile);
@@ -1293,25 +1350,20 @@ export function createTelegramTopicTargetStore(
     mutationRevision += 1;
   };
 
-  return {
-    async load() {
-      if (dirty) return;
-      await loadFromDisk();
-    },
-    refresh() {
-      const refresh = persistQueue.then(loadFromDisk);
-      persistQueue = refresh.catch(() => undefined);
-      return refresh;
-    },
-    persist() {
+  const persistSnapshot = (invalidation?: {
+    target: TelegramTarget;
+    isCurrent: () => boolean;
+    lastSyncError: string;
+  }): Promise<boolean> => {
       const persist = persistQueue.then(async () => {
         const path = getPath();
         if (loadedPath !== path && !dirty) resetForPath(path);
         if (options.canPersist && !options.canPersist()) {
-          await loadFromDisk();
-          return;
+          if (!invalidation) await loadFromDisk();
+          return false;
         }
         if (!dirty || !loaded) await loadFromDisk();
+        if (invalidation && !invalidation.isCurrent()) return false;
         await mkdir(dirname(path), { recursive: true });
         const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
         const nowMs = getNowMs();
@@ -1359,6 +1411,21 @@ export function createTelegramTopicTargetStore(
             return serialized;
           }),
         };
+        if (invalidation) {
+          const record = file.threads.find((record) => targetMatches(record.target, invalidation.target));
+          if (!record) return false;
+          file.threads = file.threads.filter((candidate) => candidate !== record);
+          file.syncObservations = file.syncObservations.filter((observation) => !targetMatches(observation.target, record.target));
+          file.syncObservations.push({
+            target: { ...record.target },
+            syncStatus: "deleted",
+            observedAtMs: nowMs,
+            ...(record.instanceId ? { instanceId: record.instanceId } : {}),
+            ...(record.slot ? { slot: record.slot } : {}),
+            lastSyncError: invalidation.lastSyncError,
+            lastReconcileAction: "mark-stale",
+          });
+        }
         let persistedSemanticSnapshot: string | undefined;
         try {
           persistedSemanticSnapshot = serializeTelegramStateSemanticSnapshot(
@@ -1375,7 +1442,7 @@ export function createTelegramTopicTargetStore(
         ) {
           loaded = true;
           dirty = false;
-          return;
+          return true;
         }
         await writeFile(tempPath, `${JSON.stringify(file, null, 2)}\n`, {
           encoding: "utf8",
@@ -1383,6 +1450,25 @@ export function createTelegramTopicTargetStore(
         });
         await chmod(tempPath, 0o600);
         try {
+          if (invalidation) {
+            let applied = false;
+            const commit = () => {
+              if (getPath() !== path || mutationRevision !== persistedRevision ||
+                statusRevision !== persistedStatusRevision || !invalidation.isCurrent()) return;
+              // Fence and rename share one synchronous commit boundary. No stale
+              // invalidation enters the live projection before durable commit.
+              renameSync(tempPath, path);
+              records = new Map(Array.from(records).filter(([, record]) => !targetMatches(record.target, invalidation.target)));
+              syncObservations = file.syncObservations;
+              mutationRevision += 1;
+              dirty = false;
+              applied = true;
+            };
+            if (options.commitPersist) options.commitPersist(commit);
+            else if (!options.canPersist || options.canPersist()) commit();
+            if (!applied) await unlink(tempPath).catch(() => undefined);
+            return applied;
+          }
           if (options.commitPersist) {
             const committed = options.commitPersist(() => {
               renameSync(tempPath, path);
@@ -1404,9 +1490,27 @@ export function createTelegramTopicTargetStore(
         }
         loaded = true;
         if (mutationRevision === persistedRevision) dirty = false;
+        return true;
       });
-      persistQueue = persist.catch(() => undefined);
+      persistQueue = persist.then(() => undefined, () => undefined);
       return persist;
+  };
+
+  return {
+    async load() {
+      if (dirty) return;
+      await loadFromDisk();
+    },
+    refresh() {
+      const refresh = persistQueue.then(loadFromDisk);
+      persistQueue = refresh.catch(() => undefined);
+      return refresh;
+    },
+    async persist() {
+      await persistSnapshot();
+    },
+    invalidateTarget(target, isCurrent, lastSyncError) {
+      return persistSnapshot({ target, isCurrent, lastSyncError });
     },
     list() {
       return Array.from(records.values()).map(cloneRecord);
@@ -2100,6 +2204,7 @@ export async function provisionOwnBusTopic(
   if (typeof chatId !== "number") return undefined;
   await deps.store.load();
   const reservationCleanupPorts = {
+    isCleanupTargetProtected: createTelegramCleanupTargetProtection(deps.store),
     callApi: deps.callApi,
     markStaleByTarget: (
       target: TelegramTarget & { threadId: number },
@@ -2253,9 +2358,11 @@ export async function provisionOwnBusTopic(
       continue;
     }
     const previousLeaderCleanupStartedAtMs = Date.now();
+    const isCleanupTargetProtected = createTelegramCleanupTargetProtection(deps.store, record);
     const cleanup = await ThreadReconciler.applyThreadReconciliationPlan(
       { actions: [action] },
       {
+        isCleanupTargetProtected,
         callApi: deps.callApi,
         markStaleByTarget: (target, syncStatus, lastSyncError) =>
           deps.store.markStaleByTarget(target, syncStatus, lastSyncError),
@@ -2304,6 +2411,7 @@ export async function provisionOwnBusTopic(
         "Previous Telegram leader topic deletion was not confirmed.",
       );
     }
+    if (isCleanupTargetProtected(action.target, action)) continue;
     deps.store.markStaleByTarget(record.target);
     deps.store.reserveThread({
       target: record.target,

package/node_modules/@llblab/pi-telegram/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.42.2",
+  "version": "0.43.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/node_modules/@llblab/pi-telegram/skills/generated-control-surface/SKILL.md

@@ -40,7 +40,9 @@ A surface is an ordered ragged sequence of rows. Each button carries:
 
 - A short, distinct label.
 - The smallest self-contained next-request prompt.
-- Optional presentation state supported by the transport.
+- Optional presentation state supported by the transport, including disabled controls when their visible unavailability helps explain current state.
+
+A disabled control is not an action: it needs no prompt or selected style and must not enqueue a prompt or invoke a bound method. Prefer a meaningful label; omit it only for an intentional blank cell in a spatial layout, never as decorative padding. Preserve its label and position when that makes a changing surface easier to understand; otherwise omit irrelevant controls. Explain non-obvious unavailability without relying on color alone. Retain at least one useful enabled action, such as refresh or navigation. Derive disabled state from the same evidence as the view; an old enabled control still requires current domain validation. Use the transport owner's disabled encoding rather than a dummy prompt or no-op callback.
 
 Prompts must name any target, operation, constraint, or freshness identity whose omission could change the action. Reuse visible context only when it remains unambiguous under delayed or reordered clicks. Never encode volatile output that should be freshly inspected.
 
@@ -57,7 +59,7 @@ Every generated human-readable action label must use `emoji + space + text`; emo
 
 For complex grids, navigation collections, or stateful repeated clicks, read [`references/layout-and-state.md`](./references/layout-and-state.md).
 
-Serialize the resulting rows with the active transport contract. This Skill owns admission and composition, not transport syntax.
+Place a control group beside the section it governs when the transport supports in-body blocks; use a footer for whole-answer actions. Placement must not change the matrix or action semantics. Serialize the resulting rows with the active transport contract. This Skill owns admission and composition, not transport syntax.
 
 ## Safety
 

package/node_modules/@llblab/pi-telegram/skills/generated-control-surface/references/layout-and-state.md

@@ -10,7 +10,7 @@ Model the surface as ordered ragged rows, not a rectangle to fill. Infer indepen
 - A horizontal pair is earned only by genuine peers with unmistakably compact labels and no plausible wrapping or truncation.
 - Three through five columns are for short symbols, coordinates, glyphs, or codes whose position carries meaning.
 - Six through eight columns require single-glyph or similarly minimal position-bearing labels. Never exceed eight columns on a phone surface.
-- Vary row width intentionally; never pad with empty, duplicate, or no-op controls.
+- Vary row width intentionally; never pad for symmetry with empty, duplicate, or no-op controls. A blank disabled cell is appropriate only when it represents a real unavailable position in a spatial grid.
 - Preserve reading order: orientation/navigation, primary content or choices, secondary controls, then separated destructive actions.
 - Rectangular grids require genuine spatial or coordinate correspondence. Vertical continuity may justify many rows; non-spatial button walls should paginate or group.
 
@@ -32,4 +32,6 @@ Keep trivial state in conversation. Persist a small human-auditable artifact whe
 
 Evaluate repeated clicks against current state, not stale button appearance. Preserve tap-ahead when the transport queues each click independently. In source-then-destination interaction, retain the source selection without duplicating the whole surface; regenerate after a completed transition, invalid input, or evidence that the transport cannot preserve the intermediate view.
 
-Omit unavailable controls when layout does not matter. Preserve occupied or selected cells when spatial topology depends on stable coordinates.
+Omit unavailable controls when layout does not matter. Preserve occupied or selected cells when spatial topology depends on stable coordinates, using the transport's disabled state without a fabricated prompt. Keep a useful enabled navigation or inspection action.
+
+Place each control group beside the content it governs when in-body blocks are supported; keep global navigation and whole-view actions in the footer. Do not duplicate one action in both positions merely for visibility. Row topology and current-state validation stay the same across compact and named representations and across placements; renderer limits and selection feedback belong to the transport.

package/node_modules/@llblab/pi-telegram/skills/generative-apps/SKILL.md

@@ -29,9 +29,9 @@ Generated Control Surface → current context → model → one ephemeral surfac
 Generative App             → model → reusable program → many evolving surfaces
 ```
 
-Both Skills use the same logical button matrix and `label + prompt` interaction model. The Telegram runtime owns its full JSON/CML notation and callback routing; this Skill owns reusable program judgment, while `generated-control-surface` owns ephemeral agent-authored composition. Shared rendering needs no third button Skill and does not collapse those responsibilities.
+Both Skills use the same logical button matrix and `label + prompt` interaction model. An app may place groups beside their related content using the transport's in-body button blocks or keep whole-view controls in the footer; placement does not change binding, disabled state, or method authority. The Telegram runtime owns its full JSON/CML notation and callback routing; this Skill owns reusable program judgment, while `generated-control-surface` owns ephemeral agent-authored composition. Shared rendering needs no third button Skill and does not collapse those responsibilities.
 
-An app may mix deterministic `app::method` controls and ordinary prompts in one view. Compile only the stable transitions that benefit from inference bypass; keep explanation, interpretation, teaching, and adaptation on the model-mediated plane. When no reusable state or deterministic loop earns a script, load and use `generated-control-surface` instead.
+An app may mix deterministic `app::method` controls and ordinary prompts in one view, including one control group. Compact and named cells may coexist under the shared transport grammar; neither representation nor placement creates another action plane. Compile only the stable transitions that benefit from inference bypass; keep explanation, interpretation, teaching, and adaptation on the model-mediated plane. When no reusable state or deterministic loop earns a script, load and use `generated-control-surface` instead.
 
 The `generated` / `generative` distinction is intentional. Do not rename `generated-control-surface` to a competing generative term.
 
@@ -76,7 +76,7 @@ Another capability remains the authoritative real owner. The app stores validate
 1. Identify the repeated feedback loop, real state owner, and actions that are truly deterministic.
 2. Choose one stable lowercase app and one self-contained `<app>.mjs` source outside the managed installation directory.
 3. Keep `init` and every exported method small, named, bounded, shell-free, and capability-specific.
-4. Render one complete next view after each action.
+4. Render one complete next view after each action. Derive disabled controls from current state using the shared transport contract; visible disabled controls neither invoke methods nor enqueue prompts. Revalidate domain preconditions when an enabled control is invoked, because previously rendered views may be stale.
 5. Mix action planes intentionally:
 
 ```text
@@ -107,6 +107,7 @@ Before presenting an app as working:
 - Inspect the installed initial view and persisted bounded state.
 - Exercise at least one real bound action and prove it bypasses Pi queue/model admission.
 - Exercise at least one ordinary prompt when the app intentionally uses the model plane.
+- Verify the placements actually used by the app and prove disabled cells invoke nothing. A successful ordinary prompt-button smoke is not evidence of app-method dispatch or stale-revision rejection.
 - Verify replacement rejects stale buttons and failed initialization preserves the prior app.
 - For adapters, prove fresh external status and terminal mutation evidence.
 - Confirm failures are bounded, redacted, and do not silently render success.

package/node_modules/@llblab/pi-telegram/skills/telegram-bridge/SKILL.md

@@ -15,7 +15,8 @@ Use Telegram as a mobile companion to the current Pi session. Preserve the exact
 | Attach a requested file to the current turn | `telegram_attach(path)` without targeting |
 | Explicitly send from local/TUI to Telegram | `telegram_message` or `telegram_attach` |
 | Explicitly send to a different live Thread | `telegram_message(thread=...)` |
-| Add prompt buttons or explicit voice | Top-level hidden action comments |
+| Add buttons | Hidden comment for footer; `telegram_button` fence for in-body rows |
+| Add explicit voice | Top-level hidden action comment |
 | Build a repeated deterministic interaction | Follow `generative-apps` |
 
 A connected Telegram session proves capability, not user intent. Use Telegram features on Telegram-originated turns or explicit Telegram delivery requests only. Never call `telegram_message` for the current active target.
@@ -39,7 +40,7 @@ Reply in concise, phone-width Telegram Rich Markdown. Use `$...$` and `$$...$$`
 
 ## Assistant Actions
 
-`telegram_button` and `telegram_voice` are hidden HTML comments, not tools. Emit each complete action comment at column zero, outside lists, quotes, code blocks, and indentation. Telegram removes every assistant-authored HTML comment from previews and final replies regardless of owner or Markdown position, but only recognized top-level comments activate actions; comment-only output sends no text message.
+`telegram_button` and `telegram_voice` are markup, not tools. Emit action comments at column zero outside lists, quotes, code, and indentation. Comments create footer buttons or voice artifacts. For buttons between paragraphs, use a column-zero triple-backtick `telegram_button` block. Both button wrappers accept the same singleton JSON/CML cell or mixed matrix; the wrapper determines placement. Telegram removes every assistant-authored HTML comment from previews and final replies regardless of owner or Markdown position; only recognized top-level wrappers activate actions; comment-only output sends no text message.
 
 ### Shared Encoding Rule
 
@@ -48,25 +49,35 @@ Choose the least verbose sufficient representation:
 1. Positional CML — default.
 2. JSON — only when multiline content, named fields, or escaping earns it.
 
-CML trims atom boundaries and decodes `\|`, `\}`, and `\\`. Keep one complete action in one comment.
+CML trims atom boundaries and decodes `\|`, `\}`, and `\\`. Keep each payload inside one complete wrapper.
 
 ### Prompt Buttons
 
-Every button has a self-contained prompt and an optional selection style. Use a short distinct `emoji + space + text` label when separate human-readable labeling adds meaning; established coordinates or symbolic tokens may use the prompt itself as visible text. A click creates an ordinary user request; it never grants authority or bypasses confirmation.
+Every enabled button has a self-contained prompt and an optional selection style. Use a short distinct `emoji + space + text` label when separate human-readable labeling adds meaning; established coordinates or symbolic tokens may use the prompt itself as visible text. A click creates an ordinary user request; it never grants authority or bypasses confirmation.
 
 - `{prompt}` uses the same text for label and prompt.
 - `{|prompt}` omits a separately authored label and uses the prompt as both visible text and queued prompt.
 - `{label|prompt}` separates visible label from queued prompt.
 - `{label|prompt|selected_style}` and `{|prompt|selected_style}` accept `primary`, `success`, or `danger`.
+- Fourth-position `1`/`true` disables, `0`/`false` enables; omission means enabled. JSON uses boolean `disabled`. `{|Next||1}` omits label/style; `{Next|||1}` omits prompt/style; `{|||1}` is blank (Telegram receives a non-breaking space). Prefer meaningful labels and retain a useful enabled action. Enabled CML requires a prompt. Disabled controls stay visible but have no callback, queued prompt, or bound-method invocation.
 - Top-level cells form vertical rows; one nested row groups horizontal peers.
-- Prefer one matrix comment for the complete surface.
+- Prefer one matrix per related group. Fenced blocks stay in place in Rich mode; HTML compatibility moves them to the footer. Native rows allow eight buttons. Malformed/oversized/unclosed blocks activate nothing; drafts hide them. Outer code fences and quoted/indented examples remain literal.
+- Both placements share prompt/app routing. In-body clicks acknowledge without recoloring; selected-style highlighting remains footer-only.
+
+A single in-body button (the four-backtick wrapper below makes this a literal example):
+
+````markdown
+```telegram_button
+{📖 Details|Explain this section.}
+```
+````
 
 ```html
 <!-- telegram_button [{▶️ Continue|Continue the current plan.}[{✅ Approve|Approve this.}{❌ Reject|Reject this.}]] -->
 <!-- telegram_button {"label":"💡 Explain","prompt":"Explain this.\nInclude the risks."} -->
 ```
 
-Proactively use `generated-control-surface` whenever controls can materially shorten likely feedback; once active, it must emit useful buttons rather than prose alone. That Skill owns action composition; this Skill owns Telegram serialization and delivery. If buttons form the whole reply, the bridge supplies the standard choice heading.
+Proactively use `generated-control-surface` whenever controls can materially shorten likely feedback; once active, it must emit useful buttons rather than prose alone. That Skill owns action composition; this Skill owns Telegram serialization and delivery. Footer-only replies receive the standard choice heading.
 
 ### Voice
 
@@ -113,6 +124,6 @@ Before replying:
 
 - Use the ordinary path for the current target and direct tools only for explicit other delivery.
 - Attach requested files rather than only mentioning them.
-- Keep action comments top-level, complete, and canonical: CML first, JSON when necessary.
-- Give every button a self-contained prompt; preserve confirmation for dangerous actions.
+- Keep action comments and button fences top-level, complete, and canonical: CML first, JSON when necessary; either syntax may coexist within one matrix.
+- Give every enabled button a self-contained prompt; preserve confirmation for dangerous actions.
 - Expose no secret or hidden reasoning.

package/node_modules/@llblab/pi-telegram/skills/telegram-bridge/references/diagnosis.md

@@ -4,11 +4,13 @@ Read this reference only when diagnosing Telegram bridge health or delivery fail
 
 Inspect in this order:
 
-1. `telegram-status` for compact health.
-2. `telegram-status --debug` for bounded human-readable diagnostics.
+1. `/telegram-status` for compact health in the Pi TUI.
+2. `/telegram-status --debug` for bounded human-readable diagnostics in the Pi TUI.
 3. `~/.pi/agent/tmp/telegram/state.json` and `logs.jsonl` for default-profile redacted evidence.
 4. `state.<profile>.json` and `logs.<profile>.jsonl` for a named profile.
 
+These slash commands are registered Pi commands, not shell executables or agent tools. If the agent cannot invoke them through a supported Pi surface, read the diagnostic files directly; do not run them in Bash or inject terminal input.
+
 When `PI_CODING_AGENT_DIR` selects another compatible runtime, resolve its equivalent `tmp/telegram` directory.
 
 Do not mutate ownership files, bridge state, journals, bindings, or locks to force recovery. Use supported commands and preserve exact profile, target, transport, and session authority. Never claim successful delivery without transport evidence.

package/node_modules/@llblab/skills/abcd-context/AGENTS.md

@@ -0,0 +1,40 @@
+# ABCd Context Project Context
+
+## Meta-Protocol Principles
+
+- `Self-Reference`: This skill validates its own context graph with its own runtimes and regression fixture.
+- `Root State Separation`: Durable protocol, open work, completed delivery, README entrypoints, and subsystem docs keep distinct ownership.
+- `Constraint-Driven Evolution`: Structure grows from observed coordination pressure, not template ceremony.
+- `Project Neutrality`: Portable rules remain independent of repository stacks and local overlays.
+- `Single Runtime`: The Node validator provides one authoritative behavior and supported execution path.
+- `Cross-Platform`: Validator behavior runs wherever the supported Node runtime runs.
+
+## Operating Principles
+
+- Keep `SKILL.md` as the operating kernel; place resolution, lifecycle, and consolidation detail in `docs/protocols.md`.
+- Keep `BACKLOG.md` limited to real open, gated, or blocked work and `CHANGELOG.md` limited to completed outcomes.
+- Keep root `README.md` connected to `AGENTS.md`, `BACKLOG.md`, `CHANGELOG.md`, and `docs/README.md` when those surfaces exist.
+- Keep subtree README entrypoints reachable once they become real human starting points.
+- Use `scripts/validate-context.mjs` for audits and `scripts/_self-test.mjs` for regression.
+- Treat warnings as evidence requiring judgment, not as automatic failure or automatic approval.
+
+## Protocol Constraints
+
+- `Farmville Guard`: Skip context mutation when it would not preserve truth, prevent drift, record meaningful delivery, or repair discoverability.
+- `Activation Symmetry`: Default post-task activation performs post-task reconciliation; it must not imply retroactive pre-task ceremony.
+- `Template Proportionality`: Lean projects receive lean structure; mature hierarchy requires real complexity.
+- `State Ownership`: The same reality must not remain simultaneously durable, open, and completed.
+- `README Continuity`: Setup, usage, topology, ownership, and same-domain entrypoint knowledge belong in the nearest relevant README.
+- `Impact-Oriented History`: Delivery history records outcomes and impact rather than iteration bookkeeping.
+- `Natural-Language Operation`: Do not introduce fictional YAML tracking or formalize obvious senior-engineer behavior without a non-obvious contract.
+- `Local Overlay Boundary`: Project-specific release, architecture, security, and stack gates remain in local overlays.
+
+## Validator Constraints
+
+- `Single Runtime`: Keep `validate-context.mjs` as the only supported validator implementation.
+- `Anchor Validation`: Preserve underscores while normalizing GitHub-style heading anchors and validate line-reference bounds.
+- `Path Portability`: Resolve paths through Node rather than platform-specific shell utilities.
+- `Human Output`: Emit concise readable logs and a summary; `NO_COLOR=1` suppresses color.
+- `Bounded Scanning`: Skip link scanning above the configured byte threshold while validating the surrounding graph.
+- `Compact Tables`: Fail non-compact delimiter cells; require exactly three hyphens with one space inside each pipe, while table rows over 120 characters only warn.
+- `Core Shape Flexibility`: Accept both numbered mature-project sections and compact skill-style durable sections.

package/node_modules/@llblab/skills/abcd-context/BACKLOG.md

@@ -0,0 +1,3 @@
+# ABCd Context Backlog
+
+No open backlog items.

package/node_modules/@llblab/skills/abcd-context/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 1.5.3
+
+- `Markdown Freedom`: LaTeX syntax is now allowed, while table checks always enforce compact three-hyphen delimiter cells and warn on rows over 120 characters without imposing a maximum. Indented backtick and tilde code fences remain excluded from table validation. Impact: context authors can use mathematical notation and fenced examples while receiving default, noise-focused table formatting guidance.
+
+## 1.5.2
+
+- `Human-First Validation`: The validator now has one Node implementation and prints classic readable logs by default; JSON output and the Bash runtime are removed. Impact: direct local use and agent calls receive the same concise report without format switches.
+- `Line-Reference Validation`: GitHub-style line-reference links now fail when their target line is absent. Impact: broken Markdown references cannot silently pass validation.
+
+## 1.5.1
+
+- `JSON-First Validation`: Bash and Node validators now emit stable JSON by default while preserving explicit `--text` output and the existing `--json` alias. Impact: agent, recipe, and CI callers receive machine-readable results without extra flags.
+
+## 1.0.20
+
+- `Protocol Cohesion`: Consolidated the operating kernel, deep protocols, templates, project context, and human entrypoint around one context ownership model. Impact: activation, routing, reconciliation, and validation now form one proportional workflow without duplicated ceremony.
+- `Self-Reference`: Added the skill's own completed-history surface and expanded regression coverage to validate both the fixture and the skill root across Bash and Node runtimes. Impact: the skill now exercises the context graph it prescribes.

package/node_modules/@llblab/skills/abcd-context/README.md

@@ -0,0 +1,30 @@
+# ABCd Context
+
+Portable context protocol for keeping durable rules, open work, completed delivery, human entrypoints, and project docs truthful without generating ceremonial churn.
+
+## Context Graph
+
+- `AGENTS.md`: Durable protocol and reusable constraints.
+- `BACKLOG.md`: Canonical remaining work.
+- `CHANGELOG.md`: Completed outcomes and impact.
+- `README.md` tree: Human entrypoints and navigation.
+- `docs/README.md` + `/docs`: Indexed subsystem and contract knowledge.
+
+## Validation
+
+The Node validator prints human-readable results wherever the supported Node runtime runs.
+
+```bash
+node ./scripts/validate-context.mjs /path/to/project
+node ./scripts/_self-test.mjs
+```
+
+Warnings require review but do not fail validation. Errors return a nonzero exit.
+
+## Start Here
+
+- [Skill Definition](./SKILL.md)
+- [Project Context](./AGENTS.md)
+- [Open Backlog](./BACKLOG.md)
+- [Changelog](./CHANGELOG.md)
+- [Documentation](./docs/README.md)

package/node_modules/@llblab/skills/abcd-context/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: abcd-context
+description: ABCd context protocol across ABC root files (AGENTS.md, BACKLOG.md, CHANGELOG.md), human entrypoint README.md files tree, and /docs. Use after meaningful project changes, backlog drift, documentation refactors, self-evolving context maintenance, or a forced context reconciliation pass.
+---
+
+# ABCd Context
+
+Keep project context truthful, separated, connected, and small enough to use. Treat `AGENTS.md`, `BACKLOG.md`, `CHANGELOG.md`, the README tree, and `/docs` as one context graph with distinct ownership.
+
+## Core Guarantee
+
+Durable rules stay durable. Open work stays open. Completed delivery moves to history. README entrypoints remain trustworthy. Docs remain discoverable. Each fact has one authoritative home.
+
+## Activation Modes
+
+- `POST_TASK` (default): Reconcile context after meaningful reality changed. Do not add pre-task ceremony retroactively.
+- `ON_REQUEST`: Run a full context audit and reconciliation when the user explicitly asks.
+- `ALWAYS_ON` (opt-in): Monitor context continuously only when explicitly requested; otherwise its attention cost exceeds its value.
+
+Skip the skill for conversational work, trivial changes, or tasks that produced no durable context change.
+
+## Context Model
+
+- `README.md`: Human entrypoint, setup, usage, topology, and navigation.
+- Subtree `README.md`: Local human entrypoint for a real subsystem, workspace, package, or tool.
+- `AGENTS.md`: Durable protocol, constraints, conventions, architecture memory, and recurring operating rules.
+- `BACKLOG.md`: Canonical remaining open, gated, or blocked work. Accepted aliases: `TODO.md`, `PLAN.md`, `ROADMAP.md` when project convention already owns them.
+- `CHANGELOG.md`: Completed delivery and impact, unless the project already has another canonical shipped-history surface.
+- `docs/README.md`: Documentation index.
+- `docs/*`: Product, subsystem, architecture, operations, and contract documentation.
+
+Detailed resolution, adaptation, consolidation, and overlay rules live in [`docs/protocols.md`](./docs/protocols.md). Templates live in [`docs/templates.md`](./docs/templates.md).
+
+## Hierarchical Backlog Batching
+
+For non-trivial work, model the plan as `outcome or epic → acceptance checkpoint → owned work item`, not one long flat sequence.
+
+- Create a checkpoint only when several compatible changes share one meaningful integration boundary and can form a compiling, bisectable candidate. Keep one-shot work flat.
+- Group by coupled invariant, ownership boundary, or acceptance evidence rather than file proximity or arbitrary item count. Keep conflicting transitions, unrelated domains, and externally gated work in separate checkpoints.
+- Give every work item one focused falsification route: a named test family, filter, audit, or explicit evidence owner. A shared test names the smallest item set whose interaction it proves.
+- During edits, prefer focused item validation. Run aggregate package/runtime checks once when the checkpoint candidate forms; reserve full release validation for the highest boundary that actually needs it.
+- Keep dependency order inside a checkpoint only where correctness requires it. Independent items may proceed in parallel without turning the backlog into a false linear pipeline.
+- Treat the checkpoint as an acceptance and context boundary, not a second source of task truth. Child items own concrete remaining work; the checkpoint owns only the shared exit condition.
+- Close or narrow children as reality changes. Remove the checkpoint when its aggregate exit condition passes, and move meaningful impact to delivery history.
+
+## Invariants
+
+1. `Single source of truth`: Do not track the same state across durable protocol, open work, completed history, and docs.
+2. `Reality before prose`: Inspect the implementation, diff, plans, and existing conventions before updating context.
+3. `Constraint-driven structure`: Add hierarchy only when discovered constraints justify it; restructure inherited context when accidental shape hides truth.
+4. `Hierarchical execution`: Group compatible non-trivial work under acceptance checkpoints with attributable item-level evidence; do not force independent work into a false sequence or replay broad gates after every edit.
+5. `Human entrypoint continuity`: Keep root and relevant subtree README files reachable and current when setup, usage, topology, or ownership changes.
+6. `Backlog truth`: A completed or narrowed slice must not remain falsely open.
+7. `Impact-oriented history`: Record meaningful delivered outcomes, not bookkeeping or duplicated commit logs.
+8. `Local convention compatibility`: Cooperate with stricter project overlays; do not copy project-specific gates into this portable protocol.
+9. `Farmville guard`: If an edit would not preserve durable wisdom, correct open-work truth, record meaningful delivery, or repair discoverability, skip it. Silence is valid.
+
+## POST_TASK Flow
+
+Run one proportional reconciliation pass:
+
+1. `Assess`: Did the task materially change behavior, architecture, public contracts, open-work truth, setup, topology, or reusable operating knowledge? If not, stop.
+2. `Inspect`: Read the touched context surfaces, relevant diff, canonical plan, nearest README entrypoints, and existing shipped-history convention.
+3. `Reconcile open work`: Close, narrow, split, retarget, defer, gate, or block affected backlog items so only real remaining work stays open.
+4. `Route knowledge`:
+   - Setup, usage, topology, navigation, ownership → nearest `README.md`.
+   - Durable reusable constraint → `AGENTS.md`.
+   - Remaining executable work → canonical backlog.
+   - Meaningful completed outcome → `CHANGELOG.md` or established equivalent.
+   - Product/subsystem/architecture contract → indexed `/docs` document.
+5. `Consolidate and connect`: Merge duplicates, remove stale statements, preserve one authoritative home, update navigation, and keep docs index coverage honest.
+6. `Validate`: When context files changed, run the project convention first, otherwise run `validate-context`. Review warnings rather than treating exit code alone as proof.
+7. `Report`: Name changed context files, validation result, and any unresolved drift. If no update passed the Farmville guard, report that no context mutation was needed.
+
+Use a light pass for small scoped changes. Use the full protocol in [`docs/protocols.md`](./docs/protocols.md) for broad context refactors, architecture changes, or multi-surface drift.
+
+## ON_REQUEST Flow
+
+1. Map the current context graph and canonical files.
+2. Run both automated validation and manual truth checks.
+3. Compare claims against repository reality.
+4. Reconcile state ownership, stale content, duplicates, missing entrypoints, links, backlog drift, and docs coverage.
+5. Restructure only where current shape obstructs navigation or truth.
+6. Rerun validation and report remaining uncertainty.
+
+## Mutation Rules
+
+- Read the existing format before writing and match it when it remains honest.
+- Prefer targeted reconciliation over broad rewrites.
+- Use templates for new/empty files and as restructuring targets for drifted files, not as mandatory ceremony.
+- Keep prose unwrapped unless project tooling requires wrapping.
+- Prefer label bullets over definition tables.
+- Do not create missing root files automatically when project convention is ambiguous; ask or preserve the established equivalent.
+- Do not claim an item completed from documentation alone; verify reality.
+- Do not let generated context exceed the mistakes or navigation cost it prevents.
+
+## Validation
+
+Run the Node validator from the project root or pass an explicit root:
+
+```bash
+node "${SKILL_DIR}/scripts/validate-context.mjs" /path/to/project
+```
+
+Output is human-readable. Markdown table checks always require compact delimiter cells such as `| --- | ---: | :--- |`; non-compact delimiters fail validation, while rows longer than 120 characters only warn without imposing a maximum length.
+
+Useful environment controls:
+
+- `VALIDATE_CONTEXT_ROOT=/path` as an environment fallback.
+- `NO_COLOR=1` for logs consumed by CI or agents.
+
+Exit `0` means no errors; warnings may still require judgment. Exit `1` means validation errors or invalid invocation. Validator design and check semantics live in [`docs/validation-design.md`](./docs/validation-design.md).
+
+## Completion Checklist
+
+- [ ] Canonical open work matches reality.
+- [ ] Completed delivery left the backlog and reached the canonical history surface when meaningful.
+- [ ] Durable constraints live in `AGENTS.md`, not delivery history.
+- [ ] Relevant README entrypoints still explain and connect the changed area.
+- [ ] Docs describe current contracts and remain indexed.
+- [ ] Duplicate or stale context was removed rather than layered over.
+- [ ] Automated validation ran after context mutation, and warnings were reviewed.

package/node_modules/@llblab/skills/abcd-context/docs/README.md

@@ -0,0 +1,9 @@
+# Documentation Index (abcd-context)
+
+Living index of all documentation in the `/docs` directory for the ABCd context protocol (`ABC + README tree + /docs`).
+
+## Documents
+
+- [`protocols.md`](./protocols.md): Adaptation rules, lifecycle management, and validation checklist.
+- [`templates.md`](./templates.md): Entry templates for index files, docs, and changelog.
+- [`validation-design.md`](./validation-design.md): Design and checks of `validate-context`.