@llblab/pi-kit 0.5.2 → 0.7.0

package/node_modules/@llblab/pi-telegram/lib/workspace-slots.ts

@@ -0,0 +1,84 @@
+/**
+ * Workspace slot allocation policy
+ * Zones: telegram, workspace identity
+ * Owns bounded profile-wide letter selection and inactivity ordering.
+ * Excludes liveness discovery, persistence, routing, and Telegram deletion;
+ * a selection is a proposal, never authority to retire a binding.
+ */
+
+export const TELEGRAM_WORKSPACE_SLOTS = "abcdefghijklmnopqrstuvwxyz";
+
+export interface TelegramWorkspaceSlotOccupancy {
+  bindingKey: string;
+  slot: string;
+  inactiveSinceMs?: number;
+  protection: "eligible" | "protected" | "unknown";
+}
+
+export type TelegramWorkspaceSlotAllocation =
+  | { kind: "free"; slot: string }
+  | { kind: "reclaim"; candidate: TelegramWorkspaceSlotOccupancy }
+  | { kind: "blocked"; reason: "invalid-state" | "protected-capacity" };
+
+function isSlot(slot: string): boolean {
+  return /^[a-z]$/u.test(slot);
+}
+
+function isValidSnapshot(
+  bindings: readonly TelegramWorkspaceSlotOccupancy[],
+  reservedSlots: readonly string[],
+  nowMs: number,
+): boolean {
+  if (!Number.isFinite(nowMs) || nowMs < 0) return false;
+  const slots = new Set<string>();
+  const keys = new Set<string>();
+  for (const binding of bindings) {
+    if (!isSlot(binding.slot) || !binding.bindingKey ||
+        slots.has(binding.slot) || keys.has(binding.bindingKey)) return false;
+    slots.add(binding.slot);
+    keys.add(binding.bindingKey);
+  }
+  return reservedSlots.every(isSlot);
+}
+
+function eligibleByInactivity(
+  bindings: readonly TelegramWorkspaceSlotOccupancy[],
+  reservedSlots: readonly string[],
+  nowMs: number,
+): TelegramWorkspaceSlotOccupancy[] {
+  const reserved = new Set(reservedSlots);
+  return bindings.filter((binding) =>
+    binding.protection === "eligible" &&
+    !reserved.has(binding.slot) &&
+    typeof binding.inactiveSinceMs === "number" &&
+    Number.isFinite(binding.inactiveSinceMs) &&
+    binding.inactiveSinceMs >= 0 &&
+    binding.inactiveSinceMs <= nowMs,
+  ).sort((left, right) =>
+    left.inactiveSinceMs! - right.inactiveSinceMs! ||
+    left.slot.charCodeAt(0) - right.slot.charCodeAt(0),
+  );
+}
+
+/** Caller must recheck exact ownership and protected work before retirement. */
+export function planTelegramWorkspaceSlotAllocation(input: {
+  bindings: readonly TelegramWorkspaceSlotOccupancy[];
+  reservedSlots: readonly string[];
+  nowMs: number;
+}): TelegramWorkspaceSlotAllocation {
+  const { bindings, reservedSlots, nowMs } = input;
+  if (!isValidSnapshot(bindings, reservedSlots, nowMs)) {
+    return { kind: "blocked", reason: "invalid-state" };
+  }
+  const occupied = new Set([
+    ...bindings.map((binding) => binding.slot),
+    ...reservedSlots,
+  ]);
+  for (const slot of TELEGRAM_WORKSPACE_SLOTS) {
+    if (!occupied.has(slot)) return { kind: "free", slot };
+  }
+  const candidate = eligibleByInactivity(bindings, reservedSlots, nowMs)[0];
+  return candidate
+    ? { kind: "reclaim", candidate: { ...candidate } }
+    : { kind: "blocked", reason: "protected-capacity" };
+}

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

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

package/node_modules/@llblab/pi-telegram/scripts/measure-bus.mjs

