feat: dependency-aware capture ledger in the work tier (ADR-32) - #4
Merged
Conversation
Running abcd's own `capture` broke abcd's own `record-lint`: the issue schema required a `created:` field while `no_git_metadata` bans it under `.abcd/development`. Root cause is a category error — the ledger is generated, schema-governed working data, not authored design record. Records the decision: move the ledger to the work tier, drop git-inferable timestamps, derive priority from a `blocked_by` edge, and keep per-folder READMEs as local contracts for the authored record only. Also records the reversal of the first-pass fix (a record-lint path exemption) as the methodology-over-local-fixes principle in action. Assisted-by: Claude:claude-opus-4-8
Implements ADR-32. - Move the ledger to `.abcd/work/issues/`, out of the record-lint root, so running `capture` no longer breaks `record-lint`. - Drop the git-inferable `created`/`updated` fields; the reader tolerates legacy ones (accept, then drop) so older ledgers degrade gracefully. - Add a one-direction `blocked_by` dependency edge (`--blocked-by`) and a derived-priority view: unblocked-first, then severity, blocked rows annotated `[blocked-by iss-N]`. Priority is a read-time projection, never stored, so resolving a blocker re-prioritises its dependents automatically. - Add a store-contract README; state leaves stay self-evident. Wired on both the CLI and the plugin markdown surface. Assisted-by: Claude:claude-opus-4-8
REPPL
added a commit
that referenced
this pull request
Jul 8, 2026
* chore: land roadmap-consistency review and capture its findings An external consistency review of the design record landed at .abcd/work/reviews/2026-07-07-roadmap-consistency/. Its 14 findings plus iss-15 (the capture/record-lint conflict, fixed by ADR-32) are captured to the ledger as the tracked triage backlog, with blocked_by edges linking the dependent majors to the criticals they wait on. Gitignore the allocator lock. Assisted-by: Claude:claude-opus-4-8 * chore: resolve iss-15 (capture ⊥ record-lint) — fixed by ADR-32 The conflict that motivated the ledger redesign is closed by PR #4: capture no longer writes git-inferable metadata into the record-lint root. Assisted-by: Claude:claude-opus-4-8 * docs: resolve iss-1 (launch phase ownership) — ADR-33 The record disagreed on which phase owns /abcd:launch: the roadmap and build sequence make install + launch the first milestone, while the brief's launch surface still carried the pre-rebuild 'builds in Phase 5 (round-trip and ship)' banner. ADR-33 decides: the roadmap phase index is the sole source of phase numbering and ownership; Phase 1 owns the curated-release cut; the launch deepenings (itd-65/66/70/72/73) are separately scheduled intents, attributed by intent rather than phase number. The launch surface banner, its in-body Phase-5 references, and the launch-gatekeeper agent row are rewritten accordingly. Assisted-by: Claude:claude-fable-5 * docs: resolve iss-2 (release-version source of truth) — align to ADR-31 Three sites still described superseded versioning models: the roadmap README tracked releases by the working-tree plugin.json version (the tree is unversioned per ADR-19), and the launch surface plus verification matrix described phase-completion bump tiering with a manual --version override. ADR-31 already decides this: the version is derived from the shipped intents' impact, with the surface-diff guardrail; no version is ever authored. All three sites now state that model. Assisted-by: Claude:claude-fable-5 * docs: resolve iss-3 (phase membership vs lifecycle) — ADR-34 The intents README defined planned/ as 'scoped into a roadmap phase' while fifteen planned intents appeared in no phase Scope and two Scope-named intents (itd-43 Phase 0, itd-7 Phase 6) still sat in drafts/. ADR-34 decides the two axes are orthogonal — lifecycle is commitment (directory, adr-3), scheduling is phase Scope membership (adr-9) — with one directional invariant: scheduled implies planned/. itd-43 and itd-7 move to planned/ (itd-43's kind bound to standalone per its suggested_kind, which the intent_lifecycle lint requires of planned intents); the README's planned/ definition and directory listings now match disk. Assisted-by: Claude:claude-fable-5 * docs: resolve iss-6, iss-9, iss-10 (unblocked majors) iss-6 — the brief's scope page listed seven user-facing commands while the surfaces index lists nine; /abcd (itd-20) and /abcd:reflect (itd-24) added. iss-9 — the glossary home is .abcd/development/brief/glossary/ (adr-30); the Phase 3 milestone and the disembark terminology render source still pointed at the old foundation/terminology/ path, and the glossary README's layout block labelled the tree root terminology/. All three standardised. iss-10 — the phases README said Phase 0 has no user-facing command while phase-0-substrate.md deliberately carries /abcd:intent review; the README now states the phase doc's qualifier (no product-capability user moment, one substrate sub-verb). Assisted-by: Claude:claude-fable-5 * docs: resolve iss-4, iss-5 (six-vs-seven phases, disembark/embark banners) Both findings are instances of the superseded six-phase numbering ADR-33 identifies. iss-4: four brief files said six planned phases (Phase 0-5); the roadmap index has seven (Phase 0-6). iss-5: the disembark banner said Phase 4, the embark banner Phase 5, while phase-6-lifeboat.md owns both; the agent catalog's lifeboat-pipeline rows carried the same old numbers. All sites now point at the owning phase doc per ADR-33. Assisted-by: Claude:claude-fable-5 * docs: resolve iss-7, iss-8 (hand-kept counts, stale out-of-scope corpus) iss-7 — the brief hand-maintained a 'thirteen phased intents' count and list that the phase docs outgrew; both sites now derive by pointer to the phase docs' Scope sections (adr-9), keeping no static copy that can re-drift. iss-8 — the out-of-scope enumeration omitted ten current drafts (itd-57..75) and still included itd-43 (scheduled, moved to planned/ by ADR-34). The list is regenerated in lockstep with the drafts/ corpus and the derivation command loses its exclusion set: per ADR-34 a scheduled intent cannot live in drafts/, so the filesystem is the list. Assisted-by: Claude:claude-fable-5 * docs: resolve iss-11..iss-14 (minors + nitpick) iss-11 — agent count 15 -> 16 in the press release, scope page, and prompt-quality page, each now deferring to the 01-agents.md catalog as the canonical roster. iss-12 — the memory docs asserted spc-38/spc-39 capability as shipped while itd-36 sits in planned/ and nothing Go-built has shipped; the references are demoted to spec attribution and the surface header defers delivery state to the intent lifecycle. iss-13 — stale status narration stripped from brief contracts (per adr-5): false 'shipped' status cells in the agent catalog corrected to design target (no agents/ directory exists in this repo), '(spc-N — shipped)' parentheticals reduced to attribution, dated capture-history prose dropped from the scope page, and a delivery-state provenance note added to the brief README covering residual predecessor spc-N references. iss-14 — the intent-fidelity-reviewer section moved from § 6 to § 7 of 05-intent.md; every deep link and textual reference re-anchored (the § 6 lint-rule reference in intents/README.md verified still correct). Assisted-by: Claude:claude-fable-5
REPPL
added a commit
that referenced
this pull request
Jul 11, 2026
* docs: ADR-32 — the issue ledger is working-tier data Running abcd's own `capture` broke abcd's own `record-lint`: the issue schema required a `created:` field while `no_git_metadata` bans it under `.abcd/development`. Root cause is a category error — the ledger is generated, schema-governed working data, not authored design record. Records the decision: move the ledger to the work tier, drop git-inferable timestamps, derive priority from a `blocked_by` edge, and keep per-folder READMEs as local contracts for the authored record only. Also records the reversal of the first-pass fix (a record-lint path exemption) as the methodology-over-local-fixes principle in action. Assisted-by: Claude:claude-opus-4-8 * feat: dependency-aware capture ledger in the work tier Implements ADR-32. - Move the ledger to `.abcd/work/issues/`, out of the record-lint root, so running `capture` no longer breaks `record-lint`. - Drop the git-inferable `created`/`updated` fields; the reader tolerates legacy ones (accept, then drop) so older ledgers degrade gracefully. - Add a one-direction `blocked_by` dependency edge (`--blocked-by`) and a derived-priority view: unblocked-first, then severity, blocked rows annotated `[blocked-by iss-N]`. Priority is a read-time projection, never stored, so resolving a blocker re-prioritises its dependents automatically. - Add a store-contract README; state leaves stay self-evident. Wired on both the CLI and the plugin markdown surface. Assisted-by: Claude:claude-opus-4-8
REPPL
added a commit
that referenced
this pull request
Jul 11, 2026
* chore: land roadmap-consistency review and capture its findings An external consistency review of the design record landed at .abcd/work/reviews/2026-07-07-roadmap-consistency/. Its 14 findings plus iss-15 (the capture/record-lint conflict, fixed by ADR-32) are captured to the ledger as the tracked triage backlog, with blocked_by edges linking the dependent majors to the criticals they wait on. Gitignore the allocator lock. Assisted-by: Claude:claude-opus-4-8 * chore: resolve iss-15 (capture ⊥ record-lint) — fixed by ADR-32 The conflict that motivated the ledger redesign is closed by PR #4: capture no longer writes git-inferable metadata into the record-lint root. Assisted-by: Claude:claude-opus-4-8 * docs: resolve iss-1 (launch phase ownership) — ADR-33 The record disagreed on which phase owns /abcd:launch: the roadmap and build sequence make install + launch the first milestone, while the brief's launch surface still carried the pre-rebuild 'builds in Phase 5 (round-trip and ship)' banner. ADR-33 decides: the roadmap phase index is the sole source of phase numbering and ownership; Phase 1 owns the curated-release cut; the launch deepenings (itd-65/66/70/72/73) are separately scheduled intents, attributed by intent rather than phase number. The launch surface banner, its in-body Phase-5 references, and the launch-gatekeeper agent row are rewritten accordingly. Assisted-by: Claude:claude-fable-5 * docs: resolve iss-2 (release-version source of truth) — align to ADR-31 Three sites still described superseded versioning models: the roadmap README tracked releases by the working-tree plugin.json version (the tree is unversioned per ADR-19), and the launch surface plus verification matrix described phase-completion bump tiering with a manual --version override. ADR-31 already decides this: the version is derived from the shipped intents' impact, with the surface-diff guardrail; no version is ever authored. All three sites now state that model. Assisted-by: Claude:claude-fable-5 * docs: resolve iss-3 (phase membership vs lifecycle) — ADR-34 The intents README defined planned/ as 'scoped into a roadmap phase' while fifteen planned intents appeared in no phase Scope and two Scope-named intents (itd-43 Phase 0, itd-7 Phase 6) still sat in drafts/. ADR-34 decides the two axes are orthogonal — lifecycle is commitment (directory, adr-3), scheduling is phase Scope membership (adr-9) — with one directional invariant: scheduled implies planned/. itd-43 and itd-7 move to planned/ (itd-43's kind bound to standalone per its suggested_kind, which the intent_lifecycle lint requires of planned intents); the README's planned/ definition and directory listings now match disk. Assisted-by: Claude:claude-fable-5 * docs: resolve iss-6, iss-9, iss-10 (unblocked majors) iss-6 — the brief's scope page listed seven user-facing commands while the surfaces index lists nine; /abcd (itd-20) and /abcd:reflect (itd-24) added. iss-9 — the glossary home is .abcd/development/brief/glossary/ (adr-30); the Phase 3 milestone and the disembark terminology render source still pointed at the old foundation/terminology/ path, and the glossary README's layout block labelled the tree root terminology/. All three standardised. iss-10 — the phases README said Phase 0 has no user-facing command while phase-0-substrate.md deliberately carries /abcd:intent review; the README now states the phase doc's qualifier (no product-capability user moment, one substrate sub-verb). Assisted-by: Claude:claude-fable-5 * docs: resolve iss-4, iss-5 (six-vs-seven phases, disembark/embark banners) Both findings are instances of the superseded six-phase numbering ADR-33 identifies. iss-4: four brief files said six planned phases (Phase 0-5); the roadmap index has seven (Phase 0-6). iss-5: the disembark banner said Phase 4, the embark banner Phase 5, while phase-6-lifeboat.md owns both; the agent catalog's lifeboat-pipeline rows carried the same old numbers. All sites now point at the owning phase doc per ADR-33. Assisted-by: Claude:claude-fable-5 * docs: resolve iss-7, iss-8 (hand-kept counts, stale out-of-scope corpus) iss-7 — the brief hand-maintained a 'thirteen phased intents' count and list that the phase docs outgrew; both sites now derive by pointer to the phase docs' Scope sections (adr-9), keeping no static copy that can re-drift. iss-8 — the out-of-scope enumeration omitted ten current drafts (itd-57..75) and still included itd-43 (scheduled, moved to planned/ by ADR-34). The list is regenerated in lockstep with the drafts/ corpus and the derivation command loses its exclusion set: per ADR-34 a scheduled intent cannot live in drafts/, so the filesystem is the list. Assisted-by: Claude:claude-fable-5 * docs: resolve iss-11..iss-14 (minors + nitpick) iss-11 — agent count 15 -> 16 in the press release, scope page, and prompt-quality page, each now deferring to the 01-agents.md catalog as the canonical roster. iss-12 — the memory docs asserted spc-38/spc-39 capability as shipped while itd-36 sits in planned/ and nothing Go-built has shipped; the references are demoted to spec attribution and the surface header defers delivery state to the intent lifecycle. iss-13 — stale status narration stripped from brief contracts (per adr-5): false 'shipped' status cells in the agent catalog corrected to design target (no agents/ directory exists in this repo), '(spc-N — shipped)' parentheticals reduced to attribution, dated capture-history prose dropped from the scope page, and a delivery-state provenance note added to the brief README covering residual predecessor spc-N references. iss-14 — the intent-fidelity-reviewer section moved from § 6 to § 7 of 05-intent.md; every deep link and textual reference re-anchored (the § 6 lint-rule reference in intents/README.md verified still correct). Assisted-by: Claude:claude-fable-5
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Redesigns the capture issue ledger so running abcd's own
captureno longer breaks abcd's ownrecord-lint.Dogfooding surfaced a shipped-vs-shipped contradiction:
capture's schema required acreated:field, whilerecord-lint'sno_git_metadatabans it under.abcd/development. Root cause was a category error — the ledger is generated, schema-governed working data, not authored design record.Changes (ADR-32)
.abcd/work/issues/, out of the record-lint root. Dissolves the conflict at its source (no lint exemption).created/updated; git is canonical. The reader tolerates legacy ones (accept, then drop) so older ledgers degrade gracefully.--blocked-byflag stores a one-directionblocked_byedge;capture list/status render a derived-priority view (unblocked-first, then severity; blocked rows annotated[blocked-by iss-N]). No stored priority — resolving a blocker re-prioritises dependents automatically.Testing
make preflightgreen (build, gofmt, vet,go test ./...,-race),record-lintclean,check-reviewsOK. New tests:blocked_byround-trip, derived priority (list + status), CLI end-to-end + bad-token rejection.Not in this PR
The roadmap-consistency review and its 15 captured issues are a separate housekeeping concern (follow-up branch). This PR is the ledger machinery + its ADR only.
Assisted-by: Claude