Development record
A decision points back to the conversation where it was reached
Press Release
Seeded by promotion from iss-2608290819228175. Expand into the full press-release narrative before planning.
Why This Matters
A decision recorded in an intent, an architecture decision record, or the decision log should point at the passage of the redacted transcript where it was actually reached, so the reasoning behind a record is recoverable rather than lost with the session that produced it. The record is the floor of recoverable theory, not the theory itself.
This is the trace the facilitator needs when the product thinker reports that the product does not match what they expected. Because the facilitator is a machine by default, the trace has to be machine-followable rather than merely readable by a person who was there.
The store is closer to this than it looks. A transcript record already carries a session identifier, a content hash, and a capture timestamp, so the session is already addressable. What is missing is granularity inside one transcript: there is no per-turn anchor, so a link can name the session but not the passage.
Two constraints rule out the obvious approach. A line number is the wrong anchor, and this repository already refuses that shape elsewhere. And redaction rewrites spans in place, so any offset computed against the raw transcript is invalid against the stored redacted one: an anchor must be derived from the redacted artefact or be content-addressed rather than positional.
Acceptance Criteria
Required (the itd-1 discipline): add at least one Given-When-Then bullet describing the verifiable bar for "shipped" before this draft can be planned.
SOTA
Surveyed on 2026-10-23; sources, evidence tiers and the local fit risks are in the sources-provenance SOTA note.
- The anchor standard exists. The W3C Web Annotation Data Model's
TextQuoteSelector"MUST have exactly 1exactproperty" and SHOULD carry oneprefixand onesuffix, text normalised and counted in code points; aTextPositionSelectoris "very brittle with regards to changes to the resource"; several selectors may describe one segment and a consumer "MUST pick one". - Re-anchoring has a settled recipe. Hypothesis stores range, position and quote selectors (32 characters of context) and tries them in order: range, position, context-first fuzzy match near the expected offset, whole-document fuzzy match, with an acceptance threshold (Hypothesis fuzzy anchoring). Browser text fragments (
#:~:text=prefix-,start,end,-suffix) are the same idea built to "degrade gracefully into an ordinary link". - The host transcript already has a per-entry id. Community documentation of the JSONL describes a
uuidandparentUuidper line; the vendor's hooks page confirmssession_idandtranscript_path(which "may lag the in-memory conversation") and a per-promptprompt_id, but not the per-entry id, so its stability is not vendor-documented. - Commit-side linking is settled as a trailer the minting tool resolves: Gerrit's
Change-Idfooter inserted by a commit-msg hook and kept across amend and rebase; Entire'sEntire-Checkpoint: <id>with sessions underrefs/entire/checkpoints/..., never on the active branch, secrets redacted best-effort; GitHub'sAgent-Logs-Urltrailer on cloud-agent commits. The 2026-07-30 note already placed abcd on the transcripts-out-of-repo side; this intent is the record-side link. - Path 2: a typed cross-reference minted when the decision is recorded, holding
session_id,source_sha256of the stored record, the host entry id when present, and aTextQuoteSelectorcomputed from the redacted body (never the raw one) with a position selector as a hint only; stored on the decision record, never in the transcript; resolved byabcd history anchor <ref>in Hypothesis's order, reporting which stage matched so a stale anchor degrades to "session found, passage moved". Any line or byte form is the hint, honouring the existing refusal of positional references. No Go dependency. The independent fit-challenge runs at plan time.
Open Questions
- (SOTA 2026-10-23) The quoted
exact,prefixandsuffixare transcript prose entering a committed record; do they pass the banlist and identity scans at mint time, and how long may the span be? - (SOTA 2026-10-23) When a re-redaction rewrites inside a quoted span, is the anchor re-minted, marked suspect in the manner of a fingerprinted link, or left to fail at resolve time?
- (SOTA 2026-10-23) Is a span of a few hundred characters the unit the facilitator needs, or the whole turn (the entry id) with the span as the highlight?
Audit Notes
Empty. Populated by intent-auditor when intent moves to shipped/.
Frontmatter
| id | itd-171 |
|---|---|
| type | intent |
| lifecycle | drafts |
| severity | minor |
.abcd/development/intents/drafts/itd-171-a-decision-recorded-in-an-intent-an-adr.md
open on GitHub ↗ · commit history ↗
Referenced by1
- iss-2608290819228175A decision recorded in an intent, an ADR or the decision log should point at the section of the redacted transcript where it was actually made, so the reasoning behind a record is recoverable rather than lost with the session that produced it. This is the Naur point the lifeboat work already rests on: the record is the floor of recoverable theory, not the theory itself, and today nothing leads from a decision back to the conversation that reached it. The store is closer to this than it first appears. A transcript record already carries session_id, a source_sha256 content hash, and captured_at as an RFC3339 nanosecond timestamp, so the SESSION is timestamped and content-addressed already. What is missing is granularity inside one transcript: there is no per-turn or per-section anchor, so a link can name the session but not the passage. Two constraints shape the design and both rule out the obvious approach. A line number is the wrong anchor, and the repository already refuses that shape elsewhere through the no-brittle-line-refs rule, which tells an author to use a section anchor instead. And redaction rewrites spans in place, so any byte offset or line number computed against the raw transcript is invalid against the stored redacted one: an anchor has to be derived from the redacted artefact, or be content-addressed rather than positional. The plausible shape is therefore a typed cross-reference carrying session_id plus source_sha256 plus a stable intra-transcript anchor, minted when the decision is recorded rather than reconstructed later, with per-turn timestamps or ids added to the stored transcript so such an anchor exists to name. Worth deciding whether the anchor is a turn id, a content hash of the passage, or a heading, and whether the link is stored on the decision record, in the transcript, or both.related
mentions3
- dcn-26092900000000112026-09-29 — The product thinker answered the twenty-six Group J rulings (plan or close), J1 to J26 (recorded by lane recGroupJ of autonomous run A, for orchestrator abcd-fc). The answers are kept verbatim in the local-tier file `.abcd/.work.local/scratch/reports/rulings-answered-2609-29.md`, section "Group J", dated 2026-09-29, and are restated here because that file is not committed. PLAN: the installer script becomes a minimal starter with an ownership-checked hand-over, planned as a new intent with its planning interview owed (J2, iss-377, draft itd-2609292106557115); token metering and size classes are planned as one intent (J3, iss-2608301744251874 and iss-2608301856299268), and session token accounting in the history store joins that metering intent (J4, iss-2608220150157508; all three in draft itd-2609292107351737); the sources tooling moves into abcd's core with ingest and consult as abcd verbs (J5, iss-27, whose corpus half itd-76 already delivered), and the backfill of the placeholder source entries is part of that intent (J6, iss-55; both in draft itd-2609292108089653); the grill hands off to an installed external interview skill and falls back to its own (J11, iss-165, draft itd-2609292108373494); an opt-in local-model prompt sanitiser is planned (J14, iss-2608261543489261, draft itd-2609292109005937); decision-to-transcript links are planned, with the anchor kind and the link's home settled in the planning interview owed for draft itd-171 (J16, iss-2608290819228175); the dredge synthesis, its write-ups as their own memory source class, is planned together with draft itd-25, whose planning interview is owed (J19, iss-2609211905340006); one provenance register across ingest and vendoring is planned together with draft itd-26, whose planning interview is owed (J20, iss-2609211905346507); release retention, keeping the newest release per version line, is automated by planning draft itd-70 (J21, iss-282); a rules-backend seam with an opt-in CARL adapter is planned, the native loader staying the default (J22, iss-64, draft itd-2609292109214516); core-owned managed pre-commit gates are planned with draft itd-62 (J23, iss-84); a behavioural end-to-end scenario suite per verb family is planned (J24, iss-48, draft itd-2609292109475690). Every draft stays in drafts/ until a person plans it, and each source issue links its draft and names that planning interview in its deferral. BUILD: the teaching plane, the rules-loader safety domain generated from the hazard registry, is built as a lane, the registry being the single source (J10, iss-151 and itd-103; a code lane owns it). RULED DETAILS: `source_kind` carries both, as two separate labels, one for the tool and one for the route (J13, iss-2608230752354928); the prompt router's removal signal is the full list of active domains every time, a domain's absence meaning it has stopped (J15, iss-2608261550580260); setup offers an outside AI service (for example OpenRouter) at install, skippable, once the API adapter ships (J18, iss-2609081951416843, which waits on the API adapter); the salvage-hook timeout is 120 seconds, the wait must show a counter or a message while it runs and never stall silently, and every per-event timeout is pinned in a test (J25, iss-323). J13, J15 and J25 are carried by code lanes. CLOSE: the quick-tunnel preview protocol is closed unless the need recurs (J26, iss-2608230617385431, wontfix with that reason). PARKED ON A TRIGGER: agent payment protocols are kept under watch, not now, revisited as the protocols mature (J8, iss-138); the findings-only skill waits for the skill format to be versioned and stewarded (J9, iss-139); the disposition worksheet as an intent and a site page waits until after the first study (J17, iss-2609021815529020). DECIDE LATER: the Homebrew tap stays parked (J1, iss-380); pluggable search back ends (J7, iss-26); forge-backed record numbering (J12, iss-2608210737264758).
- dcn-26092900000000202026-09-29 — The product thinker answered the twenty-six Group J rulings (plan or close), J1 to J26 (recorded by lane recGroupJ of autonomous run A, for orchestrator abcd-fc). The answers are kept verbatim in the local-tier file `.abcd/.work.local/scratch/reports/rulings-answered-2609-29.md`, section "Group J", dated 2026-09-29, and are restated here because that file is not committed. PLAN: the installer script becomes a minimal starter with an ownership-checked hand-over, planned as a new intent with its planning interview owed (J2, iss-377, draft itd-2609292106557115); token metering and size classes are planned as one intent (J3, iss-2608301744251874 and iss-2608301856299268), and session token accounting in the history store joins that metering intent (J4, iss-2608220150157508; all three in draft itd-2609292107351737); the sources tooling moves into abcd's core with ingest and consult as abcd verbs (J5, iss-27, whose corpus half itd-76 already delivered), and the backfill of the placeholder source entries is part of that intent (J6, iss-55; both in draft itd-2609292108089653); the grill hands off to an installed external interview skill and falls back to its own (J11, iss-165, draft itd-2609292108373494); an opt-in local-model prompt sanitiser is planned (J14, iss-2608261543489261, draft itd-2609292109005937); decision-to-transcript links are planned, with the anchor kind and the link's home settled in the planning interview owed for draft itd-171 (J16, iss-2608290819228175); the dredge synthesis, its write-ups as their own memory source class, is planned together with draft itd-25, whose planning interview is owed (J19, iss-2609211905340006); one provenance register across ingest and vendoring is planned together with draft itd-26, whose planning interview is owed (J20, iss-2609211905346507); release retention, keeping the newest release per version line, is automated by planning draft itd-70 (J21, iss-282); a rules-backend seam with an opt-in CARL adapter is planned, the native loader staying the default (J22, iss-64, draft itd-2609292109214516); core-owned managed pre-commit gates are planned with draft itd-62 (J23, iss-84); a behavioural end-to-end scenario suite per verb family is planned (J24, iss-48, draft itd-2609292109475690). Every draft stays in drafts/ until a person plans it, and each source issue links its draft and names that planning interview in its deferral. BUILD: the teaching plane, the rules-loader safety domain generated from the hazard registry, is built as a lane, the registry being the single source (J10, iss-151 and itd-103; a code lane owns it). RULED DETAILS: `source_kind` carries both, as two separate labels, one for the tool and one for the route (J13, iss-2608230752354928); the prompt router's removal signal is the full list of active domains every time, a domain's absence meaning it has stopped (J15, iss-2608261550580260); setup offers an outside AI service (for example OpenRouter) at install, skippable, once the API adapter ships (J18, iss-2609081951416843, which waits on the API adapter); the salvage-hook timeout is 120 seconds, the wait must show a counter or a message while it runs and never stall silently, and every per-event timeout is pinned in a test (J25, iss-323). J13, J15 and J25 are carried by code lanes. CLOSE: the quick-tunnel preview protocol is closed unless the need recurs (J26, iss-2608230617385431, wontfix with that reason). PARKED ON A TRIGGER: agent payment protocols are kept under watch, not now, revisited as the protocols mature (J8, iss-138); the findings-only skill waits for the skill format to be versioned and stewarded (J9, iss-139); the disposition worksheet as an intent and a site page waits until after the first study (J17, iss-2609021815529020). DECIDE LATER: the Homebrew tap stays parked (J1, iss-380); pluggable search back ends (J7, iss-26); forge-backed record numbering (J12, iss-2608210737264758).
- itd-1Every Intent Has Acceptance Criteria; Every Audit Verifies Them