@@ -0,0 +1,83 @@
+// Counts isolated registry work without sockets, configured profiles, or Telegram calls.
+import assert from "node:assert/strict";
+import { createTelegramBusFollowerRegistry, createTelegramBusProtocolIdentity } from "../lib/bus.ts";
+
+const repetitions = 10;
+const methods = ["get", "set", "delete", "entries", "values"];
+const originals = Object.fromEntries(methods.map((name) => [name, Map.prototype[name]]));
+const rows = [];
+let counts;
+
+function measure(size, operation, execute) {
+  const sample = { gets: 0, sets: 0, deletes: 0, entryVisits: 0, valueVisits: 0 };
+  let result;
+  counts = sample;
+  try {
+    for (let index = 0; index < repetitions; index++) result = execute(index);
+  } finally {
+    counts = undefined;
+  }
+  rows.push({ size, operation, repetitions, ...sample });
+  return { result, counts: sample };
+}
+
+try {
+  for (const [method, counter] of [["get", "gets"], ["set", "sets"], ["delete", "deletes"]]) {
+    Map.prototype[method] = function (...args) {
+      if (counts) counts[counter]++;
+      return originals[method].apply(this, args);
+    };
+  }
+  for (const [method, counter] of [["entries", "entryVisits"], ["values", "valueVisits"]]) {
+    Map.prototype[method] = function* (...args) {
+      for (const entry of originals[method].apply(this, args)) {
+        if (counts) counts[counter]++;
+        yield entry;
+      }
+    };
+  }
+  for (const size of [1, 13, 26]) {
+    const registry = createTelegramBusFollowerRegistry();
+    const protocol = createTelegramBusProtocolIdentity({ runtimeBuild: "measurement" });
+    const registrations = Array.from({ length: size }, (_, index) => ({
+      instanceId: `fixture-${index}`, profileKey: `manual:fixture-${index}`,
+      registrationGeneration: `generation-${index}`, connectedAtMs: 1000,
+      target: { chatId: 7, threadId: index + 1 }, protocol,
+    }));
+    for (const registration of registrations) registry.register(registration);
+    const last = registrations.at(-1);
+    const registered = measure(size, "reregister-last", () => registry.register(last));
+    assert.equal(registered.counts.entryVisits, size * repetitions);
+    const heartbeat = measure(size, "heartbeat-last", (index) => registry.heartbeat(last.instanceId, 2000 + index));
+    assert.equal(heartbeat.result.lastHeartbeatMs, 2000 + repetitions - 1);
+    assert.equal(heartbeat.counts.entryVisits + heartbeat.counts.valueVisits, 0);
+    assert.equal(heartbeat.counts.gets, repetitions);
+    assert.equal(heartbeat.counts.sets, repetitions);
+    const first = measure(size, "target-first", () => registry.getByTarget(registrations[0].target));
+    assert.equal(first.result.instanceId, registrations[0].instanceId);
+    assert.equal(first.counts.valueVisits, repetitions);
+    const tail = measure(size, "target-last", () => registry.getByTarget(last.target));
+    assert.equal(tail.result.instanceId, last.instanceId);
+    assert.equal(tail.counts.valueVisits, size * repetitions);
+    const missing = measure(size, "target-missing-chat", () => registry.getByTarget({ chatId: 8, threadId: size }));
+    assert.equal(missing.result, undefined);
+    assert.equal(missing.counts.valueVisits, size * repetitions);
+    const roster = measure(size, "list", () => registry.list());
+    assert.equal(roster.result.length, size);
+    assert.equal(roster.counts.valueVisits, size * repetitions);
+    for (const view of [registered.result, heartbeat.result, first.result, tail.result, ...roster.result]) {
+      const expected = registry.get(view.instanceId);
+      view.target.chatId = 99;
+      view.protocol.capabilities.push("fixture-only");
+      assert.deepEqual(registry.get(view.instanceId), expected, "Returned views must not mutate registry authority");
+    }
+  }
+} finally {
+  for (const method of methods) Map.prototype[method] = originals[method];
+}
+console.log(JSON.stringify({
+  scope: "Synchronous isolated follower registry, not IPC, authentication, provisioning, or throughput",
+  counters: "Aggregate Map operations and visited entries for each row's repetitions; no allocation or timing claims",
+  copyEvidence: "Mutating returned target/protocol capability views leaves registry authority unchanged",
+  rows,
+}, null, 2));

