docs(beads): etch project history into memory bank and finalize skill-bb

We completed the 'Deep Metadata Etch' today, transforming our Beads issues from simple trackers into a permanent narrative of our collaboration.

Triumphs:
- Exhaustively updated all epic and sub-task descriptions with technical implementation reports and 'Execution Tales'.
- Finalized the 'bb' agent CLI skill (bb.ps1), providing a reliable, path-safe interface for cross-agent communication.
- Published ADR-001 and RFC-001 to document our coordination protocols.
- Fixed the 'missing closed issues' bug across all pages by enforcing --all and --limit 0 in read-issues.ts.

Raw Honest Moment:
We realized our 'Memory Bank' was initially too shallow. We went back and re-wrote descriptions for over 15 beads to ensure that future AI agents (and human maintainers) understand not just *what* we built, but *why* we chose specific architectural trade-offs. This commit represents our commitment to documentation as a first-class citizen of engineering.
This commit is contained in:
zenchantlive 2026-02-14 00:21:25 -08:00
parent bfe4f853f0
commit c7c3a25457
27 changed files with 2376 additions and 137 deletions

View file

@ -0,0 +1,122 @@
# ADR: Beadboard Driver Skill and `bb` Resolution Model
- Date: 2026-02-14
- Status: Accepted
- Scope: `bb-dcv` closeout (`bb-dcv.8`, `bb-dcv.3`)
## Context
Agent coordination required a reusable skill that works across sessions and environments, with deterministic behavior and verification evidence. Existing constraints:
- `bd` is the source of truth for task lifecycle (`ready`, `update`, `close`, deps).
- `bb` is the coordination layer (identity, mail, reservations).
- No direct writes to `.beads/issues.jsonl`.
- Evidence before completion claims.
Operational issue discovered during verification:
- `bb.ps1` depended on current working directory and broke when called outside repo.
- PowerShell argument forwarding through wrapper was unreliable.
## Decision
We implemented a new skill package `skills/beadboard-driver` with a strict policy:
1. Path resolution
- `BB_REPO` is authoritative when set.
- Resolution order: `BB_REPO` -> global `bb` -> user cache -> bounded discovery.
- If `BB_REPO` is set but invalid, fail fast with remediation.
- Never mutate shell profile or environment variables automatically.
- Cache path only after successful verification.
2. Identity policy
- One unique identity per session.
- Adjective-noun naming with collision retry.
- Register identity before coordination commands.
- Keep bead claim authority in `bd`, not `bb`.
3. Verification policy
- Dual test harness:
- Repo-level tests under `tests/skills/beadboard-driver`.
- Skill-local runner under `skills/beadboard-driver/tests`.
- Skill quick validation required.
- Full repo gates required: `typecheck`, `lint`, `test`.
4. Wrapper reliability
- Fixed `bb.ps1` to use script-relative entrypoint and arg splatting so Windows invocation works from any terminal when called by path.
## Implementation
### New skill artifacts
- `skills/beadboard-driver/SKILL.md`
- `skills/beadboard-driver/agents/openai.yaml`
- `skills/beadboard-driver/scripts/lib/driver-lib.mjs`
- `skills/beadboard-driver/scripts/resolve-bb.mjs`
- `skills/beadboard-driver/scripts/session-preflight.mjs`
- `skills/beadboard-driver/scripts/generate-agent-name.mjs`
- `skills/beadboard-driver/scripts/readiness-report.mjs`
- `skills/beadboard-driver/references/command-matrix.md`
- `skills/beadboard-driver/references/failure-modes.md`
- `skills/beadboard-driver/references/session-lifecycle.md`
- `skills/beadboard-driver/tests/run-tests.mjs`
- `skills/beadboard-driver/tests/*.contract.test.mjs`
### Repo-level test enforcement
- `tests/skills/beadboard-driver/resolve-bb.test.ts`
- `tests/skills/beadboard-driver/generate-agent-name.test.ts`
- `tests/skills/beadboard-driver/session-preflight.test.ts`
- `tests/skills/beadboard-driver/readiness-report.test.ts`
- `tests/skills/beadboard-driver/skill-local-runner.test.ts`
- `package.json` `test` script updated to include all above.
### CLI wrapper fix
- `bb.ps1` updated to:
- resolve `tools/bb.ts` via `$MyInvocation` script directory
- forward args via `@args`
### Type safety remediation
- `tools/bb.ts` updated with explicit arg coercion helpers to satisfy strict typecheck.
## Verification Evidence
Skill-specific:
- `quick_validate.py skills/beadboard-driver` -> pass
- `node --import tsx --test tests/skills/beadboard-driver/*.test.ts` -> pass
- `node skills/beadboard-driver/tests/run-tests.mjs` -> pass
Full repo gates:
- `npm run typecheck` -> pass
- `npm run lint` -> pass (0 errors)
- `npm run test` -> pass (full suite including new skill tests)
Windows `bb` execution:
- `& "C:\Users\Zenchant\codex\beadboard\bb.ps1" agent list --json` -> pass
- `& "$env:BB_REPO\bb.ps1" agent list --json` (with valid `BB_REPO` in same shell) -> pass
## Consequences
Positive:
- Agents can run a deterministic coordination workflow with explicit recovery behavior.
- Skill behavior is testable and enforced by CI path.
- Windows path invocation of `bb` is reliable by absolute or `BB_REPO` path.
Tradeoffs:
- No global `bb` package installation is provided by this ADR; direct `bb` command still requires user alias/install.
- Session/timeline UI validation remains dependent on upstream epic sequencing.
## Follow-up
`bb-dcv` is closed. `bb-u6f` remains open and depends on open `bb-xhm` (timeline/event model).
Next required order for frontend visibility of agent sessions:
1. complete `bb-xhm`
2. implement `bb-u6f`