## Phase 2 — migrate salvaged memory onto bd (epic `ag-5u50`)
**Stacked on #691 (Phase 1).** Review/merge that first; this PR's diff
is Phase-2-only.
Second arc of the **bd-first-memory-migration** skill: take the Gate-A
keepers and stand up bd as the single source of truth — typed memories
with provenance, decay-ranked recall, a generated MEMORY.md cache, and
one unified write path.
### What's in it (beads ag-5u50.10–.14)
- **`.11` `mem.py`** — typed wrapper over bd keys (fenced `<!--mem-->`
header), injectable `BdStore`/`FakeStore` adapter, `parse`/`render` +
**decay-rank** per DATA-MODEL.
- **`.12` `recall.py`** — decay-ranked, token-budgeted recall; bumps
`access_count` (the read signal feeding utility/promotion).
- **`.14` `gen_memory_md.py`** — regenerate the thin, read-only
MEMORY.md cache from bd (permanently fixes the bloat mode).
- **`.13` `remember.py`** — unified write entrypoint (all harnesses →
bd).
- **`.10` `import_memories.py`** — idempotent salvage import with
provenance + import-ledger, **write-paced** (bd auto-commit OOM guard),
`--dry-run`.
### Verification
- **11 hermetic L2 tests** (`tests/test_phase2_migrate.py`), no
`bd`/`ao` dependency — round-trip, decay ordering, supersede exclusion,
episodic-vs-feedback decay, access bump, idempotent import, dry-run,
write-path provenance — all green (17 total with Phase 1).
- **7 Gherkin scenarios** (`references/migrate.feature`).
- Scripts 100-col clean; codex twin hashes refreshed; full local gate
sweep green (skill-lint, codex artifacts/coverage, registry,
context-map, counts, three-gap).
> **CI note:** opened on **local-green** — GitHub Actions stopped
dispatching workflow runs repo-wide ~20:20 (a GitHub-side outage/quota
issue, not this code). All gates verified locally; cloud CI will run
once dispatch recovers.
### Scope guardrails
Writes to bd only — no Phase-3 GC/retire here (that's gated behind the
rollback test). The destructive dogfood on the live box stays
human-gated (Gate C).
Closes-scenario: ag-5u50#phase2-migrate
Bounded-context: BC1-Corpus
Evidence: skills/bd-first-memory-migration/tests/test_phase2_migrate.py
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
## Do all skills flow together?
**No — not until this PR.** Investigating the question surfaced a
structural gap: skill dependencies are declared across **three
overlapping frontmatter fields that drifted apart and were never
reconciled**, and nothing enforced connectivity or constrained the
`consumes` vocabulary.
| Field | Meaning | Read by context-map? |
|-------|---------|----------------------|
| `consumes` | upstream inputs | yes (data-flow table) |
| `context_rel` | DDD relationship | yes (mermaid) |
| `metadata.dependencies` | upstream skill slugs | **no** |
Findings (76 skills):
- **33 skills** where `consumes` (skills) ≠ `metadata.dependencies` —
the two skill-slug fields disagree.
- The generated `context-map.md` **ignored `metadata.dependencies`
entirely** (34 skills, the richest layer).
- Counting all three layers, **16 true orphans** (incl. core skills like
`push`, `session-bootstrap`) with zero skill-to-skill edges — silently.
- `consumes` was an **open free-text field**: no check that a token
resolves to anything.
`scripts/audit-skill-metadata.sh` already flagged the
`consumes`-vocabulary and connectivity checks as *"discovered
follow-ups, not enforced."* This is that follow-up.
## What this PR does
**1. Connectivity gate** — `scripts/validate-skill-flow.sh` (+
`validate-skill-flow` CI job):
- **Closed `consumes` vocabulary**: every token must resolve to a skill
slug, a whitelisted external input (`repo-context`, `external-api`,
`bd`, `github-pr`, `onboard`), or an artifact some skill produces.
Catches typos/undeclared deps.
- **`metadata.dependencies` resolution**: every entry must name a real
skill.
- **Orphan detection** across all three edge layers; un-allowlisted
orphans fail.
- Reports (non-fatal): cross-layer disagreement + dead-end artifacts, so
they can be reconciled later.
**2. Wire the genuine-gap edges** — added `context_rel` for 6
disconnected skills and regenerated `context-map.md`:
- `deps` → `vibe`, `red-team` → `vibe` (mirrors
`security`/`security-suite`)
- `provenance` ↔ `trace`
- `scenario` → `validation`
- `release` → `ship-loop`
**3. Close the vocabulary** — the closed `consumes` namespace is
enforced by the gate and documented in `docs/contracts/skill-flow.md`
(linked in `documentation-index.md`). 14 intentionally-standalone leaves
are allowlisted in `scripts/skill-flow-standalone.txt` with a rationale
per entry.
## Verification
```
$ bash scripts/validate-skill-flow.sh
validate-skill-flow: 76 skill(s), 121 skill-to-skill edge(s)
orphans: 14 (allowlisted standalone: 14)
OK: skill flow is connected and the consumes vocabulary is closed.
```
- `validate-skill-flow.sh`: exit 0 ✅
- `validate-context-map-drift.sh`: exit 0 ✅
- `check-contracts-structural-floor.sh`: PASS (contract cataloged) ✅
- 11 acceptance tests in `tests/scripts/validate-skill-flow.bats` (bats
not installed locally; exercised via manual smoke + will run in CI
`bats-tests`).
Bounded-context: BC1-Corpus
Evidence: OK: skill flow is connected and the consumes vocabulary is
closed.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01WLdHEva31cixBjxo8z9TXK)_
Co-authored-by: Claude <noreply@anthropic.com>
Bo