@llblab/pi-kit 0.3.1 → 0.4.0

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

@@ -466,6 +466,8 @@ export interface TelegramApiClient {
 }
 
 export interface TelegramBridgeApiRuntimeDeps {
+  captureRequestErrorHandler?: (body: Record<string, unknown>) =>
+    ((error: unknown) => Promise<void>) | undefined;
   client: TelegramApiClient;
   tempDir: string;
   maxFileSizeBytes: number;
@@ -634,6 +636,11 @@ export function getTelegramApiErrorRequestTarget(
   return target ? { ...target } : undefined;
 }
 
+export function isTelegramStaleTargetHttpError(error: unknown): boolean {
+  if (!(error instanceof TelegramApiHttpError) || error.status !== 400) return false;
+  return /^Telegram API \w+ failed: HTTP 400: Bad Request: (message thread not found|thread not found|topic not found|topic deleted|topic closed|thread closed|forum topic closed|message thread closed|topic_id_invalid|topic_closed)$/i.test(error.message);
+}
+
 export function isTelegramMessageNotModifiedError(error: unknown): boolean {
   return (
     error instanceof Error && error.message.includes("message is not modified")
@@ -1438,6 +1445,7 @@ export function createTelegramAssistantDraftSender(deps: {
 export function createDefaultTelegramBridgeApiRuntime(deps: {
   getBotToken: () => string | undefined;
   recordRuntimeEvent: TelegramBridgeApiRuntimeDeps["recordRuntimeEvent"];
+  captureRequestErrorHandler?: TelegramBridgeApiRuntimeDeps["captureRequestErrorHandler"];
 }): TelegramBridgeApiRuntime {
   return createTelegramBridgeApiRuntime({
     client: createTelegramApiClient(deps.getBotToken, {
@@ -1447,12 +1455,23 @@ export function createDefaultTelegramBridgeApiRuntime(deps: {
     maxFileSizeBytes: TELEGRAM_INBOUND_FILE_MAX_BYTES,
     tempFileMaxAgeMs: TELEGRAM_TEMP_FILE_MAX_AGE_MS,
     recordRuntimeEvent: deps.recordRuntimeEvent,
+    captureRequestErrorHandler: deps.captureRequestErrorHandler,
   });
 }
 
 export function createTelegramBridgeApiRuntime(
   deps: TelegramBridgeApiRuntimeDeps,
 ): TelegramBridgeApiRuntime {
+  const recoverRequestError = async (
+    handler: ((error: unknown) => Promise<void>) | undefined,
+    error: unknown,
+  ): Promise<void> => {
+    try {
+      await handler?.(error);
+    } catch (recoveryError) {
+      deps.recordRuntimeEvent("api", recoveryError, { phase: "stale-target-recovery" });
+    }
+  };
   const now = deps.now ?? Date.now;
   const chatActionMinIntervalMs = Math.max(
     0,
@@ -1488,6 +1507,7 @@ export function createTelegramBridgeApiRuntime(
     body: Record<string, unknown>,
     options?: TelegramApiCallOptions,
   ): Promise<TResponse> => {
+    const recoverError = deps.captureRequestErrorHandler?.(body);
     const chatActionKey = getChatActionKey(method, body);
     if (chatActionKey) {
       const nowMs = now();
@@ -1516,7 +1536,8 @@ export function createTelegramBridgeApiRuntime(
           gate.notBeforeMs = now() + chatActionMinIntervalMs;
           return result;
         })
-        .catch((error: unknown) => {
+        .catch(async (error: unknown) => {
+          await recoverRequestError(recoverError, error);
           if (error instanceof TelegramApiHttpError && error.status === 429) {
             const retryAfterMs = Math.max(
               chatActionMinIntervalMs,
@@ -1550,6 +1571,12 @@ export function createTelegramBridgeApiRuntime(
     try {
       return await deps.client.call<TResponse>(method, body, options);
     } catch (error) {
+      await recoverRequestError(recoverError, error);
+      if (method === "deleteMessage" && error instanceof TelegramApiHttpError &&
+        error.status === 400 && error.message ===
+          "Telegram API deleteMessage failed: HTTP 400: Bad Request: message to delete not found") {
+        return true as TResponse;
+      }
       deps.recordRuntimeEvent(
         "api",
         error,
@@ -1574,6 +1601,7 @@ export function createTelegramBridgeApiRuntime(
       fileName,
       options,
     ) => {
+      const recoverError = deps.captureRequestErrorHandler?.(fields);
       try {
         return await deps.client.callMultipart(
           method,
@@ -1584,6 +1612,7 @@ export function createTelegramBridgeApiRuntime(
           options,
         );
       } catch (error) {
+        await recoverRequestError(recoverError, error);
         deps.recordRuntimeEvent(
           "multipart",
           error,
@@ -1676,11 +1705,13 @@ export function createTelegramBridgeApiRuntime(
     sendRichMessageDraft: (body) =>
       callRecorded<boolean>("sendRichMessageDraft", body),
     editMessageText: async (body) => {
+      const recoverError = deps.captureRequestErrorHandler?.(body);
       try {
         await deps.client.call("editMessageText", body);
         return "edited";
       } catch (error) {
         if (isTelegramMessageNotModifiedError(error)) return "unchanged";
+        await recoverRequestError(recoverError, error);
         deps.recordRuntimeEvent(
           "api",
           error,

package/node_modules/@llblab/pi-telegram/lib/thread-reconciler.ts

@@ -202,6 +202,7 @@ export interface ThreadReconciliationApplyResult {
 }
 
 export interface ThreadReconciliationApplyPorts {
+  isCleanupTargetProtected?: (target: ThreadTarget, action: ThreadReconciliationAction) => boolean;
   callApi?: <TResponse>(
     method: string,
     body: Record<string, unknown>,
@@ -576,6 +577,7 @@ export async function applyThreadReconciliationPlan(
         incompleteActions.push(action);
         continue;
       }
+      if (ports.isCleanupTargetProtected?.(action.target, action)) continue;
       let closeConfirmed = false;
       try {
         await ports.callApi("closeForumTopic", {
@@ -598,6 +600,7 @@ export async function applyThreadReconciliationPlan(
         incompleteActions.push(action);
         continue;
       }
+      if (ports.isCleanupTargetProtected?.(action.target, action)) continue;
       const changed =
         ports.markStaleByTarget?.(action.target, "closed") ?? false;
       if (changed) persistFences.push(action);
@@ -632,7 +635,12 @@ export async function applyThreadReconciliationPlan(
         continue;
       }
       let deleteConfirmed = false;
+      let superseded = false;
       for (const method of ["closeForumTopic", "deleteForumTopic"]) {
+        if (ports.isCleanupTargetProtected?.(action.target, action)) {
+          superseded = true;
+          break;
+        }
         if (shouldSkipForStaleLeaderEpoch(action, ports)) break;
         try {
           await ports.callApi(method, {
@@ -660,6 +668,15 @@ export async function applyThreadReconciliationPlan(
         incompleteActions.push(action);
         continue;
       }
+      if (superseded || ports.isCleanupTargetProtected?.(action.target, action)) {
+        ports.recordRuntimeEvent?.("telegram", "Cancelled cleanup of a protected Telegram target", {
+          phase: "thread-reconciler-cleanup-target-reused",
+          action: action.kind,
+          chatId: action.target.chatId,
+          threadId: action.target.threadId,
+        });
+        continue;
+      }
       if (!deleteConfirmed) {
         ports.recordRuntimeEvent?.(
           "telegram",

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.1",
+  "version": "0.42.4",
   "private": false,
   "publishConfig": {
     "access": "public"

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

@@ -39,7 +39,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 comment at column zero, outside lists, quotes, code blocks, and indentation.
+`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.
 
 ### Shared Encoding Rule
 

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`.