Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/BACKLOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -310,7 +310,7 @@ are closed (status: closed in frontmatter)._
- [x] **[B-0505](backlog/P1/B-0505-b0442-slice5c-docs-autonomous-loop-acceptance-close-2026-05-14.md)** B-0442 slice 5c — docs update (AUTONOMOUS-LOOP.md + bg/README.md) + B-0442 acceptance close
- [x] **[B-0507](backlog/P1/B-0507-b0448-slice1-cloud-routines-api-research-2026-05-14.md)** B-0448 slice 1 — Research Cloud Routines auth + registration API surface (resolve unknowns)
- [x] **[B-0508](backlog/P1/B-0508-b0448-slice2-cloud-schedule-json-schema-2026-05-14.md)** B-0448 slice 2 — Define cloud-schedule.json schema for tools/routines/<id>/
- [ ] **[B-0509](backlog/P1/B-0509-b0448-slice3-install-ts-cloud-schedule-extension-2026-05-14.md)** B-0448 slice 3 — Extend tools/routines/install.ts to detect + surface cloud-schedule.json
- [x] **[B-0509](backlog/P1/B-0509-b0448-slice3-install-ts-cloud-schedule-extension-2026-05-14.md)** B-0448 slice 3 — Extend tools/routines/install.ts to detect + surface cloud-schedule.json
- [x] **[B-0510](backlog/P1/B-0510-b0448-slice4-autonomous-loop-cloud-schedule-json-2026-05-14.md)** B-0448 slice 4 — Author autonomous-loop/cloud-schedule.json (first Cloud Routine declaration)
- [ ] **[B-0511](backlog/P1/B-0511-b0448-slice5-register-cloud-routine-empirical-fire-2026-05-14.md)** B-0448 slice 5 — Register autonomous-loop as Cloud Routine + empirical first-fire observation
- [ ] **[B-0512](backlog/P1/B-0512-b0448-slice6-readme-4-layer-table-2026-05-14.md)** B-0448 slice 6 — Update tools/routines/README.md with 4-layer catch-43 table
Expand Down Expand Up @@ -600,6 +600,7 @@ are closed (status: closed in frontmatter)._
- [ ] **[B-0580](backlog/P2/B-0580-enterprise-ruleset-management-2026-05-16.md)** Enterprise GitHub ruleset management — new layer above org/individual mapping (composes with prior ruleset-divergence smell decomposition)
- [ ] **[B-0583](backlog/P2/B-0583-cross-machine-account-scoped-scarcity-bus-2026-05-16.md)** Cross-machine account-scoped scarcity bus — refine B-0570 from machine-local per-agent files to account-scoped timestamped surface
- [ ] **[B-0610](backlog/P2/B-0610-amazon-orders-extract-v3-design-pass-2026-05-16.md)** Amazon orders extract — v3 design pass (8 deferred reviewer-thread findings)
- [ ] **[B-0611](backlog/P2/B-0611-dangling-memory-refs-cleanup-35-refs-6-surfaces-2026-05-17.md)** Dangling memory-refs cleanup — 35 refs across 6 substrate surfaces (use PR #4042 audit tool)

## P3 — convenience / deferred

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
---
id: B-0611
title: Dangling memory-refs cleanup — 35 refs across 6 substrate surfaces (use PR #4042 audit tool)
status: open
priority: P2
created: 2026-05-17
last_updated: 2026-05-17
type: chore
composes_with:
- B-0510 # prior B-NNNN substrate work via Otto-CLI; uses the same audit tool surface
depends_on: []
---

# Dangling memory-refs cleanup — 35 refs across 6 substrate surfaces

## Substrate-honest context

PR #4031 (closed audit memo, 2026-05-15) surfaced 5 dangling
`memory/feedback_*.md` refs in `.claude/rules/`. PR #4041
([merged 2026-05-17](https://github.com/Lucent-Financial-Group/Zeta/pull/4041))
extended the audit to find 29 across 4 substrate surfaces
(`.claude/rules` + `.claude/skills` + `docs/research` + `docs/backlog`).
PR #4042 ([merged 2026-05-17](https://github.com/Lucent-Financial-Group/Zeta/pull/4042))
mechanized the methodology as
[`tools/hygiene/audit-dangling-memory-refs.ts`](../../../tools/hygiene/audit-dangling-memory-refs.ts).

This row captures the **cleanup work itself** — the audit memos and
the audit tool exist, but the dangling refs have not been resolved.

Running the audit tool 2026-05-17T06:23Z (this row's filing tick)
surfaces **35 dangling refs across 6 surfaces**:

| Surface | scanned | uniqueRefs | uniqueDanglingRefs |
|---|---:|---:|---:|
| `.claude/agents` | 19 | 0 | 0 |
| `.claude/skills` | 262 | 14 | 1 |
| `.claude/rules` | 56 | 74 | 5 |
| `docs/research` | 355 | 186 | 8 |
| `docs/backlog` | 674 | 205 | 17 |
| `memory/persona` | 288 | 60 | 4 |
| **Total** | **1654** | **539** | **35** |

The drift has grown (29 → 35) between PR #4041 audit and today's
run — new substrate authoring continues to add citations to
user-scope memory paths that don't exist in-repo.

## Why this matters

The maintainer's Otto-CLI auto-loads user-scope memory at
`~/.claude/projects/.../memory/`, so citations like
`memory/feedback_<name>.md` resolve transparently for the maintainer.
A cold-boot agent on a fresh checkout (different machine, new
contributor, CI agent, fresh-clone-CI run) does NOT have user-scope
memory and follows the path to find nothing. The link is dead.

Per [`.claude/rules/substrate-or-it-didnt-happen.md`](../../../.claude/rules/substrate-or-it-didnt-happen.md):
"chat is weather, substrate is durable." If a substrate file
points to a memory file that exists only in user-scope, the rule
is partially weather for cold-boot consumers.

## Scope

For each of the 35 dangling refs, pick one of three resolutions:

1. **In-repo projection (preferred for load-bearing claims)**:
create an in-repo summary of the user-scope content (or move the
file in-repo if the maintainer's PII discipline allows) and update
the citation to point at the in-repo file. Follows the pattern
already in use by some rules (e.g.,
`.claude/rules/codeql-no-source-on-docs-only-pr-is-broken-commit-canary.md`
which has a "cold-boot agents on fresh checkouts: this rule's own
body above is the canonical in-repo projection" pattern).

2. **Footnote-the-user-scope-with-fallback**: keep the citation but
add a one-line note that the file is user-scope only AND name the
in-repo fallback substrate (e.g., `memory/CURRENT-otto.md` or the
rule body itself). Follows the pattern in
`.claude/rules/m-acc-multi-oracle-end-user-moral-invariants.md`
which explicitly footnotes user-scope-only references.

3. **Remove the citation**: if the cited memory was an artifact of
an earlier iteration that no longer load-bears the surrounding
substrate, just delete the citation. Less common; substrate-
honest only when the citation is truly orphaned.

## Acceptance

- [ ] All 35 dangling refs resolved via one of the 3 patterns above
- [ ] `bun tools/hygiene/audit-dangling-memory-refs.ts` exits 0
(no dangling refs on any of the 6 default surfaces)
- [ ] Audit tool wired into CI (separate row OR same; see
Workflow notes)
- [ ] Composing rule update (if needed): clarify the
in-repo-projection pattern in
`.claude/rules/substrate-or-it-didnt-happen.md` or sibling
rule so future authors avoid the pattern proactively
- [ ] **Audit tool semi-automation** (verified 2026-05-17T06:44Z:
tool has only `--json` and `--surfaces` flags; no `--fix`,
`--allowlist`, or `--suggest` logic in source): consider adding
one of: (a) `--allowlist <path>` flag reading a `.audit-allowlist`
file with `<surface>:<line>:<ref>` entries marking known-
intentional dangling refs (composes with Option A from the
slice-1 recipe memo at
`memory/feedback_otto_cli_b0611_slice1_audit_recipe_*_2026_05_17.md`);
(b) `--suggest` mode that prints the 4-option resolution menu
per dangling ref; OR (c) inline annotation parser (e.g., HTML
comment `<!-- audit-allowlist: user-scope-intentional -->`
adjacent to the citation, opt-in per ref). Decision composes
with the design choice from the slice-1 recipe memo.

## Workflow notes

The cleanup is bounded but tedious — 35 individual decisions, each
small. Suggested decomposition:

- **Slice 1 (P2)**: `.claude/skills` (1 ref) + `.claude/rules`
(5 refs) — 6 refs, smallest scope, highest-leverage (rules
auto-load at session start so cleanup here ripples furthest)
- **Slice 2 (P2)**: `memory/persona` (4 refs) — bounded, persona-
scoped
- **Slice 3 (P2)**: `docs/research` (8 refs) — verbatim-preservation
files; resolutions likely lean toward "keep citation + footnote"
- **Slice 4 (P3)**: `docs/backlog` (17 refs) — largest scope, lowest
urgency (backlog rows are work-in-progress citations, churn fast)

Each slice can be a separate small PR or grouped commits within
one PR. The audit tool's `--surfaces` flag scopes the verification.

The CI integration is a separate concern: the audit tool exits 1
on dangling refs, so wiring it into CI would block authoring until
33 of 35 are resolved (the tool reports 35 today; new authoring will
add more). Best practice: wire to CI with an allowlist that
ratchets down OR run as advisory-only initially.

## Composes with

- PR #4042 — the audit tool (`tools/hygiene/audit-dangling-memory-refs.ts`)
- PR #4041 — extended audit memo (29 refs)
- PR #4031 — original audit memo (5 refs in rules)
- [`.claude/rules/substrate-or-it-didnt-happen.md`](../../../.claude/rules/substrate-or-it-didnt-happen.md)
— the rule defining substrate vs weather
- [`.claude/rules/wake-time-substrate.md`](../../../.claude/rules/wake-time-substrate.md)
— auto-loaded rules MUST be discoverable from cold-boot; dangling
refs in auto-loaded rules degrade cold-boot discoverability
- [`.claude/rules/honor-those-that-came-before.md`](../../../.claude/rules/honor-those-that-came-before.md)
— preserves memory; cleanup must NOT delete user-scope content
in the maintainer's home directory; only resolve citations from
in-repo surfaces

## Substrate-honest framing

The dangling refs are not "broken" in the maintainer's
day-to-day operational sense — his Otto-CLI auto-loads the files
and follows the citations correctly. The drift is between the
maintainer's local substrate (rich) and the in-repo substrate
(thinner). Cleanup elevates the in-repo substrate to match what
the maintainer sees, OR documents the asymmetry explicitly via
the footnote pattern.

This is NOT a P0/P1 because no shipping pipeline is blocked. It
is P2 because cold-boot agents (the framework's design audience)
hit dead links and lose substrate context.
Loading
Loading