package/node_modules/@llblab/pi-telegram/scripts/measure-workspace.mjs

@@ -0,0 +1,101 @@
+// Measures isolated Thread-store work; never reads configured profiles or calls Telegram.
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import { syncBuiltinESMExports } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createTelegramTopicTargetStore } from "../lib/threads.ts";
+
+const repetitions = 10;
+const original = { readFile: fs.readFile, writeFile: fs.writeFile, mkdir: fs.mkdir, rename: fs.rename,
+  parse: JSON.parse, stringify: JSON.stringify };
+let counts;
+const rows = [];
+const root = await fs.mkdtemp(join(tmpdir(), "pi-telegram-measure-workspace-"));
+
+async function measure(size, operation, execute, samples = repetitions) {
+  counts = { reads: 0, readBytes: 0, writes: 0, writeBytes: 0, mkdirs: 0, renames: 0,
+    parses: 0, stringifies: 0 };
+  try {
+    for (let index = 0; index < samples; index++) await execute(index);
+    const result = { size, operation, repetitions: samples, ...counts };
+    rows.push(result);
+    return result;
+  } finally {
+    counts = undefined;
+  }
+}
+
+try {
+  fs.readFile = async (...args) => {
+    if (counts) counts.reads++;
+    const result = await original.readFile(...args);
+    if (counts) counts.readBytes += Buffer.byteLength(result);
+    return result;
+  };
+  fs.writeFile = async (...args) => {
+    if (counts) { counts.writes++; counts.writeBytes += Buffer.byteLength(args[1]); }
+    return original.writeFile(...args);
+  };
+  fs.mkdir = async (...args) => {
+    if (counts) counts.mkdirs++;
+    return original.mkdir(...args);
+  };
+  fs.rename = async (...args) => {
+    if (counts) counts.renames++;
+    return original.rename(...args);
+  };
+  JSON.parse = (...args) => { if (counts) counts.parses++; return original.parse(...args); };
+  JSON.stringify = (...args) => { if (counts) counts.stringifies++; return original.stringify(...args); };
+  syncBuiltinESMExports();
+
+  for (const size of [1, 13, 26]) {
+    const path = join(root, `${size}.json`);
+    const store = createTelegramTopicTargetStore({ path, getNowMs: () => 1000 });
+    for (let index = 0; index < size; index++) {
+      const instanceId = `fixture-${index}`;
+      const identity = store.claimWorkspaceIdentity(`/fixture/${index}`, instanceId);
+      assert.ok(identity);
+      const target = { chatId: 7, threadId: index + 1 };
+      assert.ok(store.upsertWorkspaceBinding({ ...identity, target, updatedAtMs: 1000 }, instanceId));
+      store.upsert({ profileKey: `manual:${instanceId}`, instanceId, slot: identity.slot,
+        target, status: "active", createdAtMs: 1000, updatedAtMs: 1000 });
+    }
+    await store.persist();
+    assert.equal(new Set(store.listWorkspaceBindings().map((entry) => entry.slot)).size, size);
+    await measure(size, "cold-load", async () => {
+      const reader = createTelegramTopicTargetStore({ path });
+      await reader.load();
+      assert.equal(reader.list().length, size);
+      assert.equal(reader.listWorkspaceBindings().length, size);
+    });
+    const lookup = await measure(size, "lookup-last", () => {
+      assert.equal(store.getByProfileKey(`manual:fixture-${size - 1}`)?.target.threadId, size);
+    });
+    assert.equal(lookup.reads + lookup.writes, 0);
+    const beforeReloadSave = JSON.parse(await fs.readFile(path, "utf8"));
+    const reloaded = await measure(size, "first-persist-after-reload", () => store.persist(), 1);
+    assert.equal(reloaded.writes + reloaded.renames + reloaded.mkdirs, 0);
+    assert.deepEqual(JSON.parse(await fs.readFile(path, "utf8")), beforeReloadSave,
+      "The first reloaded save must preserve the seeded semantic state");
+    const unchanged = await measure(size, "unchanged-persist", () => store.persist());
+    assert.equal(unchanged.writes + unchanged.renames + unchanged.mkdirs, 0);
+    assert.ok(unchanged.reads >= repetitions, "No-op saves still consult disk authority");
+    const changed = await measure(size, "diagnostic-persist", async (index) => {
+      store.setStatusSnapshot({ diagnostics: { measurementStep: index } });
+      await store.persist();
+    });
+    assert.equal(changed.writes, repetitions);
+    assert.equal(changed.renames, repetitions);
+  }
+} finally {
+  Object.assign(fs, { readFile: original.readFile, writeFile: original.writeFile,
+    mkdir: original.mkdir, rename: original.rename });
+  JSON.parse = original.parse;
+  JSON.stringify = original.stringify;
+  syncBuiltinESMExports();
+  await fs.rm(root, { recursive: true, force: true });
+}
+console.log(JSON.stringify({ scope: "Isolated Thread store, not IPC/admission/Telegram or throughput",
+  counters: "Aggregate API calls and bytes for each row's repetitions; object-spread clones are not instrumented",
+  rows }, null, 2));

package/node_modules/@llblab/{skills → pi-telegram/skills}/show-me/SKILL.md

@@ -1,17 +1,37 @@
 ---
 name: show-me
-description: Explain the current topic or work through contextual Markdown replies, concise diagrams, code-shape sketches, and focused HTML artifacts.
+description: Explain completed work, proposed changes, system structure, or ideas through truthful contextual Markdown, concise diagrams, code-shape sketches, and focused HTML artifacts. Use when the user asks to show what happened, what changed, or how something works, especially on a phone-width Telegram surface.
 ---
 
-Help the user understand the current topic: completed work, a proposed change, system structure, or an idea. Skip the preamble and keep prose brief. Pick the smallest view that makes the key point clear.
+Help the user understand the current topic. Skip the preamble and keep prose brief. Pick the smallest view that makes the key point clear without making the underlying claim less true.
 
 ### Output Selection
 
 - Infer the subject from the conversation and honor an explicitly requested format. With plain `show me`, choose the form that best explains the subject.
 - Markdown in the reply is a complete output format for both chat and terminal surfaces. Use headings, emphasis, lists, and focused code blocks to explain outcomes, comparisons, and reasoning; add a diagram when relationships need one.
-- `Show me markdown` requests a rendered Markdown reply. Create a Markdown file when the user asks for a saved document or file artifact.
+- `Show me markdown` requests a rendered Markdown reply. Create a Markdown file only when the user asks for a saved document or file artifact.
 - `Show me html` requests a focused HTML file. Save file artifacts in the project or filesystem as appropriate and deliver them through the active environment's file-delivery mechanism; open locally when that is the requested surface.
 
+### Surface Routing
+
+- Infer whether the active surface is Telegram, a terminal, or another client. Keep the explanation portable and use surface-specific delivery only when the context or user request authorizes it.
+- For Telegram output, read [`references/telegram-surfaces.md`](./references/telegram-surfaces.md) before selecting Markdown or HTML. Keep the immediate reply useful even when an attached artifact is the deeper view.
+- When asked what changed or happened in current work, inspect the retained diff, status, and validation evidence when available. Separate this task from pre-existing changes and distinguish repository state from released or live behavior.
+
+### Truth And State
+
+- Label material claims as `live`, `released`, `locally implemented`, `proposed`, or `unverified` when the distinction affects interpretation. Omit redundant labels when the state is already unambiguous.
+- Preserve the exact mechanism, owner, and boundary when simplifying technical behavior. A friendly label may supplement the implementation term but must not replace it when that would merge distinct timers, states, stages, or authorities.
+- Make a visual diff correspond to the actual changed symbol or contract. Show unchanged neighboring behavior when omission could imply that it changed too.
+- Do not infer that an affordance is clickable, interactive, rendered, or client-visible from source or markup shape alone. Distinguish designed or expected behavior from behavior verified through the relevant renderer, transport, runtime, and client.
+- Treat a mockup, diagram, or rendered artifact as explanatory evidence, not runtime proof. State the unverified boundary when the user could reasonably mistake one for the other.
+
+A compact state line is enough when provenance matters:
+
+```text
+State: locally implemented · validated · not released · not live
+```
+
 ### Visual Forms
 
 - Show logic or an algorithm as pseudocode:
@@ -127,7 +147,7 @@ function expandSkill(command: string): string {
 }
 ```
 
-- For a visual UI, layout, state comparison, or concept too dense for Mermaid, use a focused HTML artifact — a diagram, an infographic, or a short slide deck, whichever fits the point. Match the product's colors, type, spacing, and components; use real labels and data; support desktop and mobile.
+- For a visual UI, layout, state comparison, or concept too dense for Mermaid, use a focused HTML artifact — a diagram, an infographic, or a short slide deck, whichever fits the point. Match the product's colors, type, spacing, and components; use real labels and data; support desktop and mobile. When practical, render representative narrow and wide viewports and report what was actually inspected.
 
 ### Text Rendering
 
@@ -137,8 +157,10 @@ function expandSkill(command: string): string {
 - In trees, place comments and explanations as child nodes one level below the item they describe. Keep the item's own line for its label.
 - Use prose lists for independent statuses and split larger views into meaningful sections.
 
-### guidance
+### Guidance
+
+Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point. Prefer one primary visual and a few decision-relevant takeaways; add another form only when it explains a different necessary relationship.
 
-Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point.
+Use source paths, symbol names, or validation evidence when they materially anchor a claim, not as decoration. Report the strongest state the evidence supports and no stronger.
 
 You may use one of these, you may use several, it is unlikely you will use all of them. Use your judgement and don't overwhelm the user.

package/node_modules/@llblab/pi-telegram/skills/show-me/references/telegram-surfaces.md

@@ -0,0 +1,43 @@
+# Telegram Explanation Surfaces
+
+Use this reference only when Show Me is responding through Telegram or preparing an artifact for Telegram delivery.
+
+## Selection
+
+- With plain `show me`, prefer a native Markdown reply when one phone-width view can explain the point.
+- Use HTML when spatial comparison, dense state, a timeline, or a visual hierarchy would become harder to understand in narrow Markdown.
+- `Show me markdown` means rendered Markdown in the current reply, not a `.md` attachment, unless the user explicitly asks for a file.
+- `Show me html` means one focused, self-contained `.html` artifact delivered through the active Telegram file path. The surrounding reply should say what the artifact explains and disclose its evidence state.
+- Do not create both formats by habit. The second format must answer a need the first cannot.
+
+## Telegram Markdown
+
+- Design for a phone before a desktop: one governing question, one primary visual, short labels, shallow nesting, and prose that wraps naturally.
+- Prefer compact semantic diffs, call trees, timelines, or state transitions over raw repository diffs. A remote user needs to understand impact before file-level detail.
+- Avoid wide tables, deep trees, side-by-side layouts, and Mermaid when the current Telegram renderer would expose only source text. Move genuinely spatial material to HTML.
+- Put material state near the top: what changed, whether it is local or live, what was validated, and what remains unresolved.
+- Keep source paths and symbol names below the explanation unless they are the explanation.
+- Keep intended Telegram bot-command tokens as plain text rather than inline code. Format Pi/TUI or shell commands as code according to the host contract. Plain source shape does not prove native clickability; claim it only after the active entity-detection and client path is verified.
+- Use explicit Markdown links when a destination matters rather than assuming plain URL auto-detection.
+
+## Telegram HTML
+
+- Produce a single self-contained file with UTF-8 metadata and a viewport declaration. Avoid external assets, scripts, fonts, trackers, or network requirements unless the user explicitly requested them.
+- Build mobile-first for roughly phone-width reading, then let the same document expand cleanly in a system or desktop browser. Text must wrap; diagrams must scroll or reflow without clipping.
+- Use semantic headings, sufficient contrast, non-color status meaning, comfortable touch targets, and no hover-only information.
+- Preserve real labels, values, ordering, and uncertainty. An attractive reconstruction must not invent runtime state or imply that a proposed interaction exists.
+- Include a compact provenance line when state matters, such as `Local patch · validated · not released · not live`.
+- When rendering tools are available, inspect at least one narrow viewport and one wider viewport. Report what was inspected; static source review is not visual proof.
+- Deliver the file through the active Telegram attachment mechanism. Do not expose local paths as if the user could open them remotely.
+
+## Current-Work Evidence
+
+Before explaining “what we did” or “what happened,” use the narrowest available evidence that can support the answer:
+
+1. Inspect retained repository status and diff for the relevant task.
+2. Identify pre-existing or unrelated changes and exclude them from the claimed task result.
+3. Name the actual changed mechanism or contract, not a friendlier neighboring concept.
+4. Separate implementation evidence from validation, release, deployment, runtime, transport, and client evidence.
+5. State unresolved causes or missing live checks instead of filling them with a cleaner story.
+
+A visual is successful when the user can understand the outcome away from a computer without being given a stronger claim than the evidence supports.

package/node_modules/@llblab/pi-telegram/skills/telegram-bridge/references/delivery-and-threads.md

@@ -7,7 +7,7 @@ Read this reference only for explicit local/TUI Telegram delivery, cross-target
 Use `telegram_message` only when the user explicitly requests Telegram delivery from local/TUI or names a concrete different Telegram target.
 
 - Omitted target selects the paired/default target only outside an active Telegram turn.
-- `chat_id` plus optional `thread_id` selects an explicit Bot API target.
+- `chat_id` plus optional `thread_id` selects an explicit Bot API target. A public `@username`, or an exact negative numeric channel ID with `channel: true`, uses `chat_id` without `thread_id`; channel delivery requires the direct leader, and Telegram enforces the bot's posting permission.
 - `thread` selects another live Pi Thread by case-insensitive name or numeric id and admits one attributed turn there.
 - During an active Telegram turn, answer the current target normally; direct delivery to that same target is rejected.
 - Direct delivery requires this Pi instance to own transport or hold a live Threaded Mode registration.

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

@@ -36,5 +36,6 @@
 - `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.
+- `Contiguous Lists`: Fail blank lines inside one Markdown list; list items are contiguous structural peers, not paragraphs. Ignore fenced examples and bounded-scan exclusions.
 - `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/CHANGELOG.md

@@ -1,8 +1,12 @@
 # Changelog
 
-## 1.5.3
+## 1.14.1
 
-- `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.
+- `Contiguous Markdown Lists`: The validator now rejects blank lines inside continuous lists, including multiline and nested item boundaries, while ignoring fenced examples and bounded large-reference scans. Impact: list items remain structural peers instead of being formatted as separate paragraphs.
+
+## 1.13.2
+
+- `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
 

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

@@ -102,7 +102,7 @@ Run the Node validator from the project root or pass an explicit root:
 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.
+Output is human-readable. Markdown list items must remain contiguous: blank lines inside one list fail validation, including between multiline or nested items, while fenced examples are ignored. 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:
 

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

@@ -28,10 +28,11 @@ A missing or non-directory root fails before validation.
 6. `README reachability — Warning`: Finds subtree README files with no inbound Markdown link.
 7. `Meta-protocol presence — Warning`: Checks the durable file for `Meta-Protocol Principles`.
 8. `Bloat signals — Warning`: Reports low information density or sparse structure in the durable file.
-9. `Markdown tables — Error/Warning`: Always fails non-compact delimiter rows and warns about table rows longer than 120 characters.
-10. `Freshness — Warning`: Reports durable files older than 30 days.
-11. `Docs directory — Warning`: Checks for `/docs`.
-12. `Docs index coverage — Warning`: Detects docs missing from `docs/README.md` and indexed files that do not exist.
+9. `Markdown lists — Error`: Fails blank lines within one continuous list, including multiline and nested items, while ignoring fenced examples and files above the bounded Markdown scan limit.
+10. `Markdown tables — Error/Warning`: Always fails non-compact delimiter rows and warns about table rows longer than 120 characters.
+11. `Freshness — Warning`: Reports durable files older than 30 days.
+12. `Docs directory — Warning`: Checks for `/docs`.
+13. `Docs index coverage — Warning`: Detects docs missing from `docs/README.md` and indexed files that do not exist.
 
 ## Severity Contract
 
@@ -70,6 +71,10 @@ The validator avoids a hard file-length limit. It checks independent signals:
 
 Signals suggest consolidation; they do not replace judgment.
 
+## Markdown Lists
+
+List checks apply to Markdown within the bounded scan size and outside fenced code blocks. A blank line fails when it separates sibling list items, a list item from its nested list, nested sibling items, or a multiline item's continuation from its next item. Paragraphs and independent blocks remain separated by blank lines normally.
+
 ## Markdown Tables
 
 Table checks always run and have no enabling option.
@@ -93,7 +98,8 @@ Validation prints each check and a summary by default. `NO_COLOR=1` disables ANS
 3. A missing path, which must fail clearly.
 4. The removed `--json` option, which must fail clearly.
 5. A temporary fixture with an out-of-range line reference, which must fail clearly.
-6. Temporary fixtures proving that LaTeX and compact table delimiters pass, non-compact delimiters fail, and rows over 120 characters warn.
+6. Temporary fixtures proving that contiguous multiline/nested lists and fenced examples pass while blank separators inside lists fail.
+7. Temporary fixtures proving that LaTeX and compact table delimiters pass, non-compact delimiters fail, and rows over 120 characters warn.
 
 The fixture remains linked from [its README](../fixtures/abcd-project/README.md).
 

package/node_modules/@llblab/skills/abcd-context/scripts/_self-test.mjs

@@ -23,6 +23,7 @@ const missingPathOutput = run([path.join(fixtureRoot, "missing")], {
 const jsonOptionOutput = run(["--json"]);
 const invalidLineRefRoot = createInvalidLineRefFixture();
 const tableRoot = createTableFixture();
+const listRoot = createListFixture();
 try {
   const invalidLineRefOutput = run([invalidLineRefRoot], {
     withoutRootEnv: true,
@@ -49,6 +50,12 @@ try {
       .replace("|------------|---:|", "| --- | ---: |"),
   );
   const wideTableOutput = run([tableRoot], { withoutRootEnv: true });
+  const tightListOutput = run([listRoot], { withoutRootEnv: true });
+  fs.appendFileSync(
+    path.join(listRoot, "docs/lists.md"),
+    "\n- First loose item.\n  Continued detail.\n\n- Second loose item.\n  - Nested item.\n\n  - Nested sibling.\n",
+  );
+  const looseListOutput = run([listRoot], { withoutRootEnv: true });
 
   checkSuccess("default fixture", defaultOutput);
   checkSuccess("fixture path arg", pathOutput);
@@ -59,9 +66,12 @@ try {
   checkCompactTableAndLatex(compactTableOutput);
   checkNonCompactTable(nonCompactTableOutput);
   checkWideTable(wideTableOutput);
+  checkTightLists(tightListOutput);
+  checkLooseLists(looseListOutput);
 } finally {
   fs.rmSync(invalidLineRefRoot, { recursive: true, force: true });
   fs.rmSync(tableRoot, { recursive: true, force: true });
+  fs.rmSync(listRoot, { recursive: true, force: true });
 }
 
 console.log("PASS: validate-context fixture + self-reference regression");
@@ -146,6 +156,57 @@ function checkWideTable(result) {
   );
 }
 
+function checkTightLists(result) {
+  assert(result.status === 0, "contiguous lists and fenced examples pass");
+  assert(
+    result.stdout.includes("Markdown list checks passed"),
+    "contiguous list check reports success",
+  );
+}
+
+function checkLooseLists(result) {
+  assert(result.status !== 0, "blank lines inside lists fail validation");
+  assert(
+    result.stdout.includes("Blank line inside Markdown list: docs/lists.md"),
+    "loose list failure identifies its file",
+  );
+}
+
+function createListFixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "abcd-context-list-"));
+  fs.mkdirSync(path.join(root, "docs"));
+  fs.writeFileSync(
+    path.join(root, "README.md"),
+    "# Probe\n\n[Context](./AGENTS.md) [Backlog](./BACKLOG.md) [History](./CHANGELOG.md) [Docs](./docs/README.md)\n",
+  );
+  fs.writeFileSync(
+    path.join(root, "AGENTS.md"),
+    "# Context\n\n## Meta-Protocol Principles\n\n- First rule.\n- Second rule.\n\n## Operating Principles\n\n- Rule.\n",
+  );
+  fs.writeFileSync(path.join(root, "BACKLOG.md"), "# Backlog\n\nNo open work.\n");
+  fs.writeFileSync(path.join(root, "CHANGELOG.md"), "# Changelog\n\nNo releases.\n");
+  fs.writeFileSync(path.join(root, "docs/README.md"), "# Docs\n\n- [Lists](./lists.md)\n");
+  fs.writeFileSync(
+    path.join(root, "docs/lists.md"),
+    [
+      "# Lists",
+      "",
+      "1. First item.",
+      "2. Second item.",
+      "   - Nested item.",
+      "   - Nested sibling.",
+      "",
+      "```markdown",
+      "- Fenced item.",
+      "",
+      "- Fenced loose item.",
+      "```",
+      "",
+    ].join("\n"),
+  );
+  return root;
+}
+
 function createTableFixture() {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "abcd-context-table-"));
   fs.mkdirSync(path.join(root, "docs"));

package/node_modules/@llblab/skills/abcd-context/scripts/validate-context.mjs

@@ -16,6 +16,7 @@ for (let index = 0; index < args.length; index += 1) {
         "Validates the current directory by default, VALIDATE_CONTEXT_ROOT when set,",
         "or the explicit project-root argument when provided.",
         "",
+        "Markdown list items must be contiguous; blank separators fail validation.",
         "Markdown table formatting is always checked. Rows over 120 characters warn.",
       ].join("\n"),
     );
@@ -167,6 +168,53 @@ function markdownLines(text) {
   });
 }
 
+function markdownIndent(line) {
+  const leading = line.match(/^[ \t]*/)?.[0] || "";
+  return [...leading].reduce((width, char) => width + (char === "\t" ? 4 : 1), 0);
+}
+
+function findLooseListBlankLines(text) {
+  const lines = markdownLines(text);
+  const listIndents = [];
+  let pendingBlankLine;
+  const violations = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const { line, outsideFence } = lines[index];
+    if (!outsideFence) {
+      listIndents.length = 0;
+      pendingBlankLine = undefined;
+      continue;
+    }
+    if (/^\s*$/.test(line)) {
+      if (listIndents.length > 0 && pendingBlankLine === undefined) {
+        pendingBlankLine = index + 1;
+      }
+      continue;
+    }
+    const item = line.match(/^([ \t]*)(?:[-+*]|\d+[.)])[ \t]+\S/);
+    if (item) {
+      const indent = markdownIndent(item[1]);
+      if (pendingBlankLine !== undefined) violations.push(pendingBlankLine);
+      while (listIndents.length > 0 && listIndents.at(-1) > indent) listIndents.pop();
+      if (listIndents.at(-1) !== indent) listIndents.push(indent);
+      pendingBlankLine = undefined;
+      continue;
+    }
+    if (pendingBlankLine !== undefined) {
+      if (markdownIndent(line) > (listIndents.at(-1) ?? 0)) {
+        violations.push(pendingBlankLine);
+        pendingBlankLine = undefined;
+        continue;
+      }
+      listIndents.length = 0;
+      pendingBlankLine = undefined;
+      continue;
+    }
+    if (/^ {0,3}(?:#{1,6}\s|>|\|)/.test(line)) listIndents.length = 0;
+  }
+  return violations;
+}
+
 function stripFences(text) {
   return markdownLines(text)
     .filter(({ outsideFence }) => outsideFence)
@@ -392,6 +440,25 @@ if (contextFile) {
 
 const docsDir = path.join(root, "docs");
 
+progress("Checking Markdown lists...");
+let listIssue = false;
+for (const file of mdFiles) {
+  const sourceSize = fs.statSync(file).size;
+  if (sourceSize > markdownLinkScanMaxBytes) {
+    info(
+      `Skipped list validation for large Markdown file: ${rel(file)} (${sourceSize} bytes > ${markdownLinkScanMaxBytes})`,
+    );
+    continue;
+  }
+  for (const line of findLooseListBlankLines(read(file))) {
+    fail(
+      `Blank line inside Markdown list: ${rel(file)}:${line} (keep adjacent list items contiguous)`,
+    );
+    listIssue = true;
+  }
+}
+if (!listIssue) pass("Markdown list checks passed");
+
 progress("Checking Markdown tables...");
 let tableIssue = false;
 for (const file of mdFiles) {