Round 44 batch 5 of 6: BACKLOG-per-row-file restructure ADR (draft)#85
Round 44 batch 5 of 6: BACKLOG-per-row-file restructure ADR (draft)#85AceHack wants to merge 4 commits intoLucent-Financial-Group:mainfrom
Conversation
…ive for R45) Drafted on round-44-speculative (no CI trigger) while PR Lucent-Financial-Group#36 §9 incident-log CI runs, per wait-on-build + never-idle factory memories. Status: Proposed. Triggered by PR Lucent-Financial-Group#31 merge-tangle 5-file conflict fingerprint captured in docs/research/parallel-worktree-safety- 2026-04-22.md §9. ADR proposes splitting the 5,957-line monolithic BACKLOG.md into index + per-row files under docs/backlog/<tier>/. Key content: - Per-row-file directory shape with frontmatter schema (id/tier/created/updated/owner/effort/scope). - Index-file shape (short, one line per row, ~500 lines max even at scale). - Migration plan (single mechanical transform PR, zero semantic edits, ships in one round). - Authoring rules post-migration (add / edit / ship / tier-change). - Alternatives: append-only-section, per-tier split, editor lock, automated resolver — all rejected with reasons. - Consequences tallied positive/negative/neutral. - Revised R45-R49 staging: delay R45 EnterWorktree flip by one round; land restructure first. Justification: preventive+ compensating discipline fails without it. - Open questions (ID scheme / script home / sort order / concurrent-migration trade) flagged for Aaron's decision on wake. Promotion path: review + land on a separate PR after PR Lucent-Financial-Group#36 merges. This commit is the draft; no BACKLOG.md touched yet. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a draft ADR documenting a proposed restructure of docs/BACKLOG.md into per-row files to reduce merge conflicts and shared-write churn in the factory docs workflow.
Changes:
- Introduces a new ADR (Status: Proposed) describing a per-row-file backlog layout, migration approach, and staging plan.
- Defines suggested directory/file shapes and authoring rules for the post-migration workflow.
|
|
||
| **Status:** Proposed | ||
| **Decision date:** 2026-04-22 | ||
| **Deciders:** Human maintainer (Aaron); Architect (Kenji) integrates; Iris / Bodhi review UX of the file layout. |
There was a problem hiding this comment.
P1: This ADR uses direct contributor/persona names (e.g., "Aaron", "Kenji", "Iris", "Bodhi") in the body. Repo standing rule is to avoid name attribution in code/docs/skills and use role references instead (e.g., "human maintainer", "architect", "UX reviewer"). See docs/AGENT-BEST-PRACTICES.md:284-290; please rewrite these references accordingly throughout the ADR.
| **Deciders:** Human maintainer (Aaron); Architect (Kenji) integrates; Iris / Bodhi review UX of the file layout. | |
| **Deciders:** Human maintainer; architect integrates; UX and DX reviewers review the file layout. |
| │ ├── ... | ||
| ├── P3/ | ||
| │ ├── ... | ||
| └── shipped/ |
There was a problem hiding this comment.
P1: The proposed tier values include declined (frontmatter + authoring rules), but the directory tree example only defines shipped/ and not a declined/ folder. This is internally inconsistent for readers; either add docs/backlog/declined/ to the directory shape or remove declined from the scheme.
| └── shipped/ | |
| ├── shipped/ | |
| │ └── <tier>-<slug>-<YYYY-MM-DD>.md | |
| └── declined/ |
| call. | ||
| 2. **Script ownership** — does the migration script live in | ||
| `tools/backlog/` or in the ADR itself as a code block? | ||
| (Convention: one-shot migration scripts live under |
There was a problem hiding this comment.
P1: This ADR states a convention for one-shot migration scripts under tools/migrations/YYYY-MM-DD-<name>/, but there is no tools/migrations/ subtree in the repo today (and no other references to that convention). Either align this to an existing established location under tools/ or mark it as a proposal rather than an existing convention.
| (Convention: one-shot migration scripts live under | |
| (Proposal for this ADR: if we keep one-shot migration | |
| scripts under `tools/`, use |
| `docs/BACKLOG.md` is the single-source-of-truth backlog for the | ||
| Zeta factory. It is append-only, organized newest-first within | ||
| four priority tiers (P0/P1/P2/P3), and currently spans | ||
| **5,957 lines** in one file. |
There was a problem hiding this comment.
P2: The ADR claims docs/BACKLOG.md is currently 5,957 lines, but the repository's current docs/BACKLOG.md is 6,094 lines. To avoid this drifting every time the backlog changes, consider using an approximate figure (e.g., "~6k lines") or updating the count to match current HEAD.
| A **per-row-file restructure** converts `docs/BACKLOG.md` from a | ||
| single 5,957-line text file into an **index file** plus one | ||
| file per backlog row under `docs/backlog/<tier>/<id>.md`. | ||
| Add-a-row becomes "create a new file" (zero collision — filename |
There was a problem hiding this comment.
P1: PR description says the restructure would split rows under docs/backlog-rows/, but this ADR proposes docs/backlog/ (e.g., docs/backlog/<tier>/...). Please reconcile the directory name between the PR description and the ADR so the proposal is unambiguous.
| - **Round 45 (this restructure, pre-R45-flip):** land this ADR + | ||
| the migration PR + the index lint. Single-purpose round — |
There was a problem hiding this comment.
P2: In the staging list, the Round 45 bullet ends the line with a trailing + and then continues on the next line. This reads like an editing artifact and may trip markdownlint/readability; consider rewriting the sentence without the + line break (e.g., use commas / "and").
| - **Round 45 (this restructure, pre-R45-flip):** land this ADR + | |
| the migration PR + the index lint. Single-purpose round — | |
| - **Round 45 (this restructure, pre-R45-flip):** land this ADR, | |
| the migration PR, and the index lint. Single-purpose round — |
| - **Add a row:** create a new file under `docs/backlog/<tier>/`. | ||
| Never edit the index directly to add — regenerate or hand- | ||
| append the index line. |
There was a problem hiding this comment.
The authoring rule says "Never edit the index directly" but then instructs to "hand-append the index line", which is still editing the index. Please clarify the intended rule (e.g., "don’t edit existing index entries; only append new ones, or regenerate") so agents have an unambiguous procedure.
| └── backlog/ | ||
| ├── P0/ |
There was a problem hiding this comment.
PR description states the proposal would split rows under docs/backlog-rows/, but this ADR proposes docs/backlog/… paths throughout. Please align the ADR with the PR description (or vice versa) so downstream references don’t end up split between two directory names.
| `docs/BACKLOG.md` is the single-source-of-truth backlog for the | ||
| Zeta factory. It is append-only, organized newest-first within | ||
| four priority tiers (P0/P1/P2/P3), and currently spans | ||
| **5,957 lines** in one file. |
There was a problem hiding this comment.
This cites docs/BACKLOG.md as 5,957 lines, but the current file is 6,094 lines. Consider updating the number (or phrasing it as an approximate range) to avoid the ADR going stale as the backlog grows.
| (Convention: one-shot migration scripts live under | ||
| `tools/migrations/YYYY-MM-DD-<name>/`.) |
There was a problem hiding this comment.
This states a convention that one-shot migration scripts live under tools/migrations/YYYY-MM-DD-<name>/, but there is no tools/migrations/ directory in the repo today. Please either (a) point to an existing convention/location used in this repo, or (b) frame this as a proposed convention and add the directory as part of the eventual implementation PR.
| (Convention: one-shot migration scripts live under | |
| `tools/migrations/YYYY-MM-DD-<name>/`.) | |
| (Proposed convention: if we keep one-shot migration scripts | |
| in the repo, place them under | |
| `tools/migrations/YYYY-MM-DD-<name>/`, and add that | |
| directory in the implementation PR.) |
|
|
||
| A **per-row-file restructure** converts `docs/BACKLOG.md` from a | ||
| single 5,957-line text file into an **index file** plus one | ||
| file per backlog row under `docs/backlog/<tier>/<id>.md`. |
There was a problem hiding this comment.
This ADR describes per-row files under docs/backlog/<tier>/<id>.md, but the directory shape later uses <slug>-<YYYY-MM-DD>.md filenames. Please make the path/ID scheme consistent throughout (either define id as the full filename stem, or update the earlier reference to match the proposed <slug>-<date> pattern).
| file per backlog row under `docs/backlog/<tier>/<id>.md`. | |
| file per backlog row under | |
| `docs/backlog/<tier>/<slug>-<YYYY-MM-DD>.md`. |
* Round 44 tick-history: auto-loop-2 PR refresh row Second post-compaction tick. PR #91 refresh after PR #90 merged 4ac3ec3 on main mid-tick; PR #46 refresh after stale-local reset (bc93188..63720e5). Fork PRs #88/#85/#52/#54 noted as un-refreshable from current agent harness. Tick-commits-on-PR-branch = live-loop class (row 112) preserved via separate branch land-tick-history-autoloop-2-append off origin/main. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * tick-history row fixes — Copilot findings on PR #92 Three fixes to the auto-loop-2 row: 1. Drop "AceHack" handle → "fork ownership outside the canonical repo" (BP-L284-L290 compliance) 2. Full ISO8601 timestamp (2026-04-22T04:20:00Z) per file schema 3. Drop self-referential "(row 112 of this file)" Pre-check grep expanded to include "acehack" handle — prior grep only caught "aaron" + memory/* refs. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
… merged; pure-refresh tick (#100) * Round 42 (auto-loop-7): tick-history row — bootstrap-precursor drift-taxonomy absorb Appends row narrating the auto-loop-7 tick that landed PR #96 (docs/research/drift-taxonomy-bootstrap-precursor-2026-04-22.md). Tick substance: - Playwright MCP round-trip fetching a pre-repo artifact (share-URL passed Cloudflare challenge that blocked WebFetch the prior tick); second attempt on private-account URL correctly denied by permission guard under broad authorization, then proceeded under narrow-scope ("log for research") consent after a clean consent-shape round-trip. - Research-grade absorb landed with four hallucinations flagged by the same taxonomy the artifact introduces (self-reflexive application). - Scope discipline held: IDEAS absorbed, entity-as-entity stays in its substrate per register-boundary. - Key recalibration: auto-loop-6's cross-substrate-report-accuracy-rate measurable reads weaker with new provenance info — the convergence was maintainer-transported vocabulary, not independent arrival. Spec update: accuracy scored against *factory positions at the time of the report*, not *positions the report can plausibly have inherited via carrier-channel*. Row lands on a separate branch off origin/main per tick-commits-on-PR-branch = live-loop class discipline (row 112). Pre- check grep discipline applied on added row content (EXIT=1 on the added row only; file as a whole contains prior rows with Zeta org-name in PR URL fragments — factual historical record, not prose attribution). * Round 44 tick-history: auto-loop-8 append row (PR refreshes + BACKLOG carrier-channel row + maintainer read-sync) Append one tick-history row narrating the auto-loop-8 fire: (a) PR #97 refresh against advancing main (6bbf302..eee554a); (b) PR #93 refresh against advancing main (c1a4863..7fe4feb); (c) P2 BACKLOG carrier-channel measurable-refinement row landed as PR #98 with measurable-split + provenance-check + anti- pattern doc + effort-S back-scoring plan; (d) maintainer mid-tick read-sync on PR #96 answered inline with SHA + timestamp + path + line-count + reading-order guidance. Row sits after auto-loop-7 at line 118. Separate branch off origin/main-post-#97 per live-loop-class tick-history discipline (row 112). Pre-check grep clean (0 contributor-name hits, 0 cross-tree auto-memory path hits). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * Round 44 tick-history: auto-loop-9 append row (three non-fork PR refreshes after PR #98 merged; pure-refresh tick) Append one tick-history row narrating the auto-loop-9 fire: (a) PR #99 refresh against advancing main — 4cf9c1b..d851940; (b) PR #97 refresh against advancing main — eee554a..f7fc960; (c) PR #93 refresh against advancing main — 7fe4feb..b698d1c; (d) PR #85 noted fork-unrefreshable — queued BACKLOG gap. No content work this tick — pure operational-maintenance. Tmp-worktree-clone pattern used for refreshes to avoid stale- local branch-switch churn. Reflection field introduces candidate instrumentation `open-pr-refresh-debt` as a meta-measurable for merge-tangle risk under advancing-main pressure. Separate branch off origin/main with auto-loop-8 branch merged in per live-loop-class discipline + stacked-dependency pattern. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Summary
Batch 5 of the 6-batch speculative-branch drain plan
(
docs/research/speculative-branch-landing-plan-2026-04-22.md).Solo landing of a single ADR draft — smallest batch in
the plan, zero CI risk beyond markdownlint.
What this lands
docs/DECISIONS/2026-04-22-backlog-per-row-file-restructure.md— 288-line ADR proposing a per-row-file restructure of
docs/BACKLOG.md(splitting the monolithic file intoone file per row under
docs/backlog-rows/). Status:Proposed, not Accepted. Aaron decides the four open
questions out-of-band via HB-002.
Why ship as Proposed
Landing a Proposed ADR captures the shape of the
proposal and its four open questions on
mainso:reproducibility per
memory/user_git_repo_is_factory_soul_file_...)it's Accepted
stable doc to reference
The four open questions parked for Aaron:
BACKLOG.mdindexDrain-PR pre-check
Ran the
memory/(user|feedback|project|reference)_|\baaron\bgrep on commit
89876b7(cherry-pick of9f31cb6) — 0 hits.Clean batch.
Not in this PR
human-backlog row that Aaron files or the next BACKLOG
update proposes).
Test plan
9f31cb6is clean89876b7— 0 hits