diff --git a/.abcd/development/brief/01-product/03-mental-model.md b/.abcd/development/brief/01-product/03-mental-model.md index 0a6f1d00f..ead6bdb49 100644 --- a/.abcd/development/brief/01-product/03-mental-model.md +++ b/.abcd/development/brief/01-product/03-mental-model.md @@ -1,3 +1,5 @@ +> **Read with adr-2609212115255771 (2026-09-21).** The phase layer described below is retired: the layers are the brief, the intent and the spec (with its steps), the bundle is a delivery grouping of intents, the derived release is the checkpoint, and Now / Next / Later is a rendered status, never a stored unit. The diagram and the prose keep the phase until itd-2609211913453478 rewrites this chapter; until then, read "phase" as history. + # Four-Layer Mental Model abcd uses four layers to organise development work, each tuned to the kind of question it answers. Three are the original design layers — brief, intent, spec; the fourth, **phase**, is the sequencing-and-reflection layer added per [adr-9](../../decisions/adrs/0009-phase-as-product-layer.md). The diagram below shows the brief → intent → spec flow into delivered reality, with the phase as the audit target of delivered reality; the phase layer is explained in full after it. diff --git a/.abcd/development/brief/06-delivery/03-out-of-scope.md b/.abcd/development/brief/06-delivery/03-out-of-scope.md index 48717f3d7..9f2550df7 100644 --- a/.abcd/development/brief/06-delivery/03-out-of-scope.md +++ b/.abcd/development/brief/06-delivery/03-out-of-scope.md @@ -89,7 +89,6 @@ gate. That is what keeps "not hand-counted" true after the day it was written. - `itd-142` — The brief-creation interview: staged elicitation into the brief and a ledger (frontier rounds, options at conjectural questions, hold register, two-output rule per adr-50); spec waits on the collaborating prototype's first run - `itd-143` — The framing chapter under 01-product/: the macro-why home, with its brief↔lifeboat mapping row; receives itd-142's committed framing products - `itd-144` — Every livery mark has a surface: the lifeboat on disembark and mirrored on embark, the duckling as the harness mascot, the flag icon for the website (settles itd-112's deferred forge/web logo question) -- `itd-146` — abcd's help renders in labelled command groups, gated by a group field in the surface snapshot and an ungrouped-verb test (the reframed survivor of the verb-taxonomy ideate verdict; no verb renamed, moved or hidden) - `itd-149` — abcd handles inbound security advisories and issues, and cuts the release, for every managed repo (the 2026-08-27 pilot's loop automated; findings F-A…F-W are the acceptance-criteria source, F-U and F-Q load-bearing; filed after the itd-84 SPLIT, awaiting the planning interview) - `itd-163` — Reference-closure and acknowledgements-mirror gate: every citation resolves to the CSL references, the references and acknowledgements mirror both ways, and a committed influence registry backs the Inspirations list (supersedes itd-145; filed from the 2026-08-28 attribution review with the backfill issue iss-2608280824478819) - `itd-164` — Licence vetting at source admission: `docs cite refresh` records each source's licence verdict into the committed baseline, and the zero-network gate refuses a new entry without one (builds on itd-163) @@ -107,7 +106,6 @@ gate. That is what keeps "not hand-counted" true after the day it was written. - `itd-175` — The product thinker writes down how this could be wrong, and what would show it (Phase 8; the defeater list an acceptance rests on) - `itd-176` — Whatever ships says how hard anyone looked at it (Phase 7) - `itd-201` — every question abcd's agents put to a human is asked one at a time, in plain language, in the addressee's register, with options that widen -- `itd-2609061543533170` — one verb sets up a managed repository's release-rendered site end to end: the site composition, the wrangler configuration, the render-then-deploy workflow, the environments it needs, and the worker itself where a credential is held - `itd-2609151838312703` — sessions on one machine or one local network leave each other messages in a shared mailbox abcd owns (the built-in basic; nothing leaves the local network) - `itd-2609151838327688` — an opt-in adapter to a local message broker brings push delivery and cross-machine reach to the session mailbox (sequenced after the mailbox) - `itd-2609151541116052` — every question an interview puts to a human shows the thing being decided before it asks, at every step (refines itd-201) @@ -124,7 +122,6 @@ gate. That is what keeps "not hand-counted" true after the day it was written. - `itd-2609090746414083` — A lifeboat packs from a lab session home, the throwaway experiment's intention, harvest and bundle, with the same coverage honesty as a repository (refines itd-88 and adr-35; the non-git half, sequenced after the lab verb family) - `itd-2609180517121254` — every payload a host hands back from a delegated step names the model that produced it and the number of agents that ran, and the ingesting verb refuses one that does not - `itd-2609201916056194` — a delegated agent runs through a command-line model runner the operator chose (claude CLI, opencode/openrouter); the opt-in cli oracle rung -- `itd-2609211913453478` — one glossary page maps the record families (intent, spec, bundle, phase, batch, issue, roadmap, release) and how they relate, and answers whether a phase is still the sequencing layer **Later-phase items with no intent id.** These four were written into the brief diff --git a/.abcd/development/brief/glossary/README.md b/.abcd/development/brief/glossary/README.md index 828bedeb0..ce92f9f0e 100644 --- a/.abcd/development/brief/glossary/README.md +++ b/.abcd/development/brief/glossary/README.md @@ -72,20 +72,24 @@ glossary/ ├── core/ │ ├── README.md │ ├── brief.md +│ ├── bundle.md │ ├── construal.md │ ├── disembark.md │ ├── intent.md │ ├── ledger.md │ ├── lifeboat.md │ ├── loop.md +│ ├── milestone.md │ ├── oracle.md │ ├── persona.md │ ├── phase.md │ ├── plan.md │ ├── reading-position.md +│ ├── record-families.md │ ├── record.md │ ├── roadmap.md │ ├── spec.md +│ ├── step.md │ ├── surface.md │ ├── transport.md │ └── voyage.md @@ -189,20 +193,24 @@ The complete write-back protocol is a **design target** of `/abcd:intent grill`' | Term | Status | Definition | |---|---|---| | [brief](core/brief.md) | stable | The living root document that holds a project's purpose, constraints, and success criteria — always the project's current state, revised in place as the project moves. | +| [bundle](core/bundle.md) | stable | Several intents that share one spec because they ship as one change; each member carries kind bundle-member and the bundle's name, and all ship together when the spec closes. | | [construal](core/construal.md) | stable | The statement of what the situation is being treated as, in one or two sentences, held at the top of the brief's framing chapter as the frame a widening reading reads against; one of adr-55's three framing surfaces, beside the committed glossary terms and the committed scope. The ledger context's entry governs the term inside the cold-reading experiment. | | [disembark](core/disembark.md) | stable | The act of packing a lifeboat — `abcd disembark to ` reads a source repository without writing to it and distils its settled artefacts, decisions, and configuration into a portable lifeboat directory at a destination outside that repository, which a fresh context can later unpack via `/abcd:embark`. | | [intent](core/intent.md) | stable | A press-release-shaped description of a feature written before implementation begins, capturing the user problem, proposed solution, and success criteria. | | [ledger](core/ledger.md) | stable | An append-or-move store a command writes and a human reads back, the issue ledger under .abcd/work/issues/ when the word stands bare; inside the cold-reading experiment the word means the warm material and its stores, which the read-block keeps from a reading (the ledger context's entries govern that sense). Four further ledgers share the word and are always named in full. | | [lifeboat](core/lifeboat.md) | stable | A portable directory artefact packed by `/abcd:disembark` that captures the distilled knowledge and configuration of a source project so it can be unpacked into a fresh context by `/abcd:embark`. It always lands outside the source repository, at an operator-chosen destination. | | [loop](core/loop.md) | draft | The record loop — brief to intent to spec to shipped work to audited verdict and back onto the brief — which shipping closes twice, once by grading the acceptance criteria and once by rewriting the brief passage. Two other loops carry the word and are always qualified: the autonomous-run loop and the lifeboat round-trip. | +| [milestone](core/milestone.md) | superseded | A planned end condition for a stretch of work; retired: the checkpoint is the derived release plus each intent's acceptance criteria. | | [oracle](core/oracle.md) | stable | An AI model invoked to review, reason over, or validate a project's artefacts — host-delegated by default, or reached through an opt-in oracle adapter. | | [persona](core/persona.md) | stable | A placeholder stakeholder character drawn from the abcd personas registry, used in press releases, intents, and design documents to represent a real user archetype without using real names. | -| [phase](core/phase.md) | stable | An ordered stretch of development work that bundles a set of intents and brief plumbing-phases and ends in a milestone; abcd's sequencing layer, recorded as a document in roadmap/phases/. Unqualified it always carries that sense, the brief's own numbered build milestones being plumbing-phases. | +| [phase](core/phase.md) | superseded | An ordered stretch of development work that bundles a set of intents and brief plumbing-phases and ends in a milestone; abcd's sequencing layer, recorded as a document in roadmap/phases/. Unqualified it always carries that sense, the brief's own numbered build milestones being plumbing-phases. | | [plan](core/plan.md) | stable | The maintainer's sign-off act `abcd intent plan `, which mints a spec, links both sides and moves a draft intent to planned/. Three further senses share the word — the ordered build plan the phase docs hold, a dated design plan under development/plans/, and a session's planning brief — and each is qualified where it appears. | | [reading-position](core/reading-position.md) | stable | One of the four questions a cold reading can be commissioned to answer — widening, entailment, comparative or detection. The position fixes the reading's object, its question and the supply regime its output is validated against; `abcd reading assemble --position` names it. | +| [record-families](core/record-families.md) | stable | The one page that maps abcd's record families (intent, spec, step, bundle, issue, release, status) and how they relate: what each groups, what groups it, its lifecycle and the verb that moves it. | | [record](core/record.md) | stable | One identified, filed document that a command mints and a lint gate reads — an itd-N, spc-N, adr-N, iss-N or rdg-id. "The development record" is the whole durable corpus those records make up, and "a record family" is one lifecycle-bucketed set of them; each of the three is qualified where the other two could be read. | -| [roadmap](core/roadmap.md) | stable | The sequencing folder .abcd/development/roadmap/, which holds the phase docs and the RFCs. Its README is the roadmap dashboard, a separate sense — a live status render that reads the native spec store and the intent buckets rather than the phase docs. | +| [roadmap](core/roadmap.md) | superseded | The sequencing folder .abcd/development/roadmap/, which holds the phase docs and the RFCs. Its README is the roadmap dashboard, a separate sense — a live status render that reads the native spec store and the intent buckets rather than the phase docs. | | [spec](core/spec.md) | stable | A specced block of work in abcd's native spec store that implements one or more intents, broken into ordered tasks with acceptance criteria. | +| [step](core/step.md) | stable | One of the ordered, independently landable pieces a spec lists under its Steps section; each step is one lane and one pull request, and a spec with no steps is one step. | | [surface](core/surface.md) | stable | A verb's front door — the markdown command file under commands/ plus the transport package under internal/surface/ that reaches the core. "A surface chapter" is the brief's design record for one such front door, and "a rendered surface" is a public text held to the repository's identity block; both are qualified. | | [transport](core/transport.md) | stable | The mechanism by which curated context and artefacts are packaged and delivered to an oracle for review or reasoning. | | [voyage](core/voyage.md) | stable | The operations namespace at `~/.abcd/voyage//` — an append-only record of what abcd *did* to produce a lifeboat (every disembark and embark run), as against the lifeboat itself, which is what gets carried. | diff --git a/.abcd/development/brief/glossary/core/bundle.md b/.abcd/development/brief/glossary/core/bundle.md new file mode 100644 index 000000000..80f9de8e5 --- /dev/null +++ b/.abcd/development/brief/glossary/core/bundle.md @@ -0,0 +1,22 @@ +--- +term: bundle +bounded_context: core +definition: Several intents that share one spec because they ship as one change; each member carries kind bundle-member and the bundle's name, and all ship together when the spec closes. +aliases: [] +forbidden_synonyms: ["phase", "epic", "milestone"] +status: stable +introduced_in: itd-34 +starts_when: null +ends_when: null +not_to_be_confused_with: core/step +versions: null +--- + + +# bundle + +A **bundle** is a delivery grouping, not a sequencing one: two or three intents whose work is one change, planned together by `abcd intent plan itd-A itd-B --bundle ` (itd-34), sharing one spec and shipping together when it closes. A bundle says nothing about what comes before what; that is dependencies. A bundle cannot contain its own blocker. + +## When to use + +When two intents would be one pull request. Not as a phase in disguise: a bundle of ten is a sign the intents were cut wrong. diff --git a/.abcd/development/brief/glossary/core/milestone.md b/.abcd/development/brief/glossary/core/milestone.md new file mode 100644 index 000000000..6e1adc5ab --- /dev/null +++ b/.abcd/development/brief/glossary/core/milestone.md @@ -0,0 +1,18 @@ +--- +term: milestone +bounded_context: core +definition: A planned end condition for a stretch of work; retired: the checkpoint is the derived release plus each intent's acceptance criteria. +aliases: [] +forbidden_synonyms: [] +status: superseded +introduced_in: adr-9 +starts_when: null +ends_when: null +not_to_be_confused_with: core/record-families +versions: null +--- + + +# milestone + +> **Superseded on 2026-09-21 (adr-2609212115255771).** The word never had an entry of its own; it lived as a forbidden synonym of phase. Its job, a checkable end condition, is done twice over: each intent's acceptance criteria say when that work is done, and the derived release says what shipped. An intent that must land by a cut says so with `target_release` (itd-2609212103572513), which the cut reports and carries forward. See [record-families](record-families.md). diff --git a/.abcd/development/brief/glossary/core/phase.md b/.abcd/development/brief/glossary/core/phase.md index c67fe57b5..d5c31be3e 100644 --- a/.abcd/development/brief/glossary/core/phase.md +++ b/.abcd/development/brief/glossary/core/phase.md @@ -4,17 +4,20 @@ bounded_context: core definition: An ordered stretch of development work that bundles a set of intents and brief plumbing-phases and ends in a milestone; abcd's sequencing layer, recorded as a document in roadmap/phases/. Unqualified it always carries that sense, the brief's own numbered build milestones being plumbing-phases. aliases: ["roadmap phase"] forbidden_synonyms: ["version", "release", "milestone", "sprint", "iteration"] -status: stable +status: superseded introduced_in: adr-9 starts_when: null ends_when: null -not_to_be_confused_with: core/spec +not_to_be_confused_with: core/record-families versions: null --- # phase +> **Superseded on 2026-09-21 (adr-2609212115255771): the sequencing layer is dependencies plus the lifecycle shelves, rendered as the Now / Next / Later status block; the phase documents stay as history.** See [record-families](record-families.md). + + A **phase** is abcd's sequencing layer — an ordered stretch of work that ends in a **milestone** (a concrete, checkable end condition). Phases replace plugin-version language (`v1`, `v2`) as the way the project organises what ships together and in what order. Each diff --git a/.abcd/development/brief/glossary/core/record-families.md b/.abcd/development/brief/glossary/core/record-families.md new file mode 100644 index 000000000..a5790f734 --- /dev/null +++ b/.abcd/development/brief/glossary/core/record-families.md @@ -0,0 +1,36 @@ +--- +term: record-families +bounded_context: core +definition: The one page that maps abcd's record families (intent, spec, step, bundle, issue, release, status) and how they relate: what each groups, what groups it, its lifecycle and the verb that moves it. +aliases: [] +forbidden_synonyms: [] +status: stable +introduced_in: adr-2609212115255771 +starts_when: null +ends_when: null +not_to_be_confused_with: null +versions: null +--- + + +# record-families + +The families, and the two axes they sit on. + +| Family | What it is | Groups | Grouped by | Lifecycle | Moved by | +|---|---|---|---|---|---| +| **intent** | one user-facing capability, press release first | its specs | a bundle (delivery) | drafts → planned → shipped (superseded; disciplines) | `intent plan`, `spec close`, `intent reclassify` | +| **spec** | the design record for one piece of scheduled work | its steps | its intent (one or more specs per intent) | open → closed | `intent plan` mints, `spec close` | +| **step** | one landable piece of a spec | nothing | its spec | listed, landed, or carried into the remainder | `abcd build` | +| **bundle** | intents that ship as one change | intents | nothing | named at plan, ships with its spec | `intent plan --bundle` | +| **issue** | a captured finding with a remedy; no spec by design | nothing | nothing (edges: `blocked_by`) | open → resolved / wontfix | `capture`, `capture resolve`, `drain` | +| **release** | the derived cut: version from impact, changelog from records | what shipped since the last tag | nothing | cut, tagged | `launch ship` | +| **status** | Now / Next / Later, rendered from the shelves, the gate and the build's state | nothing (a view) | nothing | none: computed | nothing | + +**Two axes.** The *lifecycle* (what has been decided about a record) lives in the folders and is what the gates read. The *position* (how soon) is rendered from it as Now / Next / Later and is never stored. Sequencing is dependencies (`blocked_by`, `builds_on`) plus the shelves; nothing sits above the intent for sequence. + +**Retired**: [phase](phase.md) and [milestone](milestone.md) (2026-09-21, adr-2609212115255771), and the word roadmap; a **batch** is the autonomous run's internal order, derived from dependencies and the pick, and is not a term of the record. + +## When to use + +When unsure which word to use, or whether a new grouping deserves a name: a name that has no row here is a name nobody has justified. diff --git a/.abcd/development/brief/glossary/core/roadmap.md b/.abcd/development/brief/glossary/core/roadmap.md index 860ac2904..4a934c8ed 100644 --- a/.abcd/development/brief/glossary/core/roadmap.md +++ b/.abcd/development/brief/glossary/core/roadmap.md @@ -4,17 +4,20 @@ bounded_context: core definition: The sequencing folder .abcd/development/roadmap/, which holds the phase docs and the RFCs. Its README is the roadmap dashboard, a separate sense — a live status render that reads the native spec store and the intent buckets rather than the phase docs. aliases: ["roadmap folder"] forbidden_synonyms: ["backlog", "timeline", "release plan"] -status: stable +status: superseded introduced_in: adr-9 starts_when: null ends_when: null -not_to_be_confused_with: core/phase +not_to_be_confused_with: core/record-families versions: null --- # roadmap +> **Superseded on 2026-09-21 (adr-2609212115255771): the rendered Now / Next / Later status block on the `abcd` board and the site's Status page replaces the roadmap document and the word.** See [record-families](record-families.md). + + The **roadmap** is [`.abcd/development/roadmap/`](../../../roadmap/README.md): two things and no others — [`phases/`](../../../roadmap/phases/README.md), the ordered build plan, and `rfcs/`, where a proposal is argued before it becomes an ADR. It carries no dates and no diff --git a/.abcd/development/brief/glossary/core/step.md b/.abcd/development/brief/glossary/core/step.md new file mode 100644 index 000000000..3563b4a5a --- /dev/null +++ b/.abcd/development/brief/glossary/core/step.md @@ -0,0 +1,22 @@ +--- +term: step +bounded_context: core +definition: One of the ordered, independently landable pieces a spec lists under its Steps section; each step is one lane and one pull request, and a spec with no steps is one step. +aliases: [] +forbidden_synonyms: ["task", "sub-task", "scope"] +status: stable +introduced_in: adr-2609212115255771 +starts_when: null +ends_when: null +not_to_be_confused_with: core/spec +versions: null +--- + + +# step + +A **step** is the unit below a spec (itd-2609212103565953): the spec's author lists them in order, each with its own footprint, and `abcd build` lands them one at a time, the next starting after the previous has merged. A step that does not fit a cut leaves the rest as the spec's remainder. The loop's own step interface (`abcd implement step`) uses the same word for the same thing: the next piece of the current spec. + +## When to use + +When a spec is larger than one implementer can hold and land. Not as a task tracker: a step is a section of the design record, not a record of its own. diff --git a/.abcd/development/decisions/adrs/0009-phase-as-product-layer.md b/.abcd/development/decisions/adrs/0009-phase-as-product-layer.md index 83bb5e28e..b7b366da1 100644 --- a/.abcd/development/decisions/adrs/0009-phase-as-product-layer.md +++ b/.abcd/development/decisions/adrs/0009-phase-as-product-layer.md @@ -1,10 +1,10 @@ --- id: adr-9 slug: phase-as-product-layer -status: accepted +status: superseded date: 2026-05-16 supersedes: null -superseded_by: null +superseded_by: adr-2609212115255771 related_intents: [] related_rfcs: [] related_adrs: [adr-1, adr-5, adr-10] diff --git a/.abcd/development/decisions/adrs/2609212115255771-phases-and-milestones-are-retired-sequencing-is-dependencies.md b/.abcd/development/decisions/adrs/2609212115255771-phases-and-milestones-are-retired-sequencing-is-dependencies.md new file mode 100644 index 000000000..e589dee83 --- /dev/null +++ b/.abcd/development/decisions/adrs/2609212115255771-phases-and-milestones-are-retired-sequencing-is-dependencies.md @@ -0,0 +1,124 @@ +--- +id: adr-2609212115255771 +slug: phases-and-milestones-are-retired-sequencing-is-dependencies +status: accepted +date: 2026-09-21 +supersedes: adr-9 +superseded_by: null +related_intents: [itd-2609211913453478, itd-2609212103568351, itd-2609212103565953, itd-2609212103572513, itd-24, itd-34, itd-78] +related_rfcs: [] +related_adrs: [adr-1, adr-9, adr-45] +--- + +# ADR-2609212115255771: Phases and milestones are retired: sequencing is dependencies rendered as status, the checkpoint is the derived release + +## Context + +adr-9 (2026-05-16) made the phase the product layer between the brief and the +intent: an ordered stretch of work bundling intents, ending in a milestone, a +checkable end condition, recorded as a document under `roadmap/phases/`. Four +months on, the record shows the layer thinned to a document nobody anchors to: +no spec carries a `phase:` field (0 of 93), phase membership is recorded +editorially in the phase document, and the roadmap rule "each phase ends in a +milestone" names a unit no verb reads. Meanwhile three other groupings arrived +with verbs behind them: the bundle (several intents sharing one spec because +they ship as one change, itd-34), the derived release (the version computed +from the impact of what shipped, the changelog composed from the records), and +the autonomous run's batch. On 2026-09-21 the product thinker asked, in the +interview that planned the fourteen specless intents, whether phases survive +bundles and milestones survive releases. + +An independent research pass over the field (Shape Up, Linear, GitHub, +GitLab, SAFe, the Kanban Guide 2025, DORA, Firefox's trains, Kubernetes +enhancement proposals, Now/Next/Later roadmaps, Cagan, release-please and +changesets) found: every surviving sequencing unit is a timebox whose job is +to carry a date, which this repository's roadmap rule forbids; the undated +lineages run on priority, readiness and dependencies and name no sequencing +unit; where a planned checkpoint survives beside derived releases it collapses +into the release (Kubernetes' "milestone" is the release version, and the end +condition sits on the record as graduation criteria, the role acceptance +criteria play here); and Now/Next/Later, offered as a replacement, is already +present under the names `planned/` and `drafts/` plus priority, so adding it +as a stored unit would be a second name for one concept. + +## Decision + +We retire the phase and the milestone as units of the record, and the word +roadmap with them. + +1. **Sequencing is dependencies plus the shelves.** `blocked_by` and + `builds_on` on the records (itd-78 derives a priority from them; the pick + in `abcd build next` filters on them) and the lifecycle shelves + `drafts/ → planned/ → shipped/` carry the order. No stored unit sits above + the intent for sequence. +2. **Now / Next / Later is a rendered status, never stored.** The bare `abcd` + board and the site's Status page compute it: Now is every intent in a + lane (from the build's state file) plus the head of the pick order; Next + is every planned intent the gate reports READY; Later is the rest of + planned and the drafts. A started state comes from the state file and is + rendered (itd-2609212103568351). Nothing is called a roadmap. +3. **The checkpoint is the derived release plus each intent's acceptance + criteria.** No planned end condition exists apart from them. An intent + may carry an optional `target_release:` that the cut reports and moves + forward, never refuses on (itd-2609212103572513); that field is the one + forward-looking line the derived release keeps. +4. **The unit below a spec is the step**: an ordered `## Steps` section in + the spec, each step landable as one lane and one pull request; a spec + with no steps is one step; the loop's `implement step` and the section + share the word (itd-2609212103565953). No fourth record family. +5. **Two axes, kept apart.** The lifecycle (what has been decided about a + record) lives in the folders and gates; the position (how soon) is + rendered from it. `planned/` is not renamed Now, because sixty planned + intents are not all being worked on and the word would lie. +6. **Issues carry no spec by design.** An issue's design record is its + `remedy:` field and the failing test its lane writes first; an issue that + needs design is an intent in disguise and is promoted. +7. **The batch is the run's internal order**, derived from dependencies and + the pick, and is not a term of the record. +8. **One term per concept.** The glossary marks `phase`, `milestone` and + `roadmap` superseded with their successors named, gains `bundle` and + `step`, and one page maps the families (itd-2609211913453478). The + phase documents stay in the tree as history with a retirement line; the + ROADMAP rule domain is replaced by this decision's statement. + +## Alternatives Considered + +- **Keep phases as the sequencing document, retire milestones only.** Rejected: + the document had already drifted to editorial membership with no anchor, + the failure mode the research pass names for every hand-maintained + sequencing unit; a unit no verb reads is a unit nobody keeps current. +- **Rename the folders to now/next/later/done.** Rejected: the folders are + a lifecycle the gates read (`plan` mints the spec on entering `planned/`), + and the roadmap words are a position that changes without a decision; + conflating them would either make Now lie or move the spec mint to lane + start. +- **Now/Next/Later as a stored bucket on each record.** Rejected: a second + name for `planned/`, `drafts/` and priority; the rendered form carries the + same information and cannot drift. +- **A task record family below the spec.** Rejected in favour of a section: + a fourth family with folders and verbs adds the kind of vocabulary this + decision trims; Shape Up's scopes and Kubernetes' in-record graduation + criteria are the precedents for keeping the pieces inside the record. +- **Keep the word roadmap for the rendered view.** Rejected on the + repository's own documentation rule: a roadmap promises, this view + reports; the docs are present tense, and the status board is where a + reader already looks. + +## Consequences + +- adr-9 is superseded; the brief's mental-model chapter reads brief → intent + → spec (→ steps), with the bundle as a delivery grouping and the derived + release as the checkpoint (itd-2609211913453478 makes the edit). +- itd-24 becomes release retrospectives: the release boundary is real and + the changelog is a ready seed; itd-34 drops the rule that bundle members + share a phase. +- The run file's batches stay internal; its pull rule is priority plus + dependency-readiness plus the ceiling. +- The `target_release:` field, the `## Steps` section, the status block and + the glossary page are four intents planned on 2026-09-21 and built by the + run; until they ship the folders are the only sequencing signal, which is + the state the record was in already. +- What is lost: the phase's `## Expectation`, a working-backwards paragraph + at release granularity. Its nearest home is a release press release + composed from the shipped intents' press releases; the changelog composer + is one step from it, and that step is not ruled here. diff --git a/.abcd/development/intents/drafts/itd-2609061543533170-abcd-sets-up-a-managed-repository-s-release-rendered-site-en.md b/.abcd/development/intents/drafts/itd-2609061543533170-abcd-sets-up-a-managed-repository-s-release-rendered-site-en.md deleted file mode 100644 index a7ce71661..000000000 --- a/.abcd/development/intents/drafts/itd-2609061543533170-abcd-sets-up-a-managed-repository-s-release-rendered-site-en.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -id: itd-2609061543533170 -slug: abcd-sets-up-a-managed-repository-s-release-rendered-site-en -spec_id: null -kind: null -suggested_kind: null -reclassification_history: [] -builds_on: [itd-2609150819432059] -severity: minor -impact: additive -origin: researcher-authored -production_mode: hand-written ---- - -# abcd sets up a managed repository's release-rendered site end to end: Alice runs one verb and gets the site composition, the wrangler configuration, the site workflow on abcd's own render-then-deploy pattern, the GitHub Environments it needs, and, when abcd holds a Cloudflare credential, the Worker itself created and routed, so a landing page is live at the address she named without hand assembly - -## Press Release - -> _Seeded from a quoted-text intent capture. Expand into the full press-release narrative before planning._ - -## Why This Matters - -abcd sets up a managed repository's release-rendered site end to end: Alice runs one verb and gets the site composition, the wrangler configuration, the site workflow on abcd's own render-then-deploy pattern, the GitHub Environments it needs, and, when abcd holds a Cloudflare credential, the Worker itself created and routed, so a landing page is live at the address she named without hand assembly - -## Mechanism - -> _Prompted (the claim-recording gradient): why the authors expect this to work, as a falsifiable "we expect X because Y" — not the outcome restated. Replace this line with the claim, or with the exact token `None stated.` alone on its line to record the claim as considered and declined._ - -## Scope Conditions - -> _Required (the claim-recording gradient): the population, platform, scale, or assumptions this claim holds under, one per top-level bullet — `abcd intent plan` stamps each with a persistent identity. Replace this line with those bullets, or with the exact token `None stated.` alone on its line._ - -## 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._ - -## Open Questions - -_None recorded yet._ - -## Audit Notes - -_Empty. Populated by intent-auditor when intent moves to shipped/._ diff --git a/.abcd/development/intents/drafts/itd-2609211913453478-one-page-in-the-glossary-maps-abcd-s-record-families-and-how.md b/.abcd/development/intents/drafts/itd-2609211913453478-one-page-in-the-glossary-maps-abcd-s-record-families-and-how.md deleted file mode 100644 index a1c7849fd..000000000 --- a/.abcd/development/intents/drafts/itd-2609211913453478-one-page-in-the-glossary-maps-abcd-s-record-families-and-how.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -id: itd-2609211913453478 -slug: one-page-in-the-glossary-maps-abcd-s-record-families-and-how -spec_id: null -kind: standalone -suggested_kind: null -reclassification_history: [] -builds_on: [itd-34, itd-78] -related_intents: [itd-24, itd-42, itd-172] -severity: minor -impact: additive -origin: researcher-authored -production_mode: hand-written ---- - -# One page maps the record families and how they relate, and says whether a phase still is one - -## Press Release - -> One page in the glossary maps abcd's record families and how they relate: intent, spec, bundle, phase, batch, issue, roadmap and release each get one definition and one line saying what they group, what groups them, and which verb moves them. A product thinker reads it in five minutes and knows which word to use; bundle and batch gain entries; and the page answers whether a phase is still the sequencing layer now that bundles group intents that ship together and a run works in batches. - -## Why This Matters - -On 2026-09-21 the product thinker asked, mid-interview, whether abcd has an intent that sorts out its own vocabulary (intents, issues, phases, bundles, roadmap, specs) and how they relate, and whether phases are still wanted now that bundles exist. The answer was: a glossary exists (`.abcd/development/brief/glossary/`, with phase, intent, spec, roadmap, record and ledger defined in prose and adr-9 making the phase the product layer between the brief and the intent), but nothing draws the map, `bundle` has no entry, and the autonomous run adds a third grouping, the batch. Three ways of grouping intents is one too many for a vocabulary a product thinker is meant to hold; the evidence that phases have thinned is that no spec carries a phase anchor and phase membership is recorded editorially in the phase document. - -## Mechanism - -> _Prompted (the claim-recording gradient): why the authors expect this to work, as a falsifiable "we expect X because Y" — not the outcome restated. Replace this line with the claim, or with the exact token `None stated.` alone on its line to record the claim as considered and declined._ - -## Scope Conditions - -> _Required (the claim-recording gradient): the population, platform, scale, or assumptions this claim holds under, one per top-level bullet — `abcd intent plan` stamps each with a persistent identity. Replace this line with those bullets, or with the exact token `None stated.` alone on its line._ - -## What's In Scope - -- **One page**, `glossary/core/record-families.md` or its equivalent, with one row per family: the noun, one definition, what it groups, what groups it, its lifecycle folders, and the verb that moves it; the page is the single source the other entries point at. -- **Two new entries**: `bundle` (intents sharing one spec because they ship as one change; itd-34) and `batch` (the order an autonomous run takes lanes in; the run file). -- **The phase question, answered on the page**: whether a phase remains the sequencing layer, is folded into bundles, or is replaced by the run's batches; the answer is a decision recorded before the page ships, and the retrospective intent (itd-24) and the bundle rule in itd-34 follow it. -- **The lint**: every glossary entry's `not_to_be_confused_with` names a family on the page; a family named in a record's frontmatter that the page does not define is a finding. - -## What's Out of Scope - -- Renaming any family or any folder. -- The dependency graph between intents (itd-78). - -## 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._ - -## Open Questions - -- **Do phases stay?** Kept as the sequencing layer ending in a milestone; folded into bundles (a bundle is the only grouping, and the roadmap orders bundles); or replaced by the run's batches (the run file's routing is the roadmap). Each answer changes itd-24 and itd-34. -- **Where the page lives**: one glossary page, or the brief's mental-model chapter with the glossary pointing at it. - -## Audit Notes - -_Empty. Populated by intent-auditor when intent moves to shipped/._ diff --git a/.abcd/development/intents/drafts/itd-146-abcd-s-help-renders-in-labelled-command-groups-and-the-group.md b/.abcd/development/intents/planned/itd-146-abcd-s-help-renders-in-labelled-command-groups-and-the-group.md similarity index 72% rename from .abcd/development/intents/drafts/itd-146-abcd-s-help-renders-in-labelled-command-groups-and-the-group.md rename to .abcd/development/intents/planned/itd-146-abcd-s-help-renders-in-labelled-command-groups-and-the-group.md index 682055845..c1757048a 100644 --- a/.abcd/development/intents/drafts/itd-146-abcd-s-help-renders-in-labelled-command-groups-and-the-group.md +++ b/.abcd/development/intents/planned/itd-146-abcd-s-help-renders-in-labelled-command-groups-and-the-group.md @@ -1,8 +1,10 @@ --- id: itd-146 +related_intents: [itd-2609212130136102, itd-2609212113220149, itd-134] +related_adrs: [adr-2609212115255771] slug: abcd-s-help-renders-in-labelled-command-groups-and-the-group -spec_id: null -kind: null +spec_id: spc-2609212139586554 +kind: standalone suggested_kind: null reclassification_history: [] builds_on: [] @@ -12,6 +14,9 @@ impact: additive # abcd's help renders in labelled command groups, and the grouping is gated like every other surface claim +> **Widened on 2026-09-21** by the product thinker: the grouped list is the person's, one line above it says `--agent` expands it, and `--help --agent` renders two blocks, people then agents and hosts. The scope invariant below ("no verb hidden") stands for execution: every verb runs the same whichever block lists it. The verb consolidation is its own record (itd-2609212130136102), and the one-sentence explainer per verb another (itd-2609212113220149). + + ## Press Release > **abcd's command list reads as a map instead of an alphabet.** `abcd --help` @@ -113,15 +118,15 @@ a grouping shipped without one would repeat the defect it was chosen over. ## Scope Conditions -- Holds for a **CLI whose top level is a set of acts rather than resources**. +- Holds for a **CLI whose top level is a set of acts rather than resources**. Should abcd grow a genuine resource with several verbs that no existing verb owns, the noun-verb question reopens as a real one rather than a tidiness one. -- Holds for **cobra**. The grouping mechanism is a cobra feature, so a change of +- Holds for **cobra**. The grouping mechanism is a cobra feature, so a change of command framework re-decides this. -- Holds while **no third-party author registers verbs**. An extension ecosystem +- Holds while **no third-party author registers verbs**. An extension ecosystem would break the ungrouped-verb test, because the core cannot assign a group to a verb it does not register. -- The **group titles and membership are a presentation choice**, not a taxonomy +- The **group titles and membership are a presentation choice**, not a taxonomy claim. They carry no adr-40 bucket meaning and must not be read as one. ## SOTA @@ -148,48 +153,29 @@ Heroku-style colon topics; an extension-verb growth valve. ## Acceptance Criteria -- **Given** the rendered root help, **when** a reader runs `abcd --help`, - **then** every listed command appears beneath a group heading and none - appears under cobra's "Additional Commands" fallback. -- **Given** a visible top-level command registered with no group, **when** the - test suite runs, **then** a test fails naming that command, and a hidden - command does not trigger it. -- **Given** the committed surface snapshot, **when** it is regenerated, **then** - every visible top-level verb carries a group and every sub-command carries - none. -- **Given** a verb whose group changes without the snapshot being regenerated, - **when** the snapshot drift test runs, **then** it fails naming that verb. -- **Given** `abcd rules` and `abcd spec`, **when** a reader runs `abcd --help`, - **then** both appear under a group, and both keep their sections in - `docs/reference/cli/commands.md`. -- **Given** a surface snapshot written before this ships, **when** the release - guardrail reads it as the baseline, **then** it decodes without error and the - cut is not refused. -- **Given** the change shipping, **when** the release is derived, **then** it - derives as additive and the surface diff reports no break. +- **Given** `abcd --help`, **when** it renders, **then** the person's verbs appear under labelled groups (set-up, records, checks, portability, release), with one line above them saying `--agent` expands the list with the verbs agents and hosts call. +- **Given** `abcd --help --agent`, **when** it renders, **then** two blocks appear, the person's groups then an agents-and-hosts block, and every visible verb is in exactly one block. +- **Given** any verb, **when** it runs, **then** it runs the same whichever block lists it; a visible top-level verb registered with no group or block fails a test. +- **Given** the surface snapshot, **when** a verb's group or block changes without regeneration, **then** the release gate fails naming the verb. +- **Given** a verb's command page, **when** it is read, **then** it says which block the verb is in, and each line of the agent block names the page an agent reads next. +- **Given** `abcd rules` and `abcd spec`, **when** `--help` renders, **then** they keep their places; nothing is renamed or nested. + +## Decisions + +Ruled by the product thinker on 2026-09-21: + +1. **Two blocks behind one flag**: the default list is the person's groups with the expanding line above; `--agent` shows both blocks. Nothing is hidden from execution. +2. **Group titles**: set-up (`ahoy`, `update`), records (`capture`, `intent`, `spec`, `decide`, `build`, `drain`, `memory`), checks (`lint`), portability (`embark`, `disembark`), release (`launch`); the agent block holds `implement`, `reading`, `history`, `statusline`, `changelog`, `guard hook`, `intent audit ingest`, `ideate record`, `mode`. +3. **The snapshot's schema version bumps** for the block field; `changelog` sits in the agent block. ## Open Questions -- **The snapshot schema version.** The snapshot declares `SchemaVersion = 1` and - hard-fails decode on a mismatch, while the release guardrail reads its - baseline from the previous release tag. Bumping the version makes that - baseline undecodable; not bumping it means a version-1 baseline decodes with - an empty group everywhere. Adding the field as optional at the current - version, so an absent group is not a changed group, is the candidate that - keeps both branches working, and this needs deciding before planning. -- **Group titles and membership.** A first cut: set-up and update (`ahoy`, - `update`, `version`); records (`intent`, `ideate`, `capture`, `spec`, - `memory`, `history`); conformance (`lint`, `docs`, `guard`, `banlist`, - `identity`); portability (`disembark`, `embark`); release (`launch`, - `changelog`, `site`); operator (`rules`, `help`, `completion`). That is - twenty of twenty visible verbs plus the two generated commands. Membership is - a maintainer decision at the planning interview. -- **Whether the path-1 reading above is correct**, given that adoption adds no - dependency and the approval gate exists to weigh dependencies. -- **Whether `changelog` belongs in the release group.** Grouping it beside - `launch` gets the legibility benefit that folding it under `launch` was - rejected for, with no change to its invocation. +_None open; decisions 2 and 3 settle the four this record carried._ ## Audit Notes _Empty. Populated by intent-auditor when intent moves to shipped/._ + +## Grounds + +- pursued: the run lands build, drain, implement, reflect and reclassify, and an alphabet of forty verbs is where a newcomer gives up; we expect a person to find their verb in the grouped list and an agent to find the second block from the line above it; shown wrong if the first agent transcripts after it ships still grep the binary for verbs diff --git a/.abcd/development/intents/planned/itd-24-reflect-command.md b/.abcd/development/intents/planned/itd-24-reflect-command.md index 56b410500..f6844687d 100644 --- a/.abcd/development/intents/planned/itd-24-reflect-command.md +++ b/.abcd/development/intents/planned/itd-24-reflect-command.md @@ -17,7 +17,7 @@ builds_on: [itd-27] impact: additive --- -# Completed Phases Get A Retrospective +# Completed Releases Get A Retrospective ## Press Release @@ -86,6 +86,7 @@ Ruled by the product thinker on 2026-09-21, in the interview that gave this inte 1. **Nudge once.** When a phase's last piece of work closes, abcd says once that a retrospective is owed; it is not repeated and it is not a gate. 2. **A ranked few on embark.** Predecessor lessons most like the new voyage's brief are shown; the rest are a list opened on request. 3. **Layout.** The retrospective lives under the durable record tier, `.abcd/development/retrospectives//README.md`; the paths this record was written against predate the three-tier layout and are read as that. +4. **The unit is the release** (ruled 2026-09-21, adr-2609212115255771): phases are retired, so `` reads as the release tag (`v0.10.0`), the seed is the release's shipped intents and their audit notes with the derived changelog, the empty case is a release that shipped no intent, the nudge fires once when the cut is written, and criterion 7's warning names intents targeted at the release (`target_release`) still unshipped. Every criterion below is read with "phase" meaning "release". ## Open Questions diff --git a/.abcd/development/intents/planned/itd-2609061543533170-abcd-sets-up-a-managed-repository-s-release-rendered-site-en.md b/.abcd/development/intents/planned/itd-2609061543533170-abcd-sets-up-a-managed-repository-s-release-rendered-site-en.md new file mode 100644 index 000000000..238162b46 --- /dev/null +++ b/.abcd/development/intents/planned/itd-2609061543533170-abcd-sets-up-a-managed-repository-s-release-rendered-site-en.md @@ -0,0 +1,80 @@ +--- +id: itd-2609061543533170 +slug: abcd-sets-up-a-managed-repository-s-release-rendered-site-en +spec_id: spc-2609212141407459 +kind: standalone +suggested_kind: null +reclassification_history: [] +builds_on: [itd-2609212103568351] +severity: minor +impact: additive +origin: researcher-authored +production_mode: hand-written +related_intents: [itd-100, itd-131] +related_adrs: [adr-2609212115255771] +--- + +# One verb takes a managed repository's site from the checkout to a live address + +## Press Release + +> **One verb sets up a managed repository's site end to end, and the same pages abcd's own site has render from that repository's record.** +> +> "The explorer, the graph, the timeline: I had them for abcd and wanted them for every repository abcd manages," said a product thinker looking at the record browser. "Now one verb writes the workflow and the environments, and when I have given abcd a hosting credential it creates and routes the host too. Any managed repo's site looks like abcd's, with its own record in it." + +## Why This Matters + +The renderer already exists: `abcd site build` composes the landing page from the identity block and the record export into the explorer, record pages, the relationship graph, the timeline and the glossary, and it is how abcd's own site is made. What no record covered was the distance from the verb to a live address for a repository abcd manages. Ruled 2026-09-21: everything, when a credential is present; the provider behind an adapter seam; the pages the same set for every repository, switched off per repository, never on to something extra. + +## Mechanism + +We expect a managed repository whose site is live to be read by people who never open the tree, because the record is written to be read and a checkout is where nobody reads it; shown wrong if no managed repository's site gains a reader within a release of it shipping. + +## Scope Conditions + +- Holds for a repository abcd manages whose forge runs the release workflow abcd scaffolds; a forge without workflows is out of reach. +- Holds where the hosting provider has an API the adapter can create and route through; a provider without one is the person's step. + +## What's In Scope + +- **`abcd site setup`**: writes the site composition from the identity block and the record, the render-on-release-then-deploy workflow and the environments it needs, and prints the exact remaining step for the person. +- **The credentialled path**: with a hosting credential configured, the same verb creates and routes the host through the provider adapter and reports the live address; without one it stops at the step above and says so. +- **The provider seam**: one adapter ships (the provider abcd's own site uses); a second is a later intent, not a change to the verb. +- **The pages**: landing, explorer, record pages, graph, timeline, glossary and status render for every managed repository from its own text; the site configuration switches pages off. +- **Re-runnable and credential-clean**: a second run changes nothing current and says so; no credential is ever written into the repository. +- **Security review** before the lane ships. + +## What's Out of Scope + +- A second provider. +- Custom pages beyond the set. +- Any change to the renderer's page shapes. + +## Decisions + +Ruled by the product thinker on 2026-09-21, in the interview that filed and planned this intent (adr-2609212115255771 records the vocabulary rulings it rests on): + +1. Everything when a credential is present; the person's step otherwise (ruled 2026-09-21). +2. The provider is an adapter behind a seam, one shipped. +3. The same pages for every repository, opt-out per page. + +## Open Questions + +_None open._ + +## Acceptance Criteria + +- **Given** a managed repository, **when** `abcd site setup` runs without a hosting credential, **then** the composition, the render-then-deploy workflow and the environments are written, and the exact remaining step is printed. +- **Given** a hosting credential configured, **when** the verb runs, **then** the host is created and routed through the adapter and the live address is reported; nothing is written into the repository but the files above. +- **Given** the provider seam, **when** the adapter list is read, **then** one provider is present and the seam's interface is the one a second would implement. +- **Given** any managed repository, **when** its site renders, **then** the page set is abcd's own (landing, explorer, record pages, graph, timeline, glossary, status) from that repository's text, with pages switched off per its configuration. +- **Given** a second run, **when** nothing has changed, **then** it writes nothing and says so. +- **Given** the lane, **when** it ships, **then** a security review of the workflow writes and the provider calls is on its record. + +## Audit Notes + +_Empty. Populated by intent-auditor when intent moves to shipped/._ + +## Grounds + +- pursued: the renderer is built and proved on abcd's own site; the gap is only the verb from the checkout to a live address; we expect a managed repository's site to gain readers who never open the tree; shown wrong if none does within a release diff --git a/.abcd/development/intents/planned/itd-2609211913453478-one-page-in-the-glossary-maps-abcd-s-record-families-and-how.md b/.abcd/development/intents/planned/itd-2609211913453478-one-page-in-the-glossary-maps-abcd-s-record-families-and-how.md new file mode 100644 index 000000000..7265b6054 --- /dev/null +++ b/.abcd/development/intents/planned/itd-2609211913453478-one-page-in-the-glossary-maps-abcd-s-record-families-and-how.md @@ -0,0 +1,78 @@ +--- +id: itd-2609211913453478 +slug: one-page-in-the-glossary-maps-abcd-s-record-families-and-how +spec_id: spc-2609212131112235 +kind: standalone +suggested_kind: null +reclassification_history: [] +builds_on: [itd-34, itd-2609212103565953] +related_intents: [itd-24, itd-42, itd-172, itd-78] +severity: minor +impact: additive +origin: researcher-authored +production_mode: hand-written +related_adrs: [adr-2609212115255771] +--- + +# One page maps the record families, and phase, milestone and roadmap are retired + +## Press Release + +> **One glossary page maps abcd's record families and how they relate, and three words leave the vocabulary.** +> +> "I kept asking which word to use, and every answer named a different document," said a product thinker who had just approved bundles and wondered whether phases still meant anything. "Now there is one page: intent, spec, step, bundle, issue, release, status. Phase and milestone are on it too, marked superseded, with what replaced them. I read it in five minutes." + +## Why This Matters + +On 2026-09-21 the product thinker asked, mid-interview, whether abcd has an intent that sorts out its vocabulary and whether phases survive bundles. A glossary existed with phase, intent, spec, roadmap, record and ledger defined in prose and adr-9 making the phase the product layer; nothing drew the map, `bundle` had no entry, and the autonomous run had added a third grouping, the batch. The research pass and the discussion that followed retired phase, milestone and roadmap and named their successors (adr-2609212115255771); this page is where a reader learns that. + +## Mechanism + +We expect one page that every glossary entry points at to stop new second names for one concept, because a name that must earn a row on a map is a name someone has to justify; shown wrong if a new record family or grouping word appears in the next release without a row on the page. + +## Scope Conditions + +None stated. + +## What's In Scope + +- **One page**, `glossary/core/record-families.md`: one row per family, intent, spec, step, bundle, issue, release, status (Now / Next / Later), with the definition, what it groups, what groups it, its lifecycle folders and the verb that moves it; every other glossary entry's `not_to_be_confused_with` may name only a family on the page. +- **Superseded terms**: `phase`, `milestone` and `roadmap` marked `status: superseded` with the successor named (dependencies and the status block; the derived release and each intent's criteria; the status block); the phase documents under the roadmap folder carry a retirement line and stay as history. +- **New entries**: `bundle` (itd-34) and `step` (itd-2609212103565953); `batch` defined on the page as the run's internal order, not a term. +- **The lint**: a glossary entry whose `not_to_be_confused_with` names nothing on the page is refused; a record frontmatter key naming a family the page does not define is reported. +- **The brief's mental-model chapter** reads brief → intent → spec (→ steps), with the bundle as a delivery grouping and the derived release as the checkpoint; adr-9 is superseded by adr-2609212115255771. + +## What's Out of Scope + +- Renaming any family or folder. +- The dependency graph between intents (itd-78). +- A release press release at the phase's old granularity (named in the decision record's consequences, not ruled). + +## Decisions + +Ruled by the product thinker on 2026-09-21, in the interview that filed and planned this intent (adr-2609212115255771 records the vocabulary rulings it rests on): + +1. Phases and milestones are retired; sequencing is dependencies plus the lifecycle shelves; the checkpoint is the derived release plus each intent's criteria (adr-2609212115255771). +2. Now / Next / Later is a rendered status, never stored, and the word roadmap goes with the phase documents. +3. The unit below a spec is the step, a section, not a record family; an issue carries no spec by design; the batch is the run's internal order. +4. One term per concept: the page is the map every entry points at. + +## Open Questions + +_None open._ + +## Acceptance Criteria + +- **Given** the glossary, **when** the page is read, **then** it holds one row per family (intent, spec, step, bundle, issue, release, status) with the definition, what it groups, what groups it, its lifecycle folders and the verb that moves it, and every other entry points at it. +- **Given** `phase`, `milestone` and `roadmap`, **when** their entries are read, **then** each is marked superseded with its successor named, and the phase documents carry a retirement line. +- **Given** `bundle` and `step`, **when** the glossary is read, **then** each has an entry, and `batch` is defined on the page as the run's internal order. +- **Given** an entry whose `not_to_be_confused_with` names nothing on the page, or a record frontmatter key naming a family the page does not define, **when** the record lint runs, **then** the first is refused and the second reported. +- **Given** the brief's mental-model chapter, **when** it is read, **then** it reads brief → intent → spec (→ steps) with the bundle and the derived release named, and adr-9 reads superseded by adr-2609212115255771. + +## Audit Notes + +_Empty. Populated by intent-auditor when intent moves to shipped/._ + +## Grounds + +- pursued: three terms are retired today and the map is where a reader learns what replaced them; we expect no new grouping word to appear without a row; shown wrong if one does in the next release diff --git a/.abcd/development/intents/planned/itd-2609212103565953-a-spec-lists-its-steps-and-the-build-lands-them-one-at-a.md b/.abcd/development/intents/planned/itd-2609212103565953-a-spec-lists-its-steps-and-the-build-lands-them-one-at-a.md new file mode 100644 index 000000000..4331dc98a --- /dev/null +++ b/.abcd/development/intents/planned/itd-2609212103565953-a-spec-lists-its-steps-and-the-build-lands-them-one-at-a.md @@ -0,0 +1,77 @@ +--- +id: itd-2609212103565953 +slug: a-spec-lists-its-steps-and-the-build-lands-them-one-at-a +spec_id: spc-2609212138246060 +kind: standalone +suggested_kind: null +reclassification_history: [] +builds_on: [itd-2609201916151817, itd-2609211116005482] +severity: minor +impact: additive +origin: researcher-authored +production_mode: hand-written +related_intents: [itd-2609211913453478] +related_adrs: [adr-2609212115255771] +--- + +# A spec lists its steps, and the build lands them one at a time + +## Press Release + +> **A spec lists its steps, and `abcd build` lands them one at a time, each its own lane and pull request.** +> +> "The implement verb was three lanes in the spec's order, and nothing had a word for the three," said a technical facilitator reading the run file. "Now the spec says its steps, the loop builds them in that order, and a step that does not fit the cut leaves the rest as the remainder. No new record family, no task tracker: a list in the design record." + +## Why This Matters + +The record's only unit below a spec was another spec, minted as a remainder, and the build machinery's scope condition says a lane too large for one context is split by the spec, not by the loop. The run file already split the implement verb into three lanes with no name for the pieces. The field's answers are Shape Up's scopes (pieces inside the pitch) and Kubernetes' in-record graduation; a child record family (Linear's sub-issues) adds folders and verbs the vocabulary is shedding. Ruled on 2026-09-21 (adr-2609212115255771, decision 4): a section in the spec, called steps, sharing the loop's own word. + +## Mechanism + +We expect specs split into named steps to land with fewer fix rounds and smaller lane contexts than the pilot's 349k-token lane, because a step is what one implementer can hold and land; shown wrong if stepped specs show no smaller lane contexts than unstepped ones of the same footprint. + +## Scope Conditions + +None stated. + +## What's In Scope + +- **The section**: `## Steps` in the spec, an ordered list, each step with a title and its footprint (packages, tests); the spec template seeds it empty at `intent plan`; a spec without steps is one step. +- **The loop**: `abcd build` reads the list and runs one lane per step in order, each landing as its own pull request; the next step's lane starts after the previous has merged. +- **The remainder**: a step that does not fit the cut leaves the unfinished steps in the remainder spec `spec close --remainder` mints. +- **The brief**: a lane's brief names the step it builds and the steps before it; the run record lists steps as it lists lanes. +- **One word**: `implement step` (the loop's step interface) and this section share the word, and the command page says so. + +## What's Out of Scope + +- The build proposing a split (the author writes the steps). +- A task record family. +- Reordering steps mid-run. + +## Decisions + +Ruled by the product thinker on 2026-09-21, in the interview that filed and planned this intent (adr-2609212115255771 records the vocabulary rulings it rests on): + +1. The unit below a spec is a section called steps, not a record family (adr-2609212115255771, decision 4). +2. The spec's author writes the steps; a spec without any is one step. +3. A step that does not fit the cut leaves the rest as the remainder. + +## Open Questions + +_None open._ + +## Acceptance Criteria + +- **Given** `abcd intent plan` mints a spec, **when** the stub is read, **then** it carries an empty `## Steps` section beside `## Footprint`, and a spec with no steps listed is built as one step. +- **Given** a spec with three steps, **when** `abcd build` runs it, **then** three lanes run in order, each landing as its own pull request, and the second starts only after the first has merged. +- **Given** a step that does not fit the cut, **when** the spec is closed with `--remainder`, **then** the remainder spec carries the unfinished steps. +- **Given** a lane for a step, **when** its brief is rendered, **then** it names the step and the steps before it, and the run record lists the steps. +- **Given** the command page, **when** it is read, **then** `implement step` and the spec's steps are described as one word for one thing. + +## Audit Notes + +_Empty. Populated by intent-auditor when intent moves to shipped/._ + +## Grounds + +- pursued: the run file already builds the implement verb as three lanes in the spec's order with no word for the pieces; we expect named steps to land with smaller contexts and fewer fix rounds; shown wrong if stepped specs show no smaller lane contexts diff --git a/.abcd/development/intents/planned/itd-2609212103568351-the-bare-abcd-status-board-and-the-site-s-status-page-show.md b/.abcd/development/intents/planned/itd-2609212103568351-the-bare-abcd-status-board-and-the-site-s-status-page-show.md new file mode 100644 index 000000000..466c2c717 --- /dev/null +++ b/.abcd/development/intents/planned/itd-2609212103568351-the-bare-abcd-status-board-and-the-site-s-status-page-show.md @@ -0,0 +1,78 @@ +--- +id: itd-2609212103568351 +slug: the-bare-abcd-status-board-and-the-site-s-status-page-show +spec_id: spc-2609212138241908 +kind: standalone +suggested_kind: null +reclassification_history: [] +builds_on: [itd-2609211913453478, itd-2609211116005482, itd-2609201916151817] +severity: minor +impact: additive +origin: researcher-authored +production_mode: hand-written +related_intents: [itd-100, itd-2609061543533170] +related_adrs: [adr-2609212115255771] +--- + +# The status board shows Now, Next and Later, computed from the record + +## Press Release + +> **`abcd` and the site's Status page show Now, Next and Later, computed from the record and maintained by nobody.** +> +> "The phase documents told me what someone once thought would happen next; this tells me what is next," said a product thinker reading the board after retiring phases. "Now is what is in a lane and what the run would pick; Next is what is ready; Later is the rest. Nobody edits it, so it cannot lie." + +## Why This Matters + +Phases and milestones were retired on 2026-09-21 (adr-2609212115255771) on the evidence that a hand-maintained sequencing document drifts to editorial membership nobody anchors to. The field's replacement for a dated roadmap is the Now / Next / Later view; abcd already holds its inputs in the lifecycle shelves, the readiness gate and the build's state file, so the view is a render, not a record, and it lands where a reader already looks: the bare `abcd` status board and the site. + +## Mechanism + +We expect a view computed from state to stay true where the hand-maintained phase documents drifted, because nothing on it can be edited into a lie; shown wrong if a reader finds Now naming an intent that is neither in a lane nor the pick order's head. + +## Scope Conditions + +None stated. + +## What's In Scope + +- **Now**: every intent whose lane the build's state file shows as started, with its lane state, plus the head of `build next`'s pick order marked "next up", so Now is never empty while anything is READY. +- **Next**: every planned intent the readiness gate reports READY, in pick order. +- **Later**: planned intents not READY (with the failing check named), then drafts. +- **Two surfaces, one read**: the bare `abcd` board gains the block; the site's Status page renders it from the same function; `--json` carries the three lists. +- **Nothing stored**: no folder, no field; removing the state file empties Now's lane rows and leaves the head. +- **No roadmap**: the word appears on neither surface; the glossary points `roadmap` at this block. + +## What's Out of Scope + +- A started state as a stored field (it is rendered from the state file). +- The pick itself (itd-2609211116005482). +- The site's other pages (itd-2609061543533170). + +## Decisions + +Ruled by the product thinker on 2026-09-21, in the interview that filed and planned this intent (adr-2609212115255771 records the vocabulary rulings it rests on): + +1. Now / Next / Later is rendered status, never stored (adr-2609212115255771, decision 2). +2. When nothing is being built, Now shows the pick order's head marked "next up". +3. The word roadmap is retired; this block is called status. + +## Open Questions + +_None open._ + +## Acceptance Criteria + +- **Given** an abcd-managed repository, **when** `abcd` runs bare, **then** the board carries a Now / Next / Later block: Now lists the intents the build's state file shows in a lane, with their lane state, and the pick order's head marked "next up"; Next the planned intents the gate reports READY in pick order; Later the planned intents not READY with the failing check named, then the drafts; each row its id and title. +- **Given** the site is built, **when** its Status page is read, **then** it renders the same block from the same read. +- **Given** the build's state file is absent, **when** the board renders, **then** Now holds only the pick order's head, and nothing else on the board changes. +- **Given** `--json`, **when** the board renders, **then** the payload carries the three lists with ids, titles, lane states and the failing checks. +- **Given** either surface, **when** it is searched for the word roadmap, **then** it is absent, and the glossary's `roadmap` entry names this block as its successor. + +## Audit Notes + +_Empty. Populated by intent-auditor when intent moves to shipped/._ + +## Grounds + +- pursued: phases are retired today and the record needs a place a person looks to see what is next; we expect the computed block to be read where the phase documents were not; shown wrong if Now is found naming an intent neither in a lane nor next diff --git a/.abcd/development/intents/planned/itd-2609212103572513-an-intent-names-the-release-it-must-land-by-and-the-cut-says.md b/.abcd/development/intents/planned/itd-2609212103572513-an-intent-names-the-release-it-must-land-by-and-the-cut-says.md new file mode 100644 index 000000000..5b997c5e8 --- /dev/null +++ b/.abcd/development/intents/planned/itd-2609212103572513-an-intent-names-the-release-it-must-land-by-and-the-cut-says.md @@ -0,0 +1,75 @@ +--- +id: itd-2609212103572513 +slug: an-intent-names-the-release-it-must-land-by-and-the-cut-says +spec_id: spc-2609212138243443 +kind: standalone +suggested_kind: null +reclassification_history: [] +builds_on: [itd-2609211913453478, itd-2609212103568351] +severity: minor +impact: additive +origin: researcher-authored +production_mode: hand-written +related_intents: [itd-73] +related_adrs: [adr-2609212115255771] +--- + +# An intent names the release it must land by, and the cut says whether it did + +## Press Release + +> **A planned intent may carry `target_release`; the cut reports every targeted intent still unshipped and moves its target forward.** +> +> "Milestones were the only thing that said 'this must be in the next one', and they went with the phases," said a product thinker at a cut. "Now the intent says it, the dry run lists what has not made it, and after the cut the target rolls forward on its own. It never refuses my release; it never lets me forget either." + +## Why This Matters + +The research pass of 2026-09-21 found the strongest challenge to retiring milestones: a derived release says what shipped, and nothing says what must land before the next cut. Kubernetes answers it with a milestone field on the record rather than a unit; this record is that field, ruled report-and-move-forward, never refuse (adr-2609212115255771, decision 3). + +## Mechanism + +We expect a target the cut reports and carries forward to answer "what must land" without a planned unit, because the field lives on the record that owns the work and the cut is the moment anyone reads it; shown wrong if targets are never set, or set and carried past two cuts without a word. + +## Scope Conditions + +None stated. + +## What's In Scope + +- **The field**: `target_release: vX.Y.Z` (or `next`) on a planned intent, validated as a version, written by `intent plan --target` or `intent target `; the record lint refuses it on a shipped or superseded intent. +- **The report**: `launch --dry-run` and the cut list every targeted intent not yet shipped, in text, in the receipt and in `--json`; the cut proceeds. +- **The move**: at the cut, each unshipped target is rewritten to the next version in the change that rolls the changelog, and the changelog names the move. +- **The board**: the status block marks a targeted intent with its target in Next and Later. + +## What's Out of Scope + +- A refusing gate. +- A target on an issue. +- Any date. + +## Decisions + +Ruled by the product thinker on 2026-09-21, in the interview that filed and planned this intent (adr-2609212115255771 records the vocabulary rulings it rests on): + +1. Report, never refuse (adr-2609212115255771, decision 3). +2. The target moves forward at the cut, so the field never goes stale. +3. The field is optional and lives on the intent alone. + +## Open Questions + +_None open._ + +## Acceptance Criteria + +- **Given** a planned intent, **when** `intent target v0.11.0` runs, **then** the record carries `target_release: v0.11.0`, and the same on a shipped or superseded intent is refused by the verb and by the lint. +- **Given** a targeted intent still planned, **when** `launch --dry-run` or the cut runs, **then** it is listed as targeted and unshipped in text, the receipt and `--json`, and the cut proceeds. +- **Given** the cut is written, **when** the changelog is rolled, **then** each unshipped target is rewritten to the next version in the same change and the changelog names the move. +- **Given** the status block, **when** a targeted intent is listed, **then** its row shows the target. + +## Audit Notes + +_Empty. Populated by intent-auditor when intent moves to shipped/._ + +## Grounds + +- pursued: milestones are retired today and this is the only place must-land-by survives; we expect the cut's report to be read and the moved target to be acted on; shown wrong if targets are never set or carried past two cuts unremarked diff --git a/.abcd/development/intents/planned/itd-2609212113220149-every-verb-s-help-opens-with-one-sentence-an-agent-can-act.md b/.abcd/development/intents/planned/itd-2609212113220149-every-verb-s-help-opens-with-one-sentence-an-agent-can-act.md new file mode 100644 index 000000000..e7c355c26 --- /dev/null +++ b/.abcd/development/intents/planned/itd-2609212113220149-every-verb-s-help-opens-with-one-sentence-an-agent-can-act.md @@ -0,0 +1,74 @@ +--- +id: itd-2609212113220149 +slug: every-verb-s-help-opens-with-one-sentence-an-agent-can-act +spec_id: spc-2609212139583822 +kind: standalone +suggested_kind: null +reclassification_history: [] +builds_on: [itd-146] +severity: minor +impact: additive +origin: researcher-authored +production_mode: hand-written +related_intents: [itd-172] +related_adrs: [adr-2609212115255771] +--- + +# Every verb's help opens with one sentence an agent can act on + +## Press Release + +> **Every verb's help opens with one sentence, does / writes / refuses, identical on the list, the verb's `--help` and its page.** +> +> "I read one line per verb before I decide whether to call it," said a technical facilitator watching an agent choose. "When that line says what the verb does, what it writes and when it refuses, the agent calls the right one. When it says 'manage things', it grep's the binary." + +## Why This Matters + +Fifty-three verbs and sub-verbs carry a short line today, of uneven shape, and nothing holds them to a form or keeps the three places they appear in agreement. The field's guidance for both people and agents is the same: one concise, actionable line per command, in one voice. Ruled 2026-09-21: does, writes, refuses, in that order, under the repository's writing-style guide, generated from one source. + +## Mechanism + +We expect an agent choosing a verb from its sentence to call the right one more often and to stop reading the binary for verbs, because the sentence answers the three questions an agent asks before a call; shown wrong if agent transcripts after it ships still show a verb called for what it does not do. + +## Scope Conditions + +None stated. + +## What's In Scope + +- **The form**: one sentence per verb and sub-verb naming what it does, what it writes (or "writes nothing"), and when it refuses, in that order, under `docs/reference/writing-style.md`. +- **One source**: the sentence lives in the surface manifest and is rendered onto the command list, the verb's own `--help` and its plugin page, byte-identical. +- **The test**: walks every visible verb; fails on a missing clause, a length over the declared cap, or a difference between the three places. +- **The agent block** (itd-146) shows the same sentences. +- **The lint**: the docs-lint writing-style checks run over the sentences. + +## What's Out of Scope + +- The long help body per verb. +- Examples per verb (the page's). + +## Decisions + +Ruled by the product thinker on 2026-09-21, in the interview that filed and planned this intent (adr-2609212115255771 records the vocabulary rulings it rests on): + +1. Does / writes / refuses, in that order, identical in three places, under the writing-style guide. + +## Open Questions + +_None open._ + +## Acceptance Criteria + +- **Given** any visible verb or sub-verb, **when** its sentence is read, **then** it names what the verb does, what it writes or that it writes nothing, and when it refuses, in that order, and obeys the writing-style guide. +- **Given** the command list, the verb's `--help` and its plugin page, **when** the sentence is compared across them, **then** it is byte-identical, rendered from the surface manifest. +- **Given** a verb whose sentence lacks a clause, exceeds the cap or differs between places, **when** the test runs, **then** it fails naming the verb and the defect. +- **Given** `--help --agent`, **when** the agent block renders, **then** each line is the verb's sentence. +- **Given** the docs lint, **when** it runs, **then** the sentences are checked as any page is. + +## Audit Notes + +_Empty. Populated by intent-auditor when intent moves to shipped/._ + +## Grounds + +- pursued: the run adds five verbs and the per-verb lines today are fifty-three sentences of uneven shape; we expect an agent to choose from the sentence and stop grepping the binary; shown wrong if transcripts still show a verb called for what it does not do diff --git a/.abcd/development/intents/planned/itd-2609212130136102-abcd-s-verbs-consolidate-ahoy-s-three-modes-become-flags.md b/.abcd/development/intents/planned/itd-2609212130136102-abcd-s-verbs-consolidate-ahoy-s-three-modes-become-flags.md new file mode 100644 index 000000000..db9890f0e --- /dev/null +++ b/.abcd/development/intents/planned/itd-2609212130136102-abcd-s-verbs-consolidate-ahoy-s-three-modes-become-flags.md @@ -0,0 +1,74 @@ +--- +id: itd-2609212130136102 +slug: abcd-s-verbs-consolidate-ahoy-s-three-modes-become-flags +spec_id: spc-2609212139587510 +kind: standalone +suggested_kind: null +reclassification_history: [] +builds_on: [itd-146] +severity: minor +impact: breaking +origin: researcher-authored +production_mode: hand-written +related_intents: [itd-122, itd-123, itd-124, itd-125] +related_adrs: [adr-2609212115255771] +--- + +# abcd's verbs consolidate: modes become flags and five checks become one lint + +## Press Release + +> **abcd's command list loses its modes-as-verbs and its five spellings of "check this repository", so the person's list holds about a dozen verbs.** +> +> "Twenty-four verbs, and three of them were the same check wearing different hats," said a product thinker reading `abcd --help`. "Now `lint` is the check, `ahoy` has flags instead of sub-verbs for its modes, and `--version` is where every tool keeps it. I can hold the list." + +## Why This Matters + +On 2026-09-21 the product thinker asked whether fifty-three verbs all make sense. The command-line guidelines the field converges on say: a sub-verb for a distinct action, a flag for a mode of the same action, and a top-level list a newcomer can hold. Three of `ahoy`'s sub-verbs are modes; `version` is a flag everywhere else; `intent new` is a dead alias; and `lint`, `docs lint`, `lint outbound`, `site check` and `identity render` are five spellings of one act. Together with the agent block (itd-146) the person's list falls to about fourteen. The cut is breaking, in the same major as the four rename intents already in the run. + +## Mechanism + +We expect a person to hold a list of about a dozen verbs and stop asking which of five checks to run, because the checks become one verb with targets and the modes stop looking like actions; shown wrong if the same questions recur after it ships. + +## Scope Conditions + +None stated. + +## What's In Scope + +- **Modes to flags**: `ahoy dry-run`, `ahoy identity-check`, `ahoy remote` become `ahoy --dry-run`, `--identity`, `--remote`; the old spellings answer with the new one and exit non-zero for one release. +- **`--version`** replaces `abcd version`; `version --check` becomes `update --check`; `intent new` is removed. +- **One lint with targets**: `abcd lint` (all), `lint docs`, `lint outbound`, `lint site`, `lint identity`; `docs cite` and `site build` stay, because they write. +- **The record of the move**: every moved spelling in the surface snapshot with its successor; the command pages and the brief's surface chapters say the new forms only; the release derives as breaking. +- **The count**: the person's default list (itd-146) is at most fourteen verbs after this ships. + +## What's Out of Scope + +- The people/agent split (itd-146). +- Renaming any record family verb (`capture`, `intent`, `spec`). + +## Decisions + +Ruled by the product thinker on 2026-09-21, in the interview that filed and planned this intent (adr-2609212115255771 records the vocabulary rulings it rests on): + +1. Modes to flags, `--version`, the dead alias removed, and one lint with targets, in one breaking change (ruled 2026-09-21). + +## Open Questions + +_None open._ + +## Acceptance Criteria + +- **Given** `ahoy dry-run`, `ahoy identity-check` or `ahoy remote`, **when** run after this ships, **then** each answers naming its flag form and exits non-zero, and the flag form does what the sub-verb did. +- **Given** `abcd --version`, **when** run, **then** it prints what `abcd version` printed; `abcd version` answers naming the flag; `update --check` does what `version --check` did; `intent new` is unknown. +- **Given** `abcd lint docs`, `lint outbound`, `lint site` and `lint identity`, **when** run, **then** each does what its old spelling did, `abcd lint` runs them all, and `docs cite` and `site build` are unchanged. +- **Given** the surface snapshot, **when** regenerated, **then** every moved spelling is recorded with its successor, the pages and the brief say the new forms only, and the release derives as breaking. +- **Given** `abcd --help`, **when** it renders after itd-146 and this ship, **then** the person's list counts at most fourteen verbs. + +## Audit Notes + +_Empty. Populated by intent-auditor when intent moves to shipped/._ + +## Grounds + +- pursued: batch 3 already carries four breaking renames, so this lands in the same major cut at no extra cost to adopters; we expect the person's list to be held and the which-check question to stop; shown wrong if the same questions recur diff --git a/.abcd/development/intents/planned/itd-2609212130146198-the-status-line-badge-is-true-at-every-stop-an-abcd-managed.md b/.abcd/development/intents/planned/itd-2609212130146198-the-status-line-badge-is-true-at-every-stop-an-abcd-managed.md new file mode 100644 index 000000000..af0cda148 --- /dev/null +++ b/.abcd/development/intents/planned/itd-2609212130146198-the-status-line-badge-is-true-at-every-stop-an-abcd-managed.md @@ -0,0 +1,75 @@ +--- +id: itd-2609212130146198 +slug: the-status-line-badge-is-true-at-every-stop-an-abcd-managed +spec_id: spc-2609212139593041 +kind: standalone +suggested_kind: null +reclassification_history: [] +builds_on: [itd-200] +severity: minor +impact: additive +origin: researcher-authored +production_mode: hand-written +related_intents: [itd-2609212137129937, itd-201] +related_adrs: [adr-2609212115255771] +--- + +# The status-line badge is true at every stop + +## Press Release + +> **The status-line badge always reads one of three states, a question to the human is refused until the mode is set, and the answer resets it.** +> +> "The badge was set by whichever agent remembered," said a product thinker who had watched it read managed while an agent waited on them. "Now an agent cannot ask me anything until it has said which of us it is asking, and the moment I answer the badge goes back. It is the one signal I have that something is waiting; now it is true." + +## Why This Matters + +itd-200 shipped the badge and the `mode` verb; the state is whatever the agent last set, so it lags, sticks or never changes, and two captures already sit on it (a default that reads bare "abcd"; a colour that bleeds past the badge). Ruled 2026-09-21: the verb stays the setter, because the agent knows whom it addresses; the guard enforces it; abcd resets it on the next human message. + +## Mechanism + +We expect a question refused until the mode is set, and a reset on the answer, to make the badge true at every stop, because the two moments the badge must change are the two moments the harness already sees; shown wrong if a stop is still observed with the badge reading managed. + +## Scope Conditions + +None stated. + +## What's In Scope + +- **Three states, never bare**: `abcd-managed`, `waiting on the product thinker`, `waiting on the technical facilitator`; an unmanaged repository shows nothing. +- **The guard**: a question to the human through the host's question tool is refused while the mode reads managed; the refusal names the two settings and the verb. +- **The setter**: `abcd mode product-thinker|facilitator` sets the state; the line changes on its next render. +- **The reset**: the prompt hook resets the mode to managed when the next human message arrives after a question, and says so on stderr once. +- **The paint**: the line's colour ends at the badge (closes iss-2609170709035405); the default state closes iss-2609170627427239. + +## What's Out of Scope + +- Deriving the addressee from the question's text (the agent names it). +- Any state beyond the three. + +## Decisions + +Ruled by the product thinker on 2026-09-21, in the interview that filed and planned this intent (adr-2609212115255771 records the vocabulary rulings it rests on): + +1. The verb sets the state, enforced by the guard on the question tool; the agent is reminded to choose the product thinker or the technical facilitator (ruled 2026-09-21). +2. abcd resets the mode to managed on the next human message. + +## Open Questions + +_None open._ + +## Acceptance Criteria + +- **Given** an abcd-managed repository, **when** the status line renders, **then** it reads exactly one of `abcd-managed`, `waiting on the product thinker`, `waiting on the technical facilitator`, never a bare `abcd`; an unmanaged repository shows nothing. +- **Given** the mode reads managed, **when** an agent calls the host's question tool, **then** the guard refuses the call naming the two settings and `abcd mode`. +- **Given** `abcd mode product-thinker` or `facilitator`, **when** the line next renders, **then** it shows the corresponding state. +- **Given** a question was asked and the next human message arrives, **when** the prompt hook runs, **then** the mode is reset to managed and one line on stderr says so. +- **Given** the line, **when** it renders, **then** its colour ends at the badge. + +## Audit Notes + +_Empty. Populated by intent-auditor when intent moves to shipped/._ + +## Grounds + +- pursued: the badge is how the product thinker tells an agent is waiting on them, and today it is set by memory; we expect a guarded verb and an automatic reset to make it true at every stop; shown wrong if a stop is still seen with the badge reading managed diff --git a/.abcd/development/intents/planned/itd-2609212137116617-a-new-capture-or-draft-is-matched-against-the-record-before.md b/.abcd/development/intents/planned/itd-2609212137116617-a-new-capture-or-draft-is-matched-against-the-record-before.md new file mode 100644 index 000000000..5beb057a3 --- /dev/null +++ b/.abcd/development/intents/planned/itd-2609212137116617-a-new-capture-or-draft-is-matched-against-the-record-before.md @@ -0,0 +1,76 @@ +--- +id: itd-2609212137116617 +slug: a-new-capture-or-draft-is-matched-against-the-record-before +spec_id: spc-2609212141417782 +kind: standalone +suggested_kind: null +reclassification_history: [] +builds_on: [itd-84, itd-42] +severity: minor +impact: additive +origin: researcher-authored +production_mode: hand-written +related_intents: [itd-87, itd-48] +related_adrs: [adr-2609212115255771] +--- + +# A new capture or draft is matched against the record before it is written + +## Press Release + +> **A new issue or draft is matched against the record at filing; a likely double is linked, named, and never dropped.** +> +> "I filed the same finding twice a month apart and nobody noticed until a consistency pass," said a technical facilitator. "Now the capture tells me at filing that it looks like iss-N, writes the link, and leaves it to me to confirm. Nothing is refused: a wrong match is a link I remove, not a finding I lost." + +## Why This Matters + +Three places look for a match today, none at filing: the pre-pass at planning (itd-42), the drain before it captures, and itd-87's recurrence rule after closure. The itd-84 discipline names a capture-time validator as its next rung. The research of 2026-09-21 on unattended triage is plain about the failure to avoid: a matcher that refuses is the one that loses findings silently. Ruled: file it, link it, say so. + +## Mechanism + +We expect a typed link written at filing to make doubles visible where a later triage never finds them, because the moment of filing is the only moment both records are in one hand; shown wrong if the next consistency pass still finds unlinked doubles filed after this ships. + +## Scope Conditions + +- Holds for text long enough to compare; a one-line capture below the declared minimum is filed without matching and says so. + +## What's In Scope + +- **The match**: `capture` and the quoted-text `intent` create compare the new text with every open and resolved issue and every intent's title and press release, by the term-overlap heuristic the embark ranking uses, declared a heuristic. +- **The link**: a likely match is written onto the new record as `duplicates:` (near-identical) or `refines:` (narrower), naming the candidate; the verb prints the match and the link; nothing is refused or dropped. +- **The confirmation**: a person or a later pass confirms or removes the link; a record whose link is removed is ordinary. +- **The configuration**: threshold and compared fields declared with a bundled default; below the threshold nothing is written and `--json` lists the near misses. +- **The rung**: the itd-84 discipline's capture-time validator is marked delivered by this record. + +## What's Out of Scope + +- Refusing or merging records. +- Matching across repositories. +- Semantic matching by a model (the heuristic is lexical; a host pass is a later rung). + +## Decisions + +Ruled by the product thinker on 2026-09-21, in the interview that filed and planned this intent (adr-2609212115255771 records the vocabulary rulings it rests on): + +1. File it, link it, say so; never refuse, never drop (ruled 2026-09-21). +2. A lexical heuristic, declared as one; the threshold is configuration. + +## Open Questions + +_None open._ + +## Acceptance Criteria + +- **Given** a new capture whose text overlaps an existing issue above the threshold, **when** it is filed, **then** the record is written with a `duplicates:` or `refines:` link naming the candidate, and the verb prints the match. +- **Given** a new draft intent whose text overlaps an existing intent's title or press release, **when** it is created, **then** the same link is written and printed. +- **Given** any match, **when** filing completes, **then** no record was refused or dropped; removing the link leaves an ordinary record. +- **Given** overlap below the threshold, **when** filing completes, **then** nothing is written for it and `--json` lists the near misses with their scores. +- **Given** the itd-84 discipline record, **when** it is read after this ships, **then** the capture-time validator rung reads delivered by this record. + +## Audit Notes + +_Empty. Populated by intent-auditor when intent moves to shipped/._ + +## Grounds + +- pursued: the ledger holds 480 open issues and the run and the drain will file more unattended; we expect a link at filing to make doubles visible; shown wrong if the next consistency pass still finds unlinked doubles filed after this ships diff --git a/.abcd/development/intents/planned/itd-2609212137128014-abcd-lab-mechanises-the-lab-conventions-three-hand-run.md b/.abcd/development/intents/planned/itd-2609212137128014-abcd-lab-mechanises-the-lab-conventions-three-hand-run.md new file mode 100644 index 000000000..41869a2e1 --- /dev/null +++ b/.abcd/development/intents/planned/itd-2609212137128014-abcd-lab-mechanises-the-lab-conventions-three-hand-run.md @@ -0,0 +1,78 @@ +--- +id: itd-2609212137128014 +slug: abcd-lab-mechanises-the-lab-conventions-three-hand-run +spec_id: spc-2609212141418943 +kind: standalone +suggested_kind: null +reclassification_history: [] +builds_on: [itd-22] +severity: minor +impact: additive +origin: researcher-authored +production_mode: hand-written +related_intents: [itd-75, itd-59] +related_adrs: [adr-2609212115255771] +--- + +# abcd lab mechanises the lab conventions three hand-run experiments proved + +## Press Release + +> **`abcd lab` mints, preflights, records, sweeps and harvests a lab, and the procedure the labs converged on becomes a discipline record.** +> +> "Three labs, and by the third the procedure returned SHIP with zero findings, because every amendment had been written down and the scaffolding had been rebuilt by hand each time," said a technical facilitator reading the capstone. "Now the verb builds the scaffolding, the procedure is a record, and no rule can be forgotten under pressure." + +## Why This Matters + +Between 31 August and 1 September eight labs ran under `~/.abcd/lab/`, three of them the core series; the capstone's series review shows review churn falling from four rounds with three application failures to one round to SHIP as the procedure accumulated amendments, and a draft intent for the verb family was written as evidence and never filed. The recording model (evidence at operator level, knowledge through ceremony, pointers in the local tier) held across the runs. Ruled 2026-09-21: file it from the capstone's text; the four product findings the series left unfiled are captured on the same branch. + +## Mechanism + +We expect a mechanised lab to reproduce the third lab's SHIP on its first run, because the variable that moved across the series was the procedure and the procedure is what the verb encodes; shown wrong if a lab run under the verb needs more review rounds than lab 3 did. + +## Scope Conditions + +- Holds on a machine whose lab store is `~/.abcd/lab/` keyed as the other machine-scoped stores are; the repository never holds lab evidence. +- Holds while a real-session smoke stage is available: offline suites passed while the plugin was unloadable by the host. + +## What's In Scope + +- **The verb family** `abcd lab mint | preflight | record | sweep | harvest`: the home minted with its registry entry and snapshot pin; the preflight artefact (harness isolation, dual-binary vintage); probe-record scaffolding; the retraction sweep (grep the pattern, not the instance); harvest assembly against the lifeboat's section shape. +- **The procedure as a discipline record**: the amendments across the three chains, present tense, host-agnostic. +- **The recording model** as the recorded convention: evidence at `~/.abcd/lab/`, knowledge through ceremony, pointers in the local tier; the never-in-repo rules. +- **Halt-and-record on a gate refusal** as a lab rule the verb enforces. +- **No cost claim**: the series could not measure token cost; the verb records what the runner reports and claims nothing more. + +## What's Out of Scope + +- Auto-merge for lab filings. +- Labs as a grouping of the record. +- A next-labs runner; the menu stays a note. + +## Decisions + +Ruled by the product thinker on 2026-09-21, in the interview that filed and planned this intent (adr-2609212115255771 records the vocabulary rulings it rests on): + +1. Filed from the capstone's draft with its ten evidence items (ruled 2026-09-21). +2. Auto-merge for lab-derived work stays out; a lab's findings are captured and drained like any other. + +## Open Questions + +_None open._ + +## Acceptance Criteria + +- **Given** `abcd lab mint `, **when** it runs, **then** a lab home exists under the machine-scoped lab store with a registry entry, the snapshot pin and the lifecycle's sections scaffolded, and nothing is written into the repository. +- **Given** `abcd lab preflight`, **when** it runs, **then** the harness-isolation and dual-binary checks are written as an artefact, and a failed check halts the lab naming it. +- **Given** a lab's corrections, **when** `abcd lab sweep` runs, **then** every instance of a retracted pattern is listed and an unapplied correction fails the sweep. +- **Given** a finished lab, **when** `abcd lab harvest` runs, **then** the harvest is assembled in the lifeboat's section shape with the probe records cited, and its product findings are listed as capture candidates. +- **Given** a gate refusal during a lab, **when** it occurs, **then** the lab halts and records it as a finding rather than adapting around it. +- **Given** the discipline record, **when** it is read, **then** it carries the procedure's amendments in present tense, host-agnostic. + +## Audit Notes + +_Empty. Populated by intent-auditor when intent moves to shipped/._ + +## Grounds + +- pursued: three hand-run labs proved the procedure and paid for its scaffolding three times; we expect the verb to reproduce lab 3's SHIP on the first mechanised run; shown wrong if it needs more review rounds than lab 3 did diff --git a/.abcd/development/intents/planned/itd-2609212137129937-abcd-s-own-text-names-the-product-thinker-or-the-technical.md b/.abcd/development/intents/planned/itd-2609212137129937-abcd-s-own-text-names-the-product-thinker-or-the-technical.md new file mode 100644 index 000000000..f4f30602d --- /dev/null +++ b/.abcd/development/intents/planned/itd-2609212137129937-abcd-s-own-text-names-the-product-thinker-or-the-technical.md @@ -0,0 +1,75 @@ +--- +id: itd-2609212137129937 +slug: abcd-s-own-text-names-the-product-thinker-or-the-technical +spec_id: spc-2609212141412864 +kind: standalone +suggested_kind: null +reclassification_history: [] +builds_on: [itd-2609212130146198, itd-201] +severity: minor +impact: additive +origin: researcher-authored +production_mode: hand-written +related_intents: [itd-97, itd-174, itd-2609211913453478] +related_adrs: [adr-2609212115255771] +--- + +# abcd's text names the product thinker or the technical facilitator, never the maintainer + +## Press Release + +> **Every place abcd writes names which of the two people it means, and the word maintainer leaves the vocabulary.** +> +> "Agents kept asking 'the maintainer' and I never knew if they meant me deciding what to build or me running the gates," said a product thinker. "They learned the word from abcd's own pages. Now the pages say which of us, the badge says which of us, and the word cannot come back." + +## Why This Matters + +On 2026-09-21 the product thinker noted that agents blur the two roles under one word. The word is abcd's: twelve occurrences in the command pages agents read, twenty-two in the brief, five in the principles, one in the bundled rules and one in this repository's rule overrides ("a planned intent's adoption is a maintainer decision"), and a persona hint. Ruled: everywhere abcd writes, each use rewritten to the role it meant, and a lint from then on. The sweep is the run's, not this session's. + +## Mechanism + +We expect agents to stop saying maintainer once no abcd text says it, because agents say what they read; shown wrong if transcripts after the sweep still use the word for either role. + +## Scope Conditions + +None stated. + +## What's In Scope + +- **The sweep**: every occurrence in the command pages, the bundled and repository rules, the brief, the principles, the docs, the personas registry and abcd's rendered text rewritten to the product thinker (what to build, adoption, rulings) or the technical facilitator (how, gates, mechanics); one change, each rewrite reviewed. +- **The lint**: the docs-lint banned-token list gains the word for every lint root including the command pages and the rules; the acknowledgements and a persona's outside job title are the only escapes, marked. +- **The questions**: every question or stop abcd's agents put to a human names which role it asks (the GRILL rule made mechanical where the page templates carry the question). +- **The glossary**: the two roles defined beside the record-families page, citing itd-97's stance that the facilitator is a mode. +- **The test**: walks the rendered help and the plugin pages for the word. + +## What's Out of Scope + +- Defining a third role. +- Changing what either role decides (itd-174, itd-97). + +## Decisions + +Ruled by the product thinker on 2026-09-21, in the interview that filed and planned this intent (adr-2609212115255771 records the vocabulary rulings it rests on): + +1. Everywhere abcd writes, each use names the role it meant; a lint bans the word after (ruled 2026-09-21). +2. Captured for the run to build; no sweep in the session that ruled it. + +## Open Questions + +_None open._ + +## Acceptance Criteria + +- **Given** the command pages, the rules, the brief, the principles, the docs and the personas, **when** the sweep lands, **then** no occurrence of the word remains outside the marked escapes, and each rewrite names the product thinker or the technical facilitator. +- **Given** a new page or rule carrying the word, **when** the docs lint runs, **then** it is refused as a banned token on every lint root. +- **Given** a question or stop an agent puts to a human through the page templates, **when** it renders, **then** it names which of the two roles it asks. +- **Given** the glossary, **when** the two roles are looked up, **then** each has an entry beside the record-families page citing itd-97. +- **Given** the rendered help and the plugin pages, **when** the test runs, **then** it fails on the word. + +## Audit Notes + +_Empty. Populated by intent-auditor when intent moves to shipped/._ + +## Grounds + +- pursued: the badge intent and every interview today turn on which of two people is being asked, and the pages that brief agents blur them; we expect agents to stop saying maintainer once no abcd text says it; shown wrong if transcripts after the sweep still use the word diff --git a/.abcd/development/intents/planned/itd-34-three-intent-kinds.md b/.abcd/development/intents/planned/itd-34-three-intent-kinds.md index 70ed32464..4ac24c66c 100644 --- a/.abcd/development/intents/planned/itd-34-three-intent-kinds.md +++ b/.abcd/development/intents/planned/itd-34-three-intent-kinds.md @@ -142,7 +142,7 @@ None stated. ## Acceptance Criteria -- **Given** two draft intents, **when** `abcd intent plan itd-A itd-B` runs, **then** it asks for a bundle name, mints one shared spec naming both, writes `kind: bundle-member` and `bundle: ` on each, and moves both to `planned/` together; two drafts scoped to different phases are refused naming both phases, and nothing moves. +- **Given** two draft intents, **when** `abcd intent plan itd-A itd-B` runs, **then** it asks for a bundle name, mints one shared spec naming both, writes `kind: bundle-member` and `bundle: ` on each, and moves both to `planned/` together; a draft that names the other in `blocked_by` is refused naming the edge (a bundle cannot contain its own blocker), and nothing moves. - **Given** a bundle's shared spec is closed, **when** the close-hook runs, **then** every member with that `bundle:` ships together. - **Given** `abcd intent reclassify --kind ` or `--kind superseded --by --reason "…"`, **when** it runs, **then** the record's kind, shelf and links change in one write, with `superseded_by` on the record and `supersedes` on the successor written together; a shipped intent asked to become a discipline is refused and told to file a discipline that supersedes it. - **Given** one member of a bundle is superseded, **when** the reclassify completes, **then** the surviving member stays `bundle-member` and its record states that the bundle now has one member. @@ -163,6 +163,7 @@ Ruled by the product thinker on 2026-09-21, in the interview that gave this inte 2. **You name the bundle**; the command asks for a short name. 3. **A survivor stays.** When one member is superseded the other stays a bundle-member of a bundle of one, and says so. 4. **A shipped intent never changes kind.** A rule discovered after the fact is filed as a discipline that supersedes it. +5. **No phase rule** (ruled 2026-09-21, adr-2609212115255771): phases are retired, so the same-phase invariant this record carried is replaced by the blocker check above. ## Open Questions diff --git a/.abcd/development/research/notes/2026-08-15-decomposition-calibration.md b/.abcd/development/research/notes/2026-08-15-decomposition-calibration.md index 9ed93b440..0b37fd4fd 100644 --- a/.abcd/development/research/notes/2026-08-15-decomposition-calibration.md +++ b/.abcd/development/research/notes/2026-08-15-decomposition-calibration.md @@ -1925,3 +1925,43 @@ Per hand-run, append: batch 0 hunts for among READY intents and cannot reach among specless ones; iss-2609211738504433 records the gap. Fourteen records took three hours of the human's time at one question per turn. + +### Run: the vocabulary rulings and eight new records (2026-09-21, evening, product thinker's interview) + +- **Proposal (as received, in turns):** "do we need new intents for what we + just decided?"; then CLI discoverability for humans and agents; the help + sentence per verb; whether 53 verbs all make sense; the website for any + managed repo; the status-line badge; doubles at filing; the abcd labs; + never "the maintainer". +- **Table (as run):** + + | Part | Type | Home | Link | + | --- | --- | --- | --- | + | Retire phase, milestone, roadmap; two axes; issues have no spec; batch is internal | decision | adr-2609212115255771 supersedes adr-9 | reverses (confirmed) | + | The map page, the glossary entries, the lint | capability | itd-2609211913453478 (planned) | builds_on itd-34 | + | Now / Next / Later status block | capability | new itd-2609212103568351 | builds_on the map, the pick | + | Steps below a spec | capability | new itd-2609212103565953 | builds_on the build machinery | + | target_release | capability | new itd-2609212103572513 | builds_on the map | + | Grouped help, agents block | capability | itd-146 widened and planned | related consolidation, sentence | + | One sentence per verb | capability | new itd-2609212113220149 | builds_on itd-146 | + | Verb consolidation | capability, breaking | new itd-2609212130136102 | related the four renames | + | The badge guarded and reset | capability | new itd-2609212130146198 | builds_on itd-200 | + | One verb to a live site | capability | itd-2609061543533170 written and planned | builds_on the status block | + | Doubles linked at filing | capability | new itd-2609212137116617 | builds_on itd-84, itd-42 | + | Never "the maintainer" | capability + lint | new itd-2609212137129937 (captured for the run, no sweep) | builds_on the badge | + | abcd lab | capability | new itd-2609212137128014 from the capstone draft | builds_on itd-22 | + | Four lab findings | issues | two captured (guard workdir; short banlist fragment), two already fixed | | + +- **Verdict:** SPLIT throughout; one reversal (adr-9) confirmed by the + human at the question, not inferred. +- **Routing survived?** Two moves against the first table: Now/Next/Later + was first offered as a roadmap bucket and became a status block on the + research pass's own challenge (a second name for the shelves); the badge + was first offered as event-derived and the human ruled verb-set, + guard-enforced, hook-reset. Steps were offered three ways and named by + the human for the loop's word. +- **Notes:** every ruling was taken one question at a time; where the + human answered with a clarification rather than an option, the + clarification was taken as the answer and read back. The maintainer + sweep is the first record of the day captured explicitly *not* to be + fixed in the session that ruled it. diff --git a/.abcd/development/research/notes/2026-08-22-ideate-cli-verb-taxonomy-restructure.md b/.abcd/development/research/notes/2026-08-22-ideate-cli-verb-taxonomy-restructure.md index fa0500f50..6724238e9 100644 --- a/.abcd/development/research/notes/2026-08-22-ideate-cli-verb-taxonomy-restructure.md +++ b/.abcd/development/research/notes/2026-08-22-ideate-cli-verb-taxonomy-restructure.md @@ -96,7 +96,7 @@ authorship — the evaluator-outside-the-loop principle applied to ideas. The idea as posed does not survive, but the reframing recorded above does. Any graduation to a draft intent carries the reframing, not the -original wording. It graduated as [itd-146](../../intents/drafts/itd-146-abcd-s-help-renders-in-labelled-command-groups-and-the-group.md). +original wording. It graduated as [itd-146](../../intents/planned/itd-146-abcd-s-help-renders-in-labelled-command-groups-and-the-group.md). ### The reframing, stated diff --git a/.abcd/development/roadmap/README.md b/.abcd/development/roadmap/README.md index 90dfdd055..23c0defc6 100644 --- a/.abcd/development/roadmap/README.md +++ b/.abcd/development/roadmap/README.md @@ -69,6 +69,9 @@ native spec store via the Go CLI; never transcribe it here. ```sh # Live count per lifecycle bucket. + +> **Retired on 2026-09-21** (adr-2609212115255771): phases and milestones are no longer units of the record. Sequencing is dependencies plus the lifecycle shelves, rendered as the Now / Next / Later status block; the checkpoint is the derived release. The documents below stay as history and are not maintained. + for b in drafts planned shipped disciplines superseded; do printf '%-12s %s\n' "$b" \ "$(ls .abcd/development/intents/$b/itd-*.md 2>/dev/null | wc -l)" diff --git a/.abcd/development/roadmap/phases/README.md b/.abcd/development/roadmap/phases/README.md index 86cb5094e..ae1c846ce 100644 --- a/.abcd/development/roadmap/phases/README.md +++ b/.abcd/development/roadmap/phases/README.md @@ -1,3 +1,5 @@ +> **Retired on 2026-09-21** (adr-2609212115255771): phases and milestones are no longer units of the record. Sequencing is dependencies plus the lifecycle shelves, rendered as the Now / Next / Later status block; the checkpoint is the derived release. The documents below stay as history and are not maintained. + # abcd Phases The **phase** is abcd's sequencing layer — an ordered stretch of work that ends diff --git a/.abcd/development/specs/open/spc-2609211751376504-reflect-command.md b/.abcd/development/specs/open/spc-2609211751376504-reflect-command.md index 9239a9f2d..50b94137d 100644 --- a/.abcd/development/specs/open/spc-2609211751376504-reflect-command.md +++ b/.abcd/development/specs/open/spc-2609211751376504-reflect-command.md @@ -9,6 +9,8 @@ production_mode: hand-written ## Summary +**Re-read on 2026-09-21 (adr-2609212115255771): the unit is the release, not the phase.** Wherever this spec says phase document, read the release tag and the changelog section the cut composed; the seed is the intents whose `shipped_in` names the release, with their audit notes; the nudge is one line at the end of `launch ship`; the open-work warning names intents with `target_release` at that version still unshipped; the output path is `.abcd/development/retrospectives//README.md`. + The design record for itd-24, from the product thinker's interview of 2026-09-21 (decisions 1 to 3 on the intent). One host-run interview, `/abcd:reflect `, seeded from what the phase actually shipped, diff --git a/.abcd/development/specs/open/spc-2609211859391533-three-intent-kinds.md b/.abcd/development/specs/open/spc-2609211859391533-three-intent-kinds.md index 02acbc98f..ded5d3bd8 100644 --- a/.abcd/development/specs/open/spc-2609211859391533-three-intent-kinds.md +++ b/.abcd/development/specs/open/spc-2609211859391533-three-intent-kinds.md @@ -18,7 +18,7 @@ already exist and are read, not built. 1. **The bundle command**: `abcd intent plan itd-A itd-B [itd-C…]` takes `--bundle ` (asked for by the plugin page, refused absent on the - CLI), refuses members scoped to different phases naming both, mints ONE + CLI), refuses a member that names another in `blocked_by`, naming the edge, mints ONE spec whose frontmatter lists every intent (`intents: [itd-A, itd-B]` beside the existing `intent:` key naming the first), stamps `kind: bundle-member` and `bundle: ` on each, links each `spec_id`, diff --git a/.abcd/development/specs/open/spc-2609212131112235-one-page-in-the-glossary-maps-abcd-s-record-families-and-how.md b/.abcd/development/specs/open/spc-2609212131112235-one-page-in-the-glossary-maps-abcd-s-record-families-and-how.md new file mode 100644 index 000000000..382de70fb --- /dev/null +++ b/.abcd/development/specs/open/spc-2609212131112235-one-page-in-the-glossary-maps-abcd-s-record-families-and-how.md @@ -0,0 +1,43 @@ +--- +id: spc-2609212131112235 +slug: one-page-in-the-glossary-maps-abcd-s-record-families-and-how +intent: itd-2609211913453478 +origin: researcher-authored +production_mode: hand-written +--- +# one-page-in-the-glossary-maps-abcd-s-record-families-and-how + +## Summary + +The design record for itd-2609211913453478: the record-families page, the three retirements and the lint, from the vocabulary rulings of 2026-09-21 (adr-2609212115255771). + +## Scope + +1. **The page** `glossary/core/record-families.md`, a table with the seven families and a prose paragraph per axis (lifecycle; position); `glossary/core/README.md` indexes it first (criterion 1). +2. **Superseded entries**: `phase.md`, `roadmap.md` set `status: superseded`, `superseded_by` naming the page and the successor; a `milestone.md` entry is added in the superseded state, since the word had only lived as a forbidden synonym; `roadmap/README.md` and `roadmap/phases/README.md` open with the retirement line (criterion 2). +3. **New entries** `bundle.md`, `step.md` from the template, `status: stable`; the page's batch row (criterion 3). +4. **The lint**: `glossary_terms` gains the two checks beside the existing entry-shape check (criterion 4). +5. **The brief**: `01-product/03-mental-model.md` rewritten to the three layers plus steps, bundle and release; the surface chapters that say "phase" repointed (criterion 5). + +## Out of scope + +- Renames; itd-78; the release press release. + +## Approach + +Prose and one lint rule; the lint reads the page's table as the closed set of families. The retirement lines are one sentence each pointing at the decision record. + +## Footprint + +- packages: internal/core/lint (glossary_terms), .abcd/development/brief/glossary, .abcd/development/brief/01-product +- tests: the two lint checks over fixtures; the page's table parsed; the superseded entries' status + +## How the criteria are satisfied + +| Criterion | Where | +| --- | --- | +| 1 the page | scope 1 | +| 2 superseded with successors | scope 2 | +| 3 bundle, step, batch | scope 3 | +| 4 the lint | scope 4 | +| 5 the brief and adr-9 | scope 5 | diff --git a/.abcd/development/specs/open/spc-2609212138241908-the-bare-abcd-status-board-and-the-site-s-status-page-show.md b/.abcd/development/specs/open/spc-2609212138241908-the-bare-abcd-status-board-and-the-site-s-status-page-show.md new file mode 100644 index 000000000..1521d1099 --- /dev/null +++ b/.abcd/development/specs/open/spc-2609212138241908-the-bare-abcd-status-board-and-the-site-s-status-page-show.md @@ -0,0 +1,43 @@ +--- +id: spc-2609212138241908 +slug: the-bare-abcd-status-board-and-the-site-s-status-page-show +intent: itd-2609212103568351 +origin: researcher-authored +production_mode: hand-written +--- +# the-bare-abcd-status-board-and-the-site-s-status-page-show + +## Summary + +The design record for itd-2609212103568351: the Now / Next / Later block on the status board and the site, rendered from the lifecycle shelves, the readiness gate and the build's state file. + +## Scope + +1. **The read** (`internal/core/positioning/status.go`): the planned and draft shelves, `intent.Readiness` per planned record, the build's state file for lanes, and `implement.PickOrder` for the head (criteria 1, 3). +2. **The board block**: rendered after the existing board sections, text and `--json` (criteria 1, 4). +3. **The site page**: `internal/core/site` gains `status.go` calling the same function; the page is opt-in per the site configuration like the others (criterion 2). +4. **No write**: the function is pure over its reads (criterion 3). +5. **The word**: a test greps both renders for "roadmap" (criterion 5). + +## Out of scope + +- A stored started state; the pick; other site pages. + +## Approach + +One function in positioning, two renderers; the pick-order head is read through the same entry point `build next` uses so the two never disagree. + +## Footprint + +- packages: internal/core/positioning, internal/core/site, internal/surface/cli +- tests: the block over a fixture store with and without a state file; the json shape; the site page; the roadmap grep + +## How the criteria are satisfied + +| Criterion | Where | +| --- | --- | +| 1 the block | scope 1, 2 | +| 2 the site page | scope 3 | +| 3 no state file | scope 1, 4 | +| 4 json | scope 2 | +| 5 no roadmap | scope 5 | diff --git a/.abcd/development/specs/open/spc-2609212138243443-an-intent-names-the-release-it-must-land-by-and-the-cut-says.md b/.abcd/development/specs/open/spc-2609212138243443-an-intent-names-the-release-it-must-land-by-and-the-cut-says.md new file mode 100644 index 000000000..496c2e865 --- /dev/null +++ b/.abcd/development/specs/open/spc-2609212138243443-an-intent-names-the-release-it-must-land-by-and-the-cut-says.md @@ -0,0 +1,41 @@ +--- +id: spc-2609212138243443 +slug: an-intent-names-the-release-it-must-land-by-and-the-cut-says +intent: itd-2609212103572513 +origin: researcher-authored +production_mode: hand-written +--- +# an-intent-names-the-release-it-must-land-by-and-the-cut-says + +## Summary + +The design record for itd-2609212103572513: the `target_release` field, its verbs, the cut's report and the move forward. + +## Scope + +1. **The field and verbs**: `intent target` and `plan --target` in `internal/core/intent`, version-validated through the release package's parser; lint row in `record_schema` (criterion 1). +2. **The report**: `launch.DryRun` and `launch.Ship` read planned intents with a target and list those not in `shipped/` (criterion 2). +3. **The move**: the ship path rewrites each listed target to the derived next version in the receipts commit and appends a changelog line (criterion 3). +4. **The board**: the status block reads the field (criterion 4). + +## Out of scope + +- Refusal; issues; dates. + +## Approach + +Small: one frontmatter key, two verbs, one read in launch, one write at the cut; the move is part of the receipts commit so a cut is one change. + +## Footprint + +- packages: internal/core/intent, internal/core/launch, internal/core/positioning +- tests: the verbs and refusals; the dry-run list; the move at a fake cut; the board row + +## How the criteria are satisfied + +| Criterion | Where | +| --- | --- | +| 1 field and refusals | scope 1 | +| 2 report, cut proceeds | scope 2 | +| 3 move forward | scope 3 | +| 4 board | scope 4 | diff --git a/.abcd/development/specs/open/spc-2609212138246060-a-spec-lists-its-steps-and-the-build-lands-them-one-at-a.md b/.abcd/development/specs/open/spc-2609212138246060-a-spec-lists-its-steps-and-the-build-lands-them-one-at-a.md new file mode 100644 index 000000000..17a929b40 --- /dev/null +++ b/.abcd/development/specs/open/spc-2609212138246060-a-spec-lists-its-steps-and-the-build-lands-them-one-at-a.md @@ -0,0 +1,44 @@ +--- +id: spc-2609212138246060 +slug: a-spec-lists-its-steps-and-the-build-lands-them-one-at-a +intent: itd-2609212103565953 +origin: researcher-authored +production_mode: hand-written +--- +# a-spec-lists-its-steps-and-the-build-lands-them-one-at-a + +## Summary + +The design record for itd-2609212103565953: the `## Steps` section and the loop's per-step lanes. + +## Scope + +1. **The template**: `## Steps` seeded empty by `intent plan`; the readiness gate reports the section's shape (a list or empty) as advisory (criterion 1). +2. **The parser**: `spec.Steps(spec)` returns the ordered list with footprints, or one implicit step (criterion 1). +3. **The loop**: the lane in the state file gains `step: n/N`; `implement` starts the next step's lane only when the previous lane's pull request is an ancestor of the default branch (criterion 2). +4. **The remainder**: `spec close --remainder` copies steps not marked landed into the new spec (criterion 3). +5. **Briefs and the run record**: the brief renderer prints the step and its predecessors; the record lists `step` per lane (criterion 4). +6. **The page**: `commands/intent.md` and the build page say the word once for both (criterion 5). + +## Out of scope + +- The build proposing a split; a task family; reordering mid-run. + +## Approach + +A parser in the spec store, a counter in the state file, one branch in the loop's advance; the first spec to carry steps is the implement spec itself, whose three pieces become its `## Steps`. + +## Footprint + +- packages: internal/core/spec, internal/core/implement, internal/surface/cli +- tests: the parser over a stepped and an unstepped spec; the loop advancing only after merge with a fake forge; the remainder copy; the brief + +## How the criteria are satisfied + +| Criterion | Where | +| --- | --- | +| 1 template and one implicit step | scope 1, 2 | +| 2 lanes in order | scope 3 | +| 3 remainder carries steps | scope 4 | +| 4 briefs and record | scope 5 | +| 5 one word | scope 6 | diff --git a/.abcd/development/specs/open/spc-2609212139583822-every-verb-s-help-opens-with-one-sentence-an-agent-can-act.md b/.abcd/development/specs/open/spc-2609212139583822-every-verb-s-help-opens-with-one-sentence-an-agent-can-act.md new file mode 100644 index 000000000..30e7d7dc2 --- /dev/null +++ b/.abcd/development/specs/open/spc-2609212139583822-every-verb-s-help-opens-with-one-sentence-an-agent-can-act.md @@ -0,0 +1,43 @@ +--- +id: spc-2609212139583822 +slug: every-verb-s-help-opens-with-one-sentence-an-agent-can-act +intent: itd-2609212113220149 +origin: researcher-authored +production_mode: hand-written +--- +# every-verb-s-help-opens-with-one-sentence-an-agent-can-act + +## Summary + +The design record for itd-2609212113220149: one actionable sentence per verb from one source, held by a test. + +## Scope + +1. **The manifest** gains `sentence` per command; the CLI's `Short` and the pages' first line are generated from it (criterion 2). +2. **The form check**: a test parses each sentence into the three clauses by its declared separators (a colon after the doing clause; a semicolon before the refusing clause), enforces the cap (declared, 160 characters), and diffs the three renders (criteria 1, 3). +3. **The sweep**: fifty-three sentences rewritten to the form in one change, reviewed (criterion 1). +4. **The agent block** renders the same field (criterion 4). +5. **docs lint** includes the manifest's sentences as a lint root (criterion 5). + +## Out of scope + +- Long help; examples. + +## Approach + +The surface manifest is already the generated source of the pages and the snapshot; the sentence is one more generated field with a form test beside the snapshot test. + +## Footprint + +- packages: internal/core/surface, internal/surface/cli, commands/ +- tests: the three-way diff; the clause parser on good and bad sentences; the docs-lint root + +## How the criteria are satisfied + +| Criterion | Where | +| --- | --- | +| 1 the form | scope 2, 3 | +| 2 identical from one source | scope 1 | +| 3 the test | scope 2 | +| 4 agent block | scope 4 | +| 5 docs lint | scope 5 | diff --git a/.abcd/development/specs/open/spc-2609212139586554-abcd-s-help-renders-in-labelled-command-groups-and-the-group.md b/.abcd/development/specs/open/spc-2609212139586554-abcd-s-help-renders-in-labelled-command-groups-and-the-group.md new file mode 100644 index 000000000..261e70c24 --- /dev/null +++ b/.abcd/development/specs/open/spc-2609212139586554-abcd-s-help-renders-in-labelled-command-groups-and-the-group.md @@ -0,0 +1,44 @@ +--- +id: spc-2609212139586554 +slug: abcd-s-help-renders-in-labelled-command-groups-and-the-group +intent: itd-146 +origin: researcher-authored +production_mode: hand-written +--- +# abcd-s-help-renders-in-labelled-command-groups-and-the-group + +## Summary + +The design record for itd-146 as widened on 2026-09-21: grouped help for people, an agents-and-hosts block behind `--agent`, the snapshot recording both. + +## Scope + +1. **Groups and blocks** on the cobra root: `AddGroup` per group, a `block` annotation per command (`people` default, `agents` where decision 2 says), the help template rendering the person's groups and the expanding line by default and both blocks with `--agent` (criteria 1, 2). +2. **Execution unchanged**: no `Hidden`; a test registers a verb with no group and asserts failure (criterion 3). +3. **The snapshot**: `group` and `block` fields, schema version bumped, the regeneration gate (criterion 4). +4. **The pages**: each `commands/*.md` frontmatter gains `block:`; the agent block's help lines print the page path (criterion 5). +5. **Places kept**: `rules`, `spec` untouched (criterion 6). + +## Out of scope + +- Renames and merges (itd-2609212130136102); the sentence per verb (itd-2609212113220149). + +## Approach + +Cobra's group support plus one annotation and a custom help template; the surface manifest generator already walks the command tree and gains two fields. + +## Footprint + +- packages: internal/surface/cli, internal/core/surface +- tests: the rendered help with and without --agent; the no-group failure; the snapshot diff gate; the page frontmatter check + +## How the criteria are satisfied + +| Criterion | Where | +| --- | --- | +| 1 grouped list and the line | scope 1 | +| 2 two blocks | scope 1 | +| 3 runs the same; no-group fails | scope 2 | +| 4 snapshot | scope 3 | +| 5 pages | scope 4 | +| 6 places kept | scope 5 | diff --git a/.abcd/development/specs/open/spc-2609212139587510-abcd-s-verbs-consolidate-ahoy-s-three-modes-become-flags.md b/.abcd/development/specs/open/spc-2609212139587510-abcd-s-verbs-consolidate-ahoy-s-three-modes-become-flags.md new file mode 100644 index 000000000..568f2d933 --- /dev/null +++ b/.abcd/development/specs/open/spc-2609212139587510-abcd-s-verbs-consolidate-ahoy-s-three-modes-become-flags.md @@ -0,0 +1,43 @@ +--- +id: spc-2609212139587510 +slug: abcd-s-verbs-consolidate-ahoy-s-three-modes-become-flags +intent: itd-2609212130136102 +origin: researcher-authored +production_mode: hand-written +--- +# abcd-s-verbs-consolidate-ahoy-s-three-modes-become-flags + +## Summary + +The design record for itd-2609212130136102: the verb consolidation, one breaking change beside the four renames. + +## Scope + +1. **Flags on `ahoy`** with the three sub-verbs kept one release as deprecated stubs that print the flag form and exit 2 (criterion 1). +2. **`--version`** on the root; `update --check`; `intent new` deleted (criterion 2). +3. **`lint` targets**: `lint` gains sub-verbs `docs`, `outbound`, `site`, `identity` that call the existing functions; the old verbs become stubs for one release; `docs` keeps `cite`, `site` keeps `build` (criterion 3). +4. **The snapshot** gains `moved_to` per stub; pages and brief chapters regenerated and edited; the intent's `impact: breaking` derives the cut (criterion 4). +5. **The count test** over the rendered default help (criterion 5). + +## Out of scope + +- The agent block; record-family verbs. + +## Approach + +Stubs for one release keep muscle memory from failing silently; the release after removes them (a follow-on remainder spec, minted at close). + +## Footprint + +- packages: internal/surface/cli, internal/core/surface, commands/, .abcd/development/brief/04-surfaces +- tests: each stub's message and exit; each flag and target's behaviour equal to the old verb; the snapshot's moved_to; the count + +## How the criteria are satisfied + +| Criterion | Where | +| --- | --- | +| 1 ahoy flags | scope 1 | +| 2 --version, update --check, no intent new | scope 2 | +| 3 one lint | scope 3 | +| 4 snapshot, pages, breaking | scope 4 | +| 5 fourteen at most | scope 5 | diff --git a/.abcd/development/specs/open/spc-2609212139593041-the-status-line-badge-is-true-at-every-stop-an-abcd-managed.md b/.abcd/development/specs/open/spc-2609212139593041-the-status-line-badge-is-true-at-every-stop-an-abcd-managed.md new file mode 100644 index 000000000..db0835b99 --- /dev/null +++ b/.abcd/development/specs/open/spc-2609212139593041-the-status-line-badge-is-true-at-every-stop-an-abcd-managed.md @@ -0,0 +1,43 @@ +--- +id: spc-2609212139593041 +slug: the-status-line-badge-is-true-at-every-stop-an-abcd-managed +intent: itd-2609212130146198 +origin: researcher-authored +production_mode: hand-written +--- +# the-status-line-badge-is-true-at-every-stop-an-abcd-managed + +## Summary + +The design record for itd-2609212130146198: the badge's three states, the guard on the question tool, the setter and the reset. + +## Scope + +1. **States**: the statusline renderer maps mode file values to the three labels and refuses to print a bare tag (criterion 1). +2. **The guard**: `abcd guard hook` on the host's question tool (PreToolUse on the question tool's name) reads the mode file; managed → exit 2 with the two settings named (criterion 2). +3. **The setter**: unchanged `mode` verb (criterion 3). +4. **The reset**: the UserPromptSubmit hook (the rules loader's) reads a `question_open` marker the guard writes when it admits a question, resets the mode to managed, clears the marker, prints one stderr line (criterion 4). +5. **The paint**: the ANSI reset after the badge (criterion 5). + +## Out of scope + +- Deriving the addressee; other states. + +## Approach + +Two hooks that already run gain one read each; the marker is a file in the local tier; both captures resolve in the lane. + +## Footprint + +- packages: internal/core/mode, internal/core/guard, internal/core/statusline, hooks/ +- tests: the three renders; the guard's refusal and admission; the reset on the next prompt with the marker; the paint + +## How the criteria are satisfied + +| Criterion | Where | +| --- | --- | +| 1 three states | scope 1 | +| 2 guard refuses | scope 2 | +| 3 setter | scope 3 | +| 4 reset | scope 4 | +| 5 paint | scope 5 | diff --git a/.abcd/development/specs/open/spc-2609212141407459-abcd-sets-up-a-managed-repository-s-release-rendered-site-en.md b/.abcd/development/specs/open/spc-2609212141407459-abcd-sets-up-a-managed-repository-s-release-rendered-site-en.md new file mode 100644 index 000000000..76adc6873 --- /dev/null +++ b/.abcd/development/specs/open/spc-2609212141407459-abcd-sets-up-a-managed-repository-s-release-rendered-site-en.md @@ -0,0 +1,43 @@ +--- +id: spc-2609212141407459 +slug: abcd-sets-up-a-managed-repository-s-release-rendered-site-en +intent: itd-2609061543533170 +origin: researcher-authored +production_mode: hand-written +--- +# abcd-sets-up-a-managed-repository-s-release-rendered-site-en + +## Summary + +The design record for itd-2609061543533170: `site setup`, the provider adapter and the page set. + +## Scope + +1. **The verb** (`internal/core/site/setup.go`): composition, workflow (render on release, deploy from the artefact), environments via the forge's API, idempotent writes with a diff report (criteria 1, 5). +2. **The adapter** (`internal/adapter/hosting/`): create, route, report; credential read from the machine's abcd configuration, never the repository (criteria 2, 3). +3. **The pages**: the site package's page list becomes the closed set with per-page switches in the site configuration (criterion 4). +4. **Review**: security reviewer on the lane (criterion 6). + +## Out of scope + +- A second provider; custom pages; renderer changes. + +## Approach + +The verb reuses the launch scaffold's workflow writer and the ahoy remote check; the adapter is the second under `internal/adapter/` beside gitleaks and follows its shape. + +## Footprint + +- packages: internal/core/site, internal/adapter/hosting, internal/core/launch +- tests: the writes against a fixture repo; the adapter against a fake provider; the page switches; idempotence + +## How the criteria are satisfied + +| Criterion | Where | +| --- | --- | +| 1 setup without credential | scope 1 | +| 2 credentialled path | scope 2 | +| 3 the seam | scope 2 | +| 4 the page set | scope 3 | +| 5 re-runnable | scope 1 | +| 6 security review | scope 4 | diff --git a/.abcd/development/specs/open/spc-2609212141412864-abcd-s-own-text-names-the-product-thinker-or-the-technical.md b/.abcd/development/specs/open/spc-2609212141412864-abcd-s-own-text-names-the-product-thinker-or-the-technical.md new file mode 100644 index 000000000..5dab32366 --- /dev/null +++ b/.abcd/development/specs/open/spc-2609212141412864-abcd-s-own-text-names-the-product-thinker-or-the-technical.md @@ -0,0 +1,43 @@ +--- +id: spc-2609212141412864 +slug: abcd-s-own-text-names-the-product-thinker-or-the-technical +intent: itd-2609212137129937 +origin: researcher-authored +production_mode: hand-written +--- +# abcd-s-own-text-names-the-product-thinker-or-the-technical + +## Summary + +The design record for itd-2609212137129937: the sweep, the lint, the question templates and the glossary entries. + +## Scope + +1. **The lint first**: `maintainer` added to the docs-lint banned tokens with roots widened to `commands/`, `.abcd/rules.json` and the bundled rules source; escapes marked with the existing allow comment (criterion 2). +2. **The sweep**: forty-plus rewrites, each to the role the sentence meant, in one reviewed change; the persona hint becomes "open-source project lead" (criterion 1). +3. **The templates**: the plugin pages' question blocks name the addressee from the mode (criterion 3). +4. **The glossary**: `product-thinker.md`, `technical-facilitator.md` (criterion 4). +5. **The test** over rendered help and pages (criterion 5). + +## Out of scope + +- A third role; role responsibilities. + +## Approach + +Lint before sweep so the sweep is watched red then green; the rewrite table is reviewed by the record-discipline reviewer since each sentence's meaning decides the role. + +## Footprint + +- packages: internal/core/lint (docs), commands/, .abcd/development/brief, .abcd/development/principles, .abcd/rules.json, internal/core/rules +- tests: the banned token on each root; the escape; the help and page grep + +## How the criteria are satisfied + +| Criterion | Where | +| --- | --- | +| 1 the sweep | scope 2 | +| 2 the lint | scope 1 | +| 3 the questions | scope 3 | +| 4 the glossary | scope 4 | +| 5 the test | scope 5 | diff --git a/.abcd/development/specs/open/spc-2609212141417782-a-new-capture-or-draft-is-matched-against-the-record-before.md b/.abcd/development/specs/open/spc-2609212141417782-a-new-capture-or-draft-is-matched-against-the-record-before.md new file mode 100644 index 000000000..0151e1a1a --- /dev/null +++ b/.abcd/development/specs/open/spc-2609212141417782-a-new-capture-or-draft-is-matched-against-the-record-before.md @@ -0,0 +1,42 @@ +--- +id: spc-2609212141417782 +slug: a-new-capture-or-draft-is-matched-against-the-record-before +intent: itd-2609212137116617 +origin: researcher-authored +production_mode: hand-written +--- +# a-new-capture-or-draft-is-matched-against-the-record-before + +## Summary + +The design record for itd-2609212137116617: lexical matching at filing, a typed link, never a refusal. + +## Scope + +1. **The matcher** (`internal/core/record/match.go`): tokenises the new text and each candidate's title, press release or body, scores overlap, returns candidates above and below the threshold (criteria 1, 2, 4). +2. **The writers**: `capture` and `intent` create call it before the write and add the link field; the print (criteria 1, 2, 3). +3. **Configuration**: `match.threshold`, `match.fields` through the layered resolver (criterion 4). +4. **The discipline record** itd-84 edited to mark the rung (criterion 5). + +## Out of scope + +- Refusal; cross-repository; semantic matching. + +## Approach + +The overlap function is the one the embark ranking uses, moved to the record package as the canonical primitive; both callers run it under their existing locks. + +## Footprint + +- packages: internal/core/record, internal/core/capture, internal/core/intent +- tests: the scorer on fixtures; both writers with a planted double; the below-threshold json; the discipline edit + +## How the criteria are satisfied + +| Criterion | Where | +| --- | --- | +| 1 capture links | scope 1, 2 | +| 2 intent links | scope 1, 2 | +| 3 never refused | scope 2 | +| 4 threshold and json | scope 1, 3 | +| 5 itd-84 rung | scope 4 | diff --git a/.abcd/development/specs/open/spc-2609212141418943-abcd-lab-mechanises-the-lab-conventions-three-hand-run.md b/.abcd/development/specs/open/spc-2609212141418943-abcd-lab-mechanises-the-lab-conventions-three-hand-run.md new file mode 100644 index 000000000..4d25c27bf --- /dev/null +++ b/.abcd/development/specs/open/spc-2609212141418943-abcd-lab-mechanises-the-lab-conventions-three-hand-run.md @@ -0,0 +1,43 @@ +--- +id: spc-2609212141418943 +slug: abcd-lab-mechanises-the-lab-conventions-three-hand-run +intent: itd-2609212137128014 +origin: researcher-authored +production_mode: hand-written +--- +# abcd-lab-mechanises-the-lab-conventions-three-hand-run + +## Summary + +The design record for itd-2609212137128014: the `abcd lab` verb family, the procedure record and the recording model, from the capstone under the machine-scoped lab store. + +## Scope + +1. **The store**: `~/.abcd/lab//` with `index.jsonl`, keyed as the worktree and transcript stores are (criterion 1). +2. **mint / preflight / record / sweep / harvest** in `internal/core/lab`, each writing only under the lab home (criteria 1 to 4). +3. **The discipline record** under `intents/disciplines/`, from the capstone's amendment list (criterion 6). +4. **Halt-and-record**: the preflight and the sweep exit non-zero and write the finding (criterion 5). + +## Out of scope + +- Auto-merge; labs as a grouping; a next-labs runner. + +## Approach + +The capstone documents are the source: `series-review.md` for the procedure, `recording-model.md` for the store's shape, the harvests for the harvest template. The verb writes nothing into a repository; its output enters the record only through `capture`. + +## Footprint + +- packages: internal/core/lab, internal/surface/cli, .abcd/development/intents/disciplines +- tests: each verb over a fixture lab home; the sweep on a planted unapplied correction; the harvest shape + +## How the criteria are satisfied + +| Criterion | Where | +| --- | --- | +| 1 mint | scope 1, 2 | +| 2 preflight halts | scope 2, 4 | +| 3 sweep | scope 2 | +| 4 harvest | scope 2 | +| 5 halt-and-record | scope 4 | +| 6 discipline record | scope 3 | diff --git a/.abcd/rules.json b/.abcd/rules.json index 34b834713..e45580acd 100644 --- a/.abcd/rules.json +++ b/.abcd/rules.json @@ -102,7 +102,13 @@ "version" ], "rules": [ - "In a source checkout of abcd itself, every abcd invocation is `go run ./cmd/abcd ` from the repo root — never the plugin-root binary and never an `abcd` on PATH. Both are the last PUBLISHED version, stale by construction here and further behind with every commit, and the failure is often silent rather than a refusal: an empty `changelog --json` cut, a record written through a schema the gates no longer accept. The documented resolution ladder reaches the plugin-root binary first and it answers, so the `go run` fallback is never reached by following it; go straight to `go run ./cmd/abcd` (AGENTS.md, Build, test, and checks)." + "In a source checkout of abcd itself, every abcd invocation is `go run ./cmd/abcd ` from the repo root \u2014 never the plugin-root binary and never an `abcd` on PATH. Both are the last PUBLISHED version, stale by construction here and further behind with every commit, and the failure is often silent rather than a refusal: an empty `changelog --json` cut, a record written through a schema the gates no longer accept. The documented resolution ladder reaches the plugin-root binary first and it answers, so the `go run` fallback is never reached by following it; go straight to `go run ./cmd/abcd` (AGENTS.md, Build, test, and checks)." + ] + }, + "ROADMAP": { + "rules": [ + "Phases and milestones are retired (adr-2609212115255771): sequencing is dependencies (blocked_by, builds_on) plus the lifecycle shelves, rendered as the Now / Next / Later status block; the checkpoint is the derived release plus each intent's acceptance criteria; an intent that must land by a cut carries target_release, which the cut reports and moves forward.", + "No time estimates and no roadmap document: the press-release intent format carries priority; the word roadmap is retired and the phase documents under roadmap/ are history." ] } }, diff --git a/.abcd/work/DECISIONS.md b/.abcd/work/DECISIONS.md index 79ff477ec..da90881ed 100644 --- a/.abcd/work/DECISIONS.md +++ b/.abcd/work/DECISIONS.md @@ -2499,3 +2499,4 @@ together (the script's header says why there is no escape hatch). - 2026-09-15 — The roles and loopback design workstream lands on main, executing the 2026-09-01 ruling that the branch waits for the mint verb and takes its ids at the merge. `abcd decide` now exists, so the two decisions the branch numbered 0055 and 0056 are re-minted as adr-2609151528057260 (three roles, who each artefact addresses, and when the loop stops) and adr-2609151528057131 (abcd owns the product thinker's surface), content, status and date unchanged; every citation that meant the roles decisions is re-pointed (rfc-3, the phase-8 page, the roles page, the out-of-scope list, three intent drafts, and iss-168, whose 29 August extension cited them by the colliding numbers), and main's own 0055 and 0056 keep their ids. The branch's twelve hand-numbered intent drafts (itd-165 to itd-176) collide with nothing and keep their ids, as adr-45's grandfathering allows. Occasion: itd-200 shipped today refining the two roles decisions, so their citations on main pointed at the wrong records until this landed. - 2026-09-15 — GHSA-4q78-ccfv-f374 (iss-2609012039102770) is closed by OPTION B, ruled by the maintainer at an interactive question: bind the cache to a record the environment does not choose alone. The owned PATH-copy promotion re-verified the cache only against the `binary-meta` beside it, and `CLAUDE_PLUGIN_DATA` is taken from the environment as given, so whoever chose the directory wrote both the bytes and the record that "verified" them — reproduced at v0.7.0 as a one-byte file installed 0755 as `~/.local/bin/abcd` with provenance recorded. Now the bootstrap, the one process holding the harness's real data dir that has just established manifest trust for the cache (an authenticated cache hit, or a fresh download verified against the same-origin manifest), writes `~/.abcd/cache-attestation` — `data_dir`, the manifest-authenticated `binary_sha256`, `cache_trust=manifest`, `attested_at`; 0600, temp-and-rename, beside `path-entry` — and `ahoy install` promotes a cache only when that record names the directory, the co-located record carries the attested hash, and the artefact hashes to it, whichever route (environment or the root's `.data-dir` stamp) named the directory; detection offers the heal on the same predicate. An offline run neither writes nor rewrites the attestation, so a cache provisioned offline waits for a networked session before it reaches PATH, said out loud. Why B: the trust floor moves from a value the environment supplies to a write into the caller's own home, which adr-46 decision 4 already treats as the ownership root, so the attestation grants nothing that authority did not hold and costs `ahoy install` no network (adr-38 stands). Rejected: A (a manifest GET on a disk-only verb, re-fetching what the session already proved); C (a documented residual — weaker than it reads, since a harness honouring a committed settings file's environment block lets a hostile checkout set the variable, and the owned-copy claim is what the hook shims trust); the mechanical partial of cross-checking against the plugin-root binary (breaks dogfood installs whose root binary is a local build); and a terminal rung through the attestation alone (it would heal a dogfood checkout's stable symlink into a release copy). adr-46 is superseded by adr-2609151706587280 (never amended, always superseded; retained because its numbered decisions are cited), spc-35 Design 2 step 1 and Design 3 are revised in place and dated, and brief invariant 12 gains the clause. - 2026-09-09 — The headline product is settled (maintainer, closing the press release's "Product framing after adr-35" open question, both halves). abcd helps a product thinker realise an intent as a high-fidelity prototype or demonstrator, carrying the why from idea to shipped reality: the identity block's story, the one the README strapline and the roles page already tell and the one the roles and product-thinker-surface decisions on the design branch (numbered 0055 and 0056 there, re-minted at merge) are built on. The lifeboat is a key capability of that product rather than its headline, and its widening from whole repositories to a single feature, a lab session or an abandoned worktree enters the press release under the not-yet-real marker, as intention rather than commitment. `disembark probe` is a user-facing command and keeps its place in the press release's scope list. Rejected: the rescue story as headline (it would re-pin the identity block and every surface held to it); adr-35's "read any repository for its theory" as headline (it is the probe's own promise, now one capability among the surfaces); deferring (the audit of the press release against delivered reality had been blocked on this question since adr-35). +- 2026-09-21 — Phases and milestones are retired, and the word roadmap with them (product thinker, at an interactive interview after an independent research pass; adr-2609212115255771 supersedes adr-9). Sequencing is dependencies plus the lifecycle shelves, rendered as a Now / Next / Later status block on the `abcd` board and the site (itd-2609212103568351), never stored; the checkpoint is the derived release plus each intent's acceptance criteria, with an optional `target_release` the cut reports and moves forward (itd-2609212103572513); the unit below a spec is the step, a section not a family (itd-2609212103565953); an issue carries no spec by design; the batch is the run's internal order; one page maps the families (itd-2609211913453478). itd-24 becomes release retrospectives; itd-34 drops its phase rule. Same interview: `build` is the verb a person types and `implement` the loop (itd-2609201916151817 decision 8), the loop takes an issue key (decision 10), only the loop writes a verdict (decision 9); the person's command list is grouped with an agents block behind `--agent` (itd-146), every verb opens with a does/writes/refuses sentence (itd-2609212113220149), modes become flags and five checks one lint (itd-2609212130136102, breaking); the status-line badge is guarded and reset (itd-2609212130146198); a new capture or draft is matched and linked at filing, never refused (itd-2609212137116617); abcd's text names the product thinker or the technical facilitator and never the maintainer (itd-2609212137129937, captured for the run, no sweep today); the lab conventions become `abcd lab` (itd-2609212137128014); a managed repository's site goes live by one verb behind a provider seam (itd-2609061543533170). diff --git a/.abcd/work/issues/open/iss-2609212142557657-the-guard-payload-omits-a-per-call-working-directory-so-a-command-moved-into-it-slips-the-match.md b/.abcd/work/issues/open/iss-2609212142557657-the-guard-payload-omits-a-per-call-working-directory-so-a-command-moved-into-it-slips-the-match.md new file mode 100644 index 000000000..5ef03caad --- /dev/null +++ b/.abcd/work/issues/open/iss-2609212142557657-the-guard-payload-omits-a-per-call-working-directory-so-a-command-moved-into-it-slips-the-match.md @@ -0,0 +1,14 @@ +--- +schema_version: 1 +id: "iss-2609212142557657" +slug: "the-guard-payload-omits-a-per-call-working-directory-so-a-command-moved-into-it-slips-the-match" +severity: "minor" +category: "security" +source: "agent-finding" +found_during: "abcd lab 2 (lab-260831162806-976575f), filed from the capstone handoff on 2026-09-21 after verification at main" +origin: researcher-authored +production_mode: hand-written +found_at: "internal/surface/cli/guard.go (guardHookInput reads cwd and tool_input.command only)" +--- + +The guard's hook payload omits a per-call working directory, so a command moved into it slips the command-string match. guardHookInput reads the session cwd and tool_input.command and nothing else; a host whose shell tool takes a per-call working-directory field (opencode's does; a future Claude Code field would) can carry a destructive command whose target is the directory rather than an argument, and the match over argv sees nothing hazardous. Live-demonstrated in lab 2's smoke (probe p5b-live-session-retest under the lab home): the model set the tool's workdir and ran the bare destructive verb. Verified at main on 2026-09-21: the struct is unchanged. Decision owed to the product thinker: extend the guard contract to read a working-directory field where the host supplies one and resolve the command against it, or document the reach in adr-42's mistake-filter scope as outside the boundary. Not a security boundary by adr-42's own statement, which is why the severity is minor; the category is security because the slip is the shape a mistake filter exists to catch. diff --git a/.abcd/work/issues/open/iss-2609212142568782-the-private-banlist-accepts-a-fragment-shorter-than-a-word-and-nothing-warns-that-it-will-match-names.md b/.abcd/work/issues/open/iss-2609212142568782-the-private-banlist-accepts-a-fragment-shorter-than-a-word-and-nothing-warns-that-it-will-match-names.md new file mode 100644 index 000000000..a1a5f0af1 --- /dev/null +++ b/.abcd/work/issues/open/iss-2609212142568782-the-private-banlist-accepts-a-fragment-shorter-than-a-word-and-nothing-warns-that-it-will-match-names.md @@ -0,0 +1,14 @@ +--- +schema_version: 1 +id: "iss-2609212142568782" +slug: "the-private-banlist-accepts-a-fragment-shorter-than-a-word-and-nothing-warns-that-it-will-match-names" +severity: "minor" +category: "ux" +source: "agent-finding" +found_during: "abcd lab 3 (lab-260831163412-c3e59af), filed from the capstone handoff on 2026-09-21" +origin: researcher-authored +production_mode: hand-written +found_at: "internal/core/banlist (add path); the private tier's pattern validation" +--- + +The private banlist accepts a fragment shorter than a word and nothing warns that it will match names. A five-character fragment in the operator-tier private list matched a cited author's first name, so the guard refused a design branch's merge on one machine until the pattern was refined by hand; the store took the fragment without comment. The pattern itself is private and stays out of the record. Wanted: banlist add warns on a pattern below a declared length or without a word boundary, names the risk (it will match inside ordinary words and names), and takes an explicit flag to keep it; the guard's refusal on a private-tier hit names the pattern's length class so the operator knows where to look.