@llblab/pi-kit 0.3.2 → 0.4.0

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

@@ -0,0 +1,199 @@
+# ABCd Context Protocols
+
+Deep reference for the operating kernel in [SKILL.md](../SKILL.md). This document owns file resolution, full reconciliation, state transitions, consolidation, and local-overlay coexistence.
+
+## File Resolution
+
+### Human Entrypoints
+
+Root and subtree `README.md` files form the human navigation plane.
+
+- Root `README.md` should link to the durable protocol, canonical open work, completed history when present, and primary docs index.
+- A subtree `README.md` becomes managed when the subtree acts as a real human entrypoint.
+- Update the nearest relevant README when setup, topology, ownership, usage semantics, or same-domain operator/developer knowledge changes.
+- Keep subtree entrypoints reachable from a parent README, root README, or docs index.
+
+### Durable Protocol
+
+Preferred file: `AGENTS.md`.
+
+Accepted inherited fallbacks, in resolution order: `CLAUDE.md`, `CODEX.md`, `GEMINI.md`, `CONTEXT.md`.
+
+Create `AGENTS.md` only when project convention permits it. If an inherited durable file contains useful material but mixes abstraction levels or state types, restructure it toward the appropriate template instead of appending another flat section.
+
+### Canonical Open Work
+
+Preferred file: `BACKLOG.md`.
+
+Accepted inherited fallbacks: `TODO.md`, `PLAN.md`, `ROADMAP.md`.
+
+- If exactly one exists and project behavior confirms it, use it.
+- If several exist, identify the actively maintained canonical source before editing.
+- Prefer eventual convergence toward one source, but do not rename established project files casually.
+- Never mirror the same open item across multiple plans.
+
+### Completed Delivery
+
+Preferred file: `CHANGELOG.md`.
+
+If the project already keeps canonical shipped history elsewhere, preserve that convention rather than inventing a parallel changelog. Completed delivery never belongs as rolling history in `AGENTS.md`.
+
+### Documentation Plane
+
+- `docs/README.md` indexes project documentation.
+- `docs/*` owns subsystem, architecture, operations, decision, and public-contract detail.
+- Root protocol files should link to docs rather than duplicate them.
+
+## Adaptation and Restructuring
+
+When writing managed files:
+
+1. Read the current structure, tone, and ownership.
+2. Decide whether the structure still represents reality honestly.
+3. Match established form when it remains clear.
+4. Restructure when one file mixes durable protocol, open work, completed history, or unrelated documentation.
+5. Route new information only after ownership becomes clear.
+6. Consolidate existing duplication in the same pass when safe.
+
+Use [templates.md](./templates.md) for new/empty files and as target shapes for inherited drift. Choose the lean `AGENTS.md` starter for low coordination load and the layered starter only when real subsystem or governance complexity justifies it.
+
+Do not preserve accidental formatting merely because it exists. Do not impose a mature hierarchy on a tiny project.
+
+## Proportional Reconciliation
+
+### Light Pass
+
+Use after a small meaningful slice:
+
+1. Reconcile the affected backlog item.
+2. Update the nearest README or contract doc only if user-facing or operator-facing truth changed.
+3. Record a changelog outcome only when delivery is meaningful.
+4. Promote a durable lesson only when it will change future behavior.
+5. Validate changed context and stop.
+
+### Full Pass
+
+Use for architecture changes, broad documentation refactors, migration of context ownership, or explicit audits:
+
+1. Map root files, README entrypoints, docs index, and local overlays.
+2. Identify canonical owners for durable protocol, open work, shipped history, and subsystem contracts.
+3. Compare claims with repository reality.
+4. Repair backlog truth first.
+5. Repair README entrypoints and navigation.
+6. Reconcile subsystem docs and docs index coverage.
+7. Record meaningful delivered outcomes.
+8. Promote only reusable constraints into durable protocol.
+9. Merge duplicates and remove stale context.
+10. Run validation, inspect warnings, and repeat only for concrete remaining drift.
+
+## Backlog State Transitions
+
+Use one of these explicit transitions:
+
+- `Close`: Exit criteria are satisfied in reality; remove the item from open work.
+- `Narrow`: Part landed; rewrite the item to describe only what remains.
+- `Split`: One vague item became multiple independently executable slices.
+- `Retarget`: The original wording no longer matches the real desired outcome.
+- `Defer`: The item remains valid but no longer ranks as the next useful slice.
+- `Gate`: Progress requires an external condition or approval.
+- `Block`: Progress requires another unresolved internal or external dependency.
+
+Rules:
+
+- Active epics should expose at least one concrete next slice.
+- If implementation completed work absent from the plan, update the nearest existing item or record delivery without fabricating retrospective backlog ceremony.
+- If docs or architecture change exit criteria, update the item rather than preserving stale wording.
+- Evergreen maintenance disciplines belong in durable protocol, not perpetual checkboxes.
+- Prefer refining existing items over creating near-duplicates.
+
+## Completed Delivery Sync
+
+Record meaningful outcomes from reality, not intention.
+
+A good entry names:
+
+- The affected area.
+- What changed for users, operators, developers, or system behavior.
+- Material compatibility, migration, or safety impact when relevant.
+
+Avoid version-bump-only notes, test bookkeeping, and duplicates of `AGENTS.md` rules.
+
+## Consolidation
+
+### Triggers
+
+Consolidate when:
+
+- Three or more entries describe one pattern.
+- Two sections substantially overlap.
+- A section grows beyond easy scanning because abstraction levels became mixed.
+- A mistake repeats despite an existing rule.
+- Docs contradict implementation.
+- Two docs own the same contract.
+- A docs file lacks index coverage.
+- A README entrypoint becomes unreachable or stale.
+
+Heuristics suggest inspection; they do not replace judgment.
+
+### Procedure
+
+1. Identify the authoritative home.
+2. Preserve unique and still-true information.
+3. Resolve contradictions against implementation and current project convention.
+4. Merge the useful content.
+5. Remove or explicitly deprecate the weaker source.
+6. Repair links and index coverage.
+7. Validate the resulting graph.
+
+### Escalation Ladder
+
+When a mistake repeats:
+
+```text
+Durable insight
+→ Emphasized convention
+→ Hard rule with validation
+→ Structural tooling or automation
+```
+
+Escalate only after evidence shows the previous level failed.
+
+## Local Overlay Coexistence
+
+ABCd owns portable context hygiene:
+
+- Root state separation.
+- README and docs-index connectivity.
+- Link health and basic Markdown shape.
+- Generic backlog/changelog drift detection.
+- Context bloat and freshness signals.
+
+Local overlays own project-specific behavior:
+
+- Release and deployment gates.
+- Architecture/domain ownership rules.
+- Stack-specific tests and security checks.
+- Organization-specific conventions.
+
+Run ABCd to verify the context surface, then run the stricter local overlay. Do not copy local rules into ABCd unless they become portable across projects. Tune style warnings through documented options or environment variables rather than forking the validator for one repository.
+
+## Full Audit Checklist
+
+After automated validation, manually verify what scripts cannot prove:
+
+- [ ] Repository claims match implementation and current operations.
+- [ ] One authoritative home owns each material fact.
+- [ ] Canonical open work reflects real remaining work.
+- [ ] Completed work no longer appears open.
+- [ ] Durable protocol contains reusable constraints rather than delivery history.
+- [ ] Relevant README entrypoints describe current setup, topology, usage, and ownership.
+- [ ] Subtree entrypoints remain reachable.
+- [ ] Docs index covers current docs without phantom entries.
+- [ ] Active epics expose an executable next slice.
+- [ ] Local overlays remain authoritative for project-specific gates.
+
+## Related
+
+- [SKILL.md](../SKILL.md) — operating kernel
+- [templates.md](./templates.md) — starter and restructuring shapes
+- [validation-design.md](./validation-design.md) — validator behavior and parity contract

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

@@ -0,0 +1,194 @@
+# ABCd Context Templates
+
+Starter and restructuring shapes for files managed by ABCd. Existing honest project conventions win. Use only the files and sections the project actually needs.
+
+## Root README
+
+```markdown
+# [Project Name]
+
+[One-sentence project purpose.]
+
+## Start Here
+
+- [Project Context](./AGENTS.md)
+- [Open Backlog](./BACKLOG.md)
+- [Changelog](./CHANGELOG.md)
+- [Documentation](./docs/README.md)
+```
+
+Omit links to surfaces the project deliberately does not maintain. Do not create empty control-plane files merely to satisfy the template.
+
+## AGENTS — Lean
+
+Use for early projects with low coordination load and few durable constraints.
+
+```markdown
+# Project Context
+
+## Meta-Protocol Principles
+
+- `Constraint-Driven Evolution`: Add structure when real constraints justify it.
+- `Single Source of Truth`: Keep each fact in one authoritative layer.
+- `Context Hygiene`: Consolidate and remove stale context before it becomes drag.
+- `Boundary Clarity`: Separate durable protocol, open work, completed history, and docs.
+
+## Concept
+
+[One-sentence project purpose and boundary.]
+
+## Topology
+
+- `/[directory]/`: [Responsibility.]
+
+## Durable Conventions
+
+- `[Label]`: [Constraint or rule.]
+  - Trigger: [When it applies.]
+  - Action: [Required behavior.]
+```
+
+## AGENTS — Layered
+
+Use only when multiple subsystems, stronger contracts, or autonomous coordination pressure justify a durable hierarchy. This also serves as a restructuring target for overgrown flat files.
+
+```markdown
+# Project Context
+
+## 0. Meta-Protocol Principles
+
+- `Constraint-Driven Evolution`: Add complexity only when discovered constraints justify it.
+- `Single Source of Truth`: Keep durable protocol, open work, completed history, and subsystem docs distinct.
+- `Decreasing Abstraction`: Organize context from mental model to execution protocol.
+- `Context Optimization`: Consolidate and remove stale structure before context becomes entropy.
+- `Validation Infrastructure`: Pair structural rules with explicit checks.
+- `Human + Agent Coherence`: Keep the same graph useful to future humans and agents.
+
+## 1. Concept
+
+[Project identity, problem, and product boundary.]
+
+## 2. Identity and Naming
+
+- [Canonical terms and naming boundaries.]
+
+## 3. Topology
+
+- `/[directory]/`: [Responsibility.]
+
+## 4. Core Entities
+
+- [Durable domain atoms.]
+
+## 5. Architectural Decisions
+
+- [Stable boundaries and design decisions.]
+
+## 6. Engineering Conventions
+
+- [Validation, implementation, and code standards.]
+
+## 7. Operational Conventions
+
+- [Documentation, tooling, coordination, and release rules.]
+
+## 8. Integration Protocols
+
+- [Runtime, upstream, network, and service seams.]
+
+## 9. Pre-Task Protocol
+
+- [Preparation required by this project.]
+
+## 10. Completion Protocol
+
+- [Validation, context sync, and delivery gates.]
+```
+
+## BACKLOG
+
+```markdown
+# Project Backlog
+
+## Open Backlog
+
+- [ ] `[Slice]` [Concrete remaining work with truthful exit criteria.]
+```
+
+Keep only open, gated, or blocked work. Remove completed items after recording meaningful delivery in the canonical history surface.
+
+## CHANGELOG
+
+```markdown
+# Changelog
+
+## [Version or Current]
+
+- `[Area]` [Delivered outcome]. Impact: [Meaningful user/operator/developer effect.]
+```
+
+## Durable Convention Entry
+
+```markdown
+- `[Label]`: [Reusable constraint or insight.]
+  - Trigger: [Observed condition.]
+  - Action: [Future behavior.]
+```
+
+## Subtree README
+
+```markdown
+# [Area Name]
+
+[One-sentence responsibility.]
+
+## What This Area Owns
+
+- [Responsibility.]
+
+## Key Entry Points
+
+- [Relevant file or directory](./path)
+- [Parent or related documentation](../README.md)
+```
+
+## Docs Index
+
+```markdown
+# Documentation Index
+
+Living index of project documentation.
+
+## Documents
+
+- [`filename.md`](./filename.md): [Purpose.]
+```
+
+## Project Document
+
+```markdown
+# [Document Title]
+
+## Overview
+
+[What this document owns and why it exists.]
+
+## [Main Section]
+
+[Content organized from general contract to specific behavior.]
+
+## Related
+
+- [Related document](./related.md)
+```
+
+## README Status Update
+
+Use when local entrypoint truth changed:
+
+```markdown
+## Current Status
+
+- [What this area now owns or exposes.]
+- [Changed entrypoint, workflow, compatibility, or boundary.]
+```

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

@@ -0,0 +1,117 @@
+# `validate-context` Design
+
+## Purpose
+
+`validate-context` supplies structural evidence for the ABCd graph. It checks ownership surfaces, navigation, links, drift signals, and Markdown shape. It cannot prove that documentation claims match implementation; the full audit keeps that manual responsibility explicit.
+
+## Runtime
+
+`scripts/validate-context.mjs` is the single supported implementation. It runs on the supported Node runtime and prints classic human-readable validation logs by default.
+
+## Root Resolution
+
+Resolution order:
+
+1. Explicit `project-root` argument.
+2. `VALIDATE_CONTEXT_ROOT`.
+3. Current working directory.
+
+A missing or non-directory root fails before validation.
+
+## Checks
+
+1. `Durable file detection — Error`: Finds `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `GEMINI.md`, or `CONTEXT.md`.
+2. `Root README connectivity — Warning`: Checks references to the durable file, canonical open work, completed history, and docs index when present.
+3. `Core durable structure — Warning`: Accepts numbered mature-project sections or compact skill-style meta/operating sections.
+4. `Root state split — Warning`: Detects the canonical plan, completed-history surface, delivery history inside the durable file, and obvious backlog/changelog label drift.
+5. `Relative links and anchors — Error`: Validates Markdown links outside fenced code blocks, including heading anchors and GitHub-style line-reference bounds.
+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.
+
+## Severity Contract
+
+- `Pass`: The structural check found no issue.
+- `Info`: Evidence or an intentionally skipped bounded check.
+- `Warning`: Potential drift requiring judgment; warnings do not change exit status.
+- `Error`: Broken structural invariant or invalid invocation; errors return exit `1`.
+
+Exit `0` never means the context is factually correct. It means automated checks found no errors.
+
+## Link Validation
+
+The validator scans Markdown under the project root while excluding common generated, dependency, cache, and vendor directories. It ignores links and table syntax inside fenced code blocks, including backtick or tilde fences with CommonMark-compatible indentation and matching closing-fence length.
+
+It handles anchor-only, relative-file, file-plus-anchor, and GitHub line-reference links. Heading anchors use GitHub-style normalization while preserving underscores. Line references must point to existing lines.
+
+Files larger than `ABCD_MARKDOWN_LINK_SCAN_MAX_BYTES`, default `262144`, skip link scanning and emit an info item instead of spending unbounded time on generated or reference dumps.
+
+## Root State Drift
+
+The validator prefers `BACKLOG.md` but accepts `TODO.md`, `PLAN.md`, and `ROADMAP.md` with a warning.
+
+It warns when:
+
+- The durable file contains a `Change History` section while `CHANGELOG.md` exists.
+- An unchecked backtick-labelled backlog slice also appears in `CHANGELOG.md`.
+
+These checks identify suspicious duplication; they do not prove semantic completion.
+
+## Bloat Signals
+
+The validator avoids a hard file-length limit. It checks independent signals:
+
+- `Low information density`: Structural elements make up less than 40% of nonblank lines.
+- `Sparse structure`: The file averages more than 15 lines per heading.
+
+Signals suggest consolidation; they do not replace judgment.
+
+## Markdown Tables
+
+Table checks always run and have no enabling option.
+
+- Delimiter cells use exactly three hyphens, optional alignment colons, and one space inside each pipe: for example, `| --- | ---: | :--- |`.
+- Delimiters without inner spaces or with padded hyphen runs fail validation.
+- Table row length has no maximum; each contiguous table emits one warning when one or more rows exceed 120 characters.
+
+LaTeX is allowed and is not validated.
+
+## Human-Readable Output
+
+Validation prints each check and a summary by default. `NO_COLOR=1` disables ANSI color for CI or captured logs. There is no JSON output mode.
+
+## Regression Contract
+
+`scripts/_self-test.mjs` verifies the Node validator against:
+
+1. `fixtures/abcd-project`, through both environment and explicit-root resolution.
+2. The `abcd-context` skill root.
+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.
+
+The fixture remains linked from [its README](../fixtures/abcd-project/README.md).
+
+## Usage
+
+```bash
+# Current project
+node /path/to/skill/scripts/validate-context.mjs
+
+# Explicit root
+node /path/to/skill/scripts/validate-context.mjs /path/to/project
+
+# Skill regression suite
+node /path/to/skill/scripts/_self-test.mjs
+```
+
+## Related
+
+- [SKILL.md](../SKILL.md) — operating kernel
+- [protocols.md](./protocols.md) — reconciliation and consolidation rules
+- [templates.md](./templates.md) — starter and restructuring shapes

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

@@ -0,0 +1,10 @@
+# Project Context
+
+## Meta-Protocol Principles
+
+- `Single Source of Truth`: Durable protocol, open work, completed delivery,
+  and docs stay in separate files.
+
+## Operating Principles
+
+- `Context Domain`: Keep context compact and truthful.

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

@@ -0,0 +1,5 @@
+# Project Backlog
+
+## Open Backlog
+
+- [ ] `Fixture Follow-Up`: keep one open item so plan detection is exercised.

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

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-05-07
+
+- `Fixture Setup`: Added the fixture project. Impact: validator tests have a stable ABC root shape.

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

@@ -0,0 +1,10 @@
+# ABC Fixture Project
+
+Small fixture for `validate-context.mjs` regression tests.
+
+## Start Here
+
+- [Project Context](./AGENTS.md)
+- [Open Backlog](./BACKLOG.md)
+- [Changelog](./CHANGELOG.md)
+- [Documentation](./docs/README.md)

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

@@ -0,0 +1,7 @@
+# Documentation Index
+
+Living index of all documentation in the `/docs` directory.
+
+## Documents
+
+- [overview.md](./overview.md): Fixture overview used by validator tests.

package/node_modules/@llblab/skills/abcd-context/fixtures/abcd-project/docs/overview.md

@@ -0,0 +1,3 @@
+# Fixture Overview
+
+This document gives the fixture project one reachable docs entry.

package/node_modules/@llblab/skills/abcd-context/recipes/validate-context.json

@@ -0,0 +1,7 @@
+{
+  "description": "Run the ABCd context validator for a project root.",
+  "args": [
+    "path:path=."
+  ],
+  "template": "{skill_dir}/scripts/validate-context.mjs {path}"
+}