diff --git a/.abcd/development/brief/01-product/01-press-release.md b/.abcd/development/brief/01-product/01-press-release.md index cff0b5fa..52d7638f 100644 --- a/.abcd/development/brief/01-product/01-press-release.md +++ b/.abcd/development/brief/01-product/01-press-release.md @@ -16,7 +16,7 @@ Long-running projects accumulate context that doesn't live in any one file: why - **Unpack the lifeboat:** `/abcd:embark from ` reads the lifeboat, runs a press-release interview to confirm the framing with the user, scaffolds the new repo at canonical locations, and writes provenance so the rebuild knows where it came from. The literal string `home` resolves to the current repo's `.abcd/lifeboat/` for the round-trip case. - **Install / promote:** `/abcd:ahoy install` bootstraps abcd in any repo (transparent prompts, visibility-driven gitignore, marker block in CLAUDE.md/AGENTS.md, prompt-router hook). `/abcd:launch ship` cuts a curated release from the single repo — `.abcd/**` excluded from the artifact by packaging — with secret/PII scans and a version stamp. - **Forward-looking discipline:** `/abcd:intent` captures product intents in three structural kinds per itd-34 — `standalone` (one user moment, one spec), `bundle-member` (coupled intents share a spec), and `discipline` (cross-cutting rules with no user moment, e.g., the itd-1 acceptance-gates rule that enforces Given-When-Then on every other spec). Standalone and bundle-member intents are press-release-shaped; disciplines use a `## Rule` template instead. `/abcd:capture` runs a structured issue ledger that replaces free-form `.work/issues.md`. `/abcd:intent grill` (sibling of `refine`, per itd-27) is a Socratic-questioning sub-verb that stress-tests intents (or brief sections, via `--brief-section`) before planning. After shipping, `/abcd:intent review` (Role 1 of `intent-fidelity-reviewer`) reviews delivered reality against the press release; `/abcd:intent consistency` (Role 2, shipped in spc-29 per itd-48, which superseded itd-31) catches cross-document drift; `/abcd:intent shape` (Role 3) keeps each intent's `kind` honest. -- **Plumbing that makes it possible:** 15 agents, a vendor-agnostic adapter seam, a host-delegated LLM with opt-in oracle adapters (native, CLI, API, MCP), a prompt-quality stack with golden-test fixtures, structural lint, periodic SOTA audit, prompt-version frontmatter, self-improvement pre-flight, and injection-canary fixtures — plus operator-internal command wiring (e.g. `/abcd:run`, the itd-29 autonomous-run operator surface — read-mostly `status`/`pause`/`resume`/`preflight` over the pluggable autonomous-run seam; not part of the user-facing command set). +- **Plumbing that makes it possible:** 16 agents, a vendor-agnostic adapter seam, a host-delegated LLM with opt-in oracle adapters (native, CLI, API, MCP), a prompt-quality stack with golden-test fixtures, structural lint, periodic SOTA audit, prompt-version frontmatter, self-improvement pre-flight, and injection-canary fixtures — plus operator-internal command wiring (e.g. `/abcd:run`, the itd-29 autonomous-run operator surface — read-mostly `status`/`pause`/`resume`/`preflight` over the pluggable autonomous-run seam; not part of the user-facing command set). See [`04-scope.md`](04-scope.md) for the full scope boundary and [`04-surfaces/`](../04-surfaces) for per-command detail. diff --git a/.abcd/development/brief/01-product/03-mental-model.md b/.abcd/development/brief/01-product/03-mental-model.md index 2c60ce2d..5eb6cc13 100644 --- a/.abcd/development/brief/01-product/03-mental-model.md +++ b/.abcd/development/brief/01-product/03-mental-model.md @@ -68,7 +68,7 @@ flowchart TD **Why typing matters.** The 1:1-only model (every intent = one spec) forces bundle-shaped work into separate specs that redo each other's plumbing, and forces discipline-shaped rules into "specs" whose only deliverable is "every other spec inherits this gate." Both shapes calcify into wrong fits. The three kinds let each intent's *delivery shape* match its *forward-looking shape* without forcing one onto the other. -**The six phases target thirteen intents across two of the three kinds:** ten standalone (itd-2, itd-3, itd-4, itd-6, itd-7, itd-27, itd-28, itd-34, itd-36, itd-40) and three disciplines (itd-1, itd-5, itd-37). The `bundle-member` kind exists in the framework but isn't currently exercised — the corpus has zero live bundles. See [`phases/README.md`](../../roadmap/phases/README.md) for the phase plan and each phase's intent scope, [`intents/README.md`](../../intents/README.md) for the intent index, and that file's § Bundles for the retired-bundle history. +**The phased intents span two of the three kinds** — standalone capabilities plus the three disciplines (itd-1, itd-5, itd-37); the set itself is the union of the phase docs' `## Scope` sections and is never transcribed here (per [adr-9](../../decisions/adrs/0009-phase-as-product-layer.md), hand-kept counts re-drift). The `bundle-member` kind exists in the framework but isn't currently exercised — the corpus has zero live bundles. See [`phases/README.md`](../../roadmap/phases/README.md) for the phase plan and each phase's intent scope, [`intents/README.md`](../../intents/README.md) for the intent index, and that file's § Bundles for the retired-bundle history. **Classification happens at plan time.** Capture stays cheap and format-neutral (`/abcd:intent ""` produces a press-release-shaped draft regardless of eventual kind, with an optional advisory `suggested_kind` hint from the LLM classifier). The binding `kind` field is set at `/abcd:intent plan` time, when the user is committing to *build* the thing — that's when the shape decision has to be true. A continuous audit role (the third role on `intent-fidelity-reviewer`, see [`05-internals/01-agents.md`](../05-internals/01-agents.md)) suggests reclassifications when patterns emerge in the corpus over time. diff --git a/.abcd/development/brief/01-product/04-scope.md b/.abcd/development/brief/01-product/04-scope.md index c6be2e50..d31578ac 100644 --- a/.abcd/development/brief/01-product/04-scope.md +++ b/.abcd/development/brief/01-product/04-scope.md @@ -1,6 +1,6 @@ # Scope -The scope this brief covers is bounded by what is bundled into the six planned phases (Phase 0 — Substrate & disciplines through Phase 5 — round-trip; see [`roadmap/phases/README.md`](../../roadmap/phases/README.md)) plus what is explicitly slated for a later phase. +The scope this brief covers is bounded by what is bundled into the seven planned phases (Phase 0 — Foundations through Phase 6 — Lifeboat round-trip; see [`roadmap/phases/README.md`](../../roadmap/phases/README.md)) plus what is explicitly slated for a later phase. ## What the phases deliver @@ -13,22 +13,32 @@ The scope this brief covers is bounded by what is bundled into the six planned p - `/abcd:intent` — press-release intent capture — see [`04-surfaces/05-intent.md`](../04-surfaces/05-intent.md) - `/abcd:capture` — issue ledger — see [`04-surfaces/06-capture.md`](../04-surfaces/06-capture.md) - `/abcd:memory` — multi-upstream curated knowledge substrate (per itd-36) — see [`05-internals/07-memory.md`](../05-internals/07-memory.md) +- `/abcd` — top-level where-am-i status board (per itd-20) — see [`04-surfaces/08-abcd.md`](../04-surfaces/08-abcd.md) +- `/abcd:reflect` — phase retrospective (per itd-24) — see [`04-surfaces/09-reflect.md`](../04-surfaces/09-reflect.md) **Operator-internal commands** (wiring under `commands/abcd/`, NOT part of the user-facing surface above): `/abcd:run` — the itd-29 autonomous-run operator surface (`status`/`pause`/`resume`/`preflight`; read-mostly over the pluggable autonomous-run seam ([adr-27](../../decisions/adrs/0027-autonomous-run-pluggable-seam.md)), v1 never starts or kills the loop). See [`04-surfaces/README.md`](../04-surfaces/README.md) for the user-facing-vs-operator-internal boundary. -**Thirteen phased intents — ten standalone plus three disciplines:** -- **Standalone (10):** itd-2, itd-3, itd-4, itd-6, itd-7, itd-27, itd-28, itd-34, itd-36, itd-40. -- **Disciplines (3):** itd-1 (acceptance gates), itd-5 (prompt-quality + capability_scope per idea-4), itd-37 (modification grammar per ideas 2+3). Disciplines have no user moment; they impose acceptance gates on every other spec per the three-kinds taxonomy in [`01-product/03-mental-model.md`](03-mental-model.md) and itd-34. +**Phased intents — derived, never hand-counted here.** The intents each phase +bundles are named in that phase doc's `## Scope` section — the single source of +the mapping ([adr-9](../../decisions/adrs/0009-phase-as-product-layer.md)); the +phased set is the union across the seven phase docs, and this page keeps no +static copy of it (a hand-kept count re-drifts the moment a phase doc changes, +the same failure the roadmap dashboard avoids by deriving counts from disk). +The set spans two of the three kinds: standalone capabilities, plus the three +disciplines (itd-1 acceptance gates, itd-5 prompt-quality + capability_scope, +itd-37 modification grammar) — disciplines have no user moment; they impose +acceptance gates on every other spec per the three-kinds taxonomy in +[`01-product/03-mental-model.md`](03-mental-model.md) and itd-34. -See [`phases/README.md`](../../roadmap/phases/README.md) for the phase plan and each phase's intent scope, and [`intents/README.md`](../../intents/README.md) for the intent index. itd-27 (`/abcd:intent grill` sub-verb), itd-28 (spec-tied RP reviews), and itd-34 (three intent kinds) were captured post-brief on 2026-05-07. itd-36 (memory unification) and itd-37 (modification grammar) were captured on 2026-05-08 following adversarial RP review of four candidate ideas (LLM Wiki, Naur theory-building, systems thinking, jagged frontier); itd-40 (folder classification) was captured 2026-05-16. +See [`phases/README.md`](../../roadmap/phases/README.md) for the phase plan and each phase's intent scope, and [`intents/README.md`](../../intents/README.md) for the intent index. Capture history lives in `git log` and each intent file's own provenance, never in this page (per [adr-5](../../decisions/adrs/0005-brief-is-current-state.md)). -**Plumbing infrastructure** (15 agents, 11 adapters, harness shim, prompt-quality stack, hooks): see [`05-internals/`](../05-internals). +**Plumbing infrastructure** (16 agents — the canonical roster is the catalog in [`05-internals/01-agents.md`](../05-internals/01-agents.md) — 11 adapters, harness shim, prompt-quality stack, hooks): see [`05-internals/`](../05-internals). ## What comes in a later phase -**All later-phase items live as press-release intents** in `.abcd/development/intents/drafts/`. The canonical out-of-scope list is at [`06-delivery/03-out-of-scope.md`](../06-delivery/03-out-of-scope.md). +**Later-phase items live as press-release intents** — the uncommitted bench in `.abcd/development/intents/drafts/`, plus the committed-but-unscheduled intents in `planned/` (per [adr-34](../../decisions/adrs/0034-lifecycle-and-scheduling-orthogonal.md)). The canonical out-of-scope list is at [`06-delivery/03-out-of-scope.md`](../06-delivery/03-out-of-scope.md). -The later-phase set is the live `drafts/` corpus minus the intents already scoped into a planned phase; it is enumerated — and kept non-drifting via a filesystem-derived command rather than a hand-count — in the canonical [`06-delivery/03-out-of-scope.md`](../06-delivery/03-out-of-scope.md). itd-31 and itd-32 are superseded (preserved as historical record in `intents/superseded/`). +The later-phase bench is the live `drafts/` corpus (per adr-34 no phase-scoped intent lives there, so nothing is subtracted); it is enumerated — and kept non-drifting via a filesystem-derived command rather than a hand-count — in the canonical [`06-delivery/03-out-of-scope.md`](../06-delivery/03-out-of-scope.md). itd-31 and itd-32 are superseded (preserved as historical record in `intents/superseded/`). Each intent captures the press-release-shaped scope and acceptance criteria. A later-phase intent enters work by being scoped into a phase, then promoted to `planned/` via `/abcd:intent plan ` and to `shipped/` via `/abcd:intent ship ` (or automatically when the linked spec closes). diff --git a/.abcd/development/brief/04-surfaces/02-disembark.md b/.abcd/development/brief/04-surfaces/02-disembark.md index d38a725e..81d31668 100644 --- a/.abcd/development/brief/04-surfaces/02-disembark.md +++ b/.abcd/development/brief/04-surfaces/02-disembark.md @@ -1,6 +1,6 @@ # `/abcd:disembark` — Pack a Lifeboat -> **Status:** design target — builds in Phase 4 (the lifeboat pipeline). Today only the probe / dry-run stubs ship (spc-17); the full flow below is not yet built. +> **Phase ownership** ([adr-33](../../decisions/adrs/0033-launch-phase-ownership-tiered.md)): the lifeboat round-trip — disembark packing and embark unpacking — ships in [Phase 6](../../roadmap/phases/phase-6-lifeboat.md). > **Recovery humility.** Disembark packs the highest-fidelity proxy of the project's theory we can leave behind. It is not the theory. The theory of any non-trivial project lives in the people who built it, the conversations where decisions were made, and the alternatives they rejected before this one — what Naur (1985) called the lived activity of building. The lifeboat is the floor we can carry forward across a session, machine, or team boundary; it is not the activity itself. See [`01-product/03-mental-model.md § The Naurian gap`](../01-product/03-mental-model.md#the-naurian-gap) for the framing. @@ -109,7 +109,7 @@ Pass B's chat-distiller is exempt (already streams by per-spine-entry queries). │ └── code-principles.{json,md} # from code-rescuer ├── docs/ │ ├── adrs/ # verbatim ADR copies -│ ├── terminology.md # rendered from .abcd/development/foundation/terminology//.md (per itd-27 / spc-3) +│ ├── terminology.md # rendered from .abcd/development/brief/glossary//.md (per itd-27 / spc-3, adr-30) │ ├── claude-md-snapshot.md │ └── tutorials/ guides/ reference/ explanation/ # verbatim from source docs/ ├── assets/ diff --git a/.abcd/development/brief/04-surfaces/03-embark.md b/.abcd/development/brief/04-surfaces/03-embark.md index 3dc8913e..8af19f20 100644 --- a/.abcd/development/brief/04-surfaces/03-embark.md +++ b/.abcd/development/brief/04-surfaces/03-embark.md @@ -1,6 +1,6 @@ # `/abcd:embark` — Unpack a Lifeboat -> **Status:** design target — builds in Phase 5 (round-trip and ship). Today only the probe / scan stubs ship (spc-17); the full flow below is not yet built. +> **Phase ownership** ([adr-33](../../decisions/adrs/0033-launch-phase-ownership-tiered.md)): the lifeboat round-trip — disembark packing and embark unpacking — ships in [Phase 6](../../roadmap/phases/phase-6-lifeboat.md). > **Recovery humility.** Embark unpacks the lifeboat into a working repo. The lifeboat is the highest-fidelity floor the originating session could leave behind; it is not the activity that produced it. **When something here doesn't make sense, hunt the originating session before trusting the lifeboat blindly** — ask the prior author, surface the chat where the decision happened, look at the rejected alternatives. The lifeboat is a starting point, not an oracle. See [`01-product/03-mental-model.md § The Naurian gap`](../01-product/03-mental-model.md#the-naurian-gap) for the framing. diff --git a/.abcd/development/brief/04-surfaces/04-launch.md b/.abcd/development/brief/04-surfaces/04-launch.md index ae0e4752..a0152be6 100644 --- a/.abcd/development/brief/04-surfaces/04-launch.md +++ b/.abcd/development/brief/04-surfaces/04-launch.md @@ -1,13 +1,13 @@ # `/abcd:launch` — Curated Release -> **Status:** design target — builds in Phase 5 (round-trip and ship). Today only the probe / dry-run stubs ship (spc-17); the full pre-flight gate suite and release flow below are not yet built. +> **Phase ownership** ([adr-33](../../decisions/adrs/0033-launch-phase-ownership-tiered.md)): the curated-release cut — packaging with `.abcd/**` excluded plus the secret/PII scan — ships in [Phase 1](../../roadmap/phases/phase-1-ahoy.md). The full pre-flight gate suite and release automation below are separately scheduled intents (itd-65 gate suite, itd-66 render parity, itd-70 retention, itd-72 tier-b publishing, itd-73 derived versioning). ## Sub-verbs Bare `/abcd:launch` shows status + help only — never mutates state. Current sub-verbs: -- **`/abcd:launch ship`** — cut a curated release artefact from the one repo: run pre-flight gates, filter the artefact (default-deny, `.abcd/**` excluded by packaging), stamp the version, and on a `v*` tag publish a GitHub Release ([adr-28](../../decisions/adrs/0028-single-repo-curated-release.md)). The flow described in §§ 1–6 below is this sub-verb's behaviour. Flag-shaped modifiers: `--version `, `--allow-dirty`, `--allow-doc-warnings`. -- **`/abcd:launch dry-run`** — **report-only preview, always exit-0** (a preview never blocks). It runs the parts of the pre-flight suite that exist today: as of spc-64 the **secret + PII scan gate** (the native scanners, see [§ 1](#1-pre-flight-gates)) runs for real in report-only mode and prints what it *would* refuse on (a finding, or a fail-closed reason such as "scanner unavailable"); the remaining gates (marker-block, `plugin.json` parse, documentation-auditor) are Phase-5 and render as "(not yet implemented)". It also produces the would-be artefact manifest, without writing the release artefact. dry-run is **not** "ship minus publish": running the *full* gate suite and **hard-failing** on a finding (exit non-zero) is the Phase-5 `ship` verb's behaviour, not dry-run's. +- **`/abcd:launch ship`** — cut a curated release artefact from the one repo: run pre-flight gates, filter the artefact (default-deny, `.abcd/**` excluded by packaging), stamp the version, and on a `v*` tag publish a GitHub Release ([adr-28](../../decisions/adrs/0028-single-repo-curated-release.md)). The flow described in §§ 1–6 below is this sub-verb's behaviour. Flag-shaped modifiers: `--allow-dirty`, `--allow-doc-warnings`. There is no version flag — the version is derived, never authored ([adr-31](../../decisions/adrs/0031-derived-versioning-from-intents.md), see [§ 3](#3-versioning--marketplace)). +- **`/abcd:launch dry-run`** — **report-only preview, always exit-0** (a preview never blocks). It runs the parts of the pre-flight suite that exist today: as of spc-64 the **secret + PII scan gate** (the native scanners, see [§ 1](#1-pre-flight-gates)) runs for real in report-only mode and prints what it *would* refuse on (a finding, or a fail-closed reason such as "scanner unavailable"); the remaining gates (marker-block, `plugin.json` parse, documentation-auditor) are the gate-suite intent's (itd-65) and render as "(not yet implemented)". It also produces the would-be artefact manifest, without writing the release artefact. dry-run is **not** "ship minus publish": running the *full* gate suite and **hard-failing** on a finding (exit non-zero) is the full `ship` verb's behaviour (itd-65 + itd-72), not dry-run's. ## 1. Pre-flight gates @@ -22,7 +22,7 @@ Bare `/abcd:launch` shows status + help only — never mutates state. Current su - **OWASP / vulnerability check** (folded into the pre-flight suite) — warn-fail - **Documentation auditor** (subagent) — runs over `docs/` to verify user-facing documentation is well-formed before release — warn-fail -Pre-flight report written to `.abcd/logbook/launch//preflight.{json,md}` — **Phase-5 `ship` behaviour**. The spc-64 secret/PII gate is itself side-effect-free w.r.t. the repo (its only writes are to a private temp tree it removes), and `dry-run` renders the gate result inline rather than writing a report file. +Pre-flight report written to `.abcd/logbook/launch//preflight.{json,md}` — **full-`ship` behaviour (itd-65)**. The spc-64 secret/PII gate is itself side-effect-free w.r.t. the repo (its only writes are to a private temp tree it removes), and `dry-run` renders the gate result inline rather than writing a report file. ## 2. Curated release artefact (default-deny) @@ -43,37 +43,35 @@ Versioning is **strict SemVer**: the version string is `MAJOR.MINOR.PATCH` (no leading `v`) at the selected version location, and the release's git tag is `v`. While the version is `0.y.z` the operator surface may still change between minor versions (pre-1.0 = not yet surface-stable); `1.0.0` marks the -first stable `/abcd:*` surface and is a manual, maintainer-declared bump like -every other major. The tag drives identification: what is installed vs what is -available is compared through the tagged, released artefact — the working tree -carries no version at all (adr-19, adr-28). +first stable `/abcd:*` surface. The tag drives identification: what is installed +vs what is available is compared through the tagged, released artefact — the +working tree carries no version at all (adr-19, adr-28). ### Bump-tier rule -`launch ship` selects the bump tier automatically; the tier is recorded in the -launch report and the commit message so every published version is traceable -to *why* it bumped. - -| Tier | Trigger | Selected by | -|---|---|---| -| **Patch** (`v0.0.x`) | Any release cut that is not a phase completion — a routine snapshot of in-progress work. | Default — every `ship` that isn't one of the rows below. | -| **Minor** (`v0.x.0`) | A phase completed since the last release: every spec carrying that phase's `phase:` anchor is closed, and the phase's `## Phase Acceptance` has been reviewed. | Auto-detected (see below). | -| **Major** (`vx.0.0`) | A deliberate milestone the maintainer declares. | **Manual only** — `launch ship --version `. Never auto-selected. | - -**Phase-completion detection.** Before choosing a tier, `launch ship` reads -`.abcd/development/roadmap/phases/` and, for each phase, checks whether every -spec anchored to it (`phase:` frontmatter, per adr-9) is closed in the native -spec store. The `phase:` anchor is deferred today (see [`roadmap/phases/README.md`](../../roadmap/phases/README.md)); -it activates with this launch surface, so until then the phase set this -detection reads is the editorial `## Scope` membership, not a frontmatter field. If -a phase became fully-closed since the version recorded in the last -`launch-report.json`, the bump is **minor** and the report names the completed -phase. If more than one phase completed since the last launch, it is still a -single minor bump; the report lists all of them. If none did, the bump is -**patch**. - -`--version ` overrides the auto-selected tier entirely (the only way to -trigger a major bump, and an escape hatch if detection is wrong). +The version is **derived, never authored** +([adr-31](../../decisions/adrs/0031-derived-versioning-from-intents.md)): +`launch ship` selects the bump tier from the intents shipped since the previous +release; the tier and its reason are recorded in the launch report and the +commit message so every published version is traceable to *why* it bumped. + +| Tier | Trigger | +|---|---| +| **Major** (`vx.0.0`) | Any shipped intent since the last release carries `impact: breaking`. | +| **Minor** (`v0.x.0`) | No `breaking`, at least one `impact: additive`. | +| **Patch** (`v0.0.x`) | Only `impact: fix` intents (or a release with no intent-tied change). | + +**Impact derivation.** Every intent carries `impact: additive | breaking | fix`, +set when the intent is shaped and enforced by `internal/core/lint` (adr-31, tracked +by itd-73). At release, `launch ship` gathers the intents shipped since the +previous release and takes the highest-severity impact. A change not tied to any +intent falls back to conventional-commit derivation (`feat:` / `fix:` / +`feat!:` prefixes since the last tag). + +**Surface-diff guardrail.** `launch ship` snapshots the `/abcd:*` command, flag, +and manifest surface and compares it to the previous release. A removed or +altered surface with no `breaking` intent in the release **fails the launch** — +a mislabelled impact cannot ship a compatibility lie. `launch ship` is responsible for writing the version into **the selected version location**, never a hard-coded `plugin.json`. That location is recorded @@ -113,7 +111,7 @@ The checker has no bypass flag, and adr-20 records that `--allow-dirty` must not bypass manifest consistency (wiring policy, enforced by the pre-flight suite). Commit message: `chore(release): launch abcd v (: ) from ` -— e.g. `chore(release): launch abcd v0.3.0 (minor: phase-2-ahoy complete) from a1b2c3d`. +— e.g. `chore(release): launch abcd v0.3.0 (minor: additive itd-40 shipped) from a1b2c3d`. ### Release cut + retention @@ -154,13 +152,13 @@ The first release cut of abcd itself is a manual `v*` tag + GitHub Release; docu ## 6. Acceptance - **Given** any abcd-aware terminal, **when** the user runs bare `/abcd:launch`, **then** the dispatcher shows current launch readiness (pre-flight gate state, last launch attempt timestamp), the available sub-verbs (`ship`, `dry-run`), and suggested next actions — bare invocation never mutates state. -- **Given** a clean tree with a deliberate PII fixture (e.g., a real email in a comment) inside the resolved artefact, **when** `/abcd:launch dry-run` runs, **then** the report-only gate (spc-64) PRINTS that it *would* refuse on that finding (the offending file/line in the gate result), still **exits 0**, and writes no artefact. (The **hard-fail** on that finding — exit non-zero plus a `preflight.{json,md}` report under `.abcd/logbook/launch//` — is the Phase-5 `ship` verb's behaviour, not dry-run's.) +- **Given** a clean tree with a deliberate PII fixture (e.g., a real email in a comment) inside the resolved artefact, **when** `/abcd:launch dry-run` runs, **then** the report-only gate (spc-64) PRINTS that it *would* refuse on that finding (the offending file/line in the gate result), still **exits 0**, and writes no artefact. (The **hard-fail** on that finding — exit non-zero plus a `preflight.{json,md}` report under `.abcd/logbook/launch//` — is the full `ship` verb's behaviour (itd-65), not dry-run's.) - **Given** a clean tree, **when** `/abcd:launch dry-run` runs, **then** the report lists exactly the include/exclude artefact manifest in [§ 2](#2-curated-release-artefact-default-deny) with no surprises and no artefact is written. -- **Given** no phase completed since the last launch, **when** `launch ship` runs without `--version`, **then** the bump tier is **patch** (`v0.0.x`) and the next patch version is written into the **selected version location** (from `.abcd/config/version-location.json`, per [§ 3](#3-versioning--marketplace)) in the **release artefact** only — the working-tree manifests stay unversioned (adr-19, adr-28) — plus the canonical `.claude-plugin/marketplace.json`, never a hard-coded `plugin.json`. -- **Given** every spec anchored to a phase (`phase:` frontmatter) is closed and that phase was not yet complete at the last recorded launch, **when** `launch ship` runs without `--version`, **then** the bump tier is **minor** (`v0.x.0`) and the launch report names the completed phase. -- **Given** two or more phases completed since the last launch, **when** `launch ship` runs without `--version`, **then** a single **minor** bump is applied and the report lists every completed phase. -- **Given** the user passes `launch ship --version `, **when** the command runs, **then** the explicit version overrides the auto-selected tier — this is the only path to a major (`vx.0.0`) bump. -- **Given** any `launch ship` run, **when** the release commit is written, **then** the commit message records the bump tier and its reason (e.g. `(minor: phase-2-ahoy complete)`). +- **Given** only `impact: fix` intents (or no intent-tied change) shipped since the last release, **when** `launch ship` runs, **then** the bump tier is **patch** (`v0.0.x`) and the next patch version is written into the **selected version location** (from `.abcd/config/version-location.json`, per [§ 3](#3-versioning--marketplace)) in the **release artefact** only — the working-tree manifests stay unversioned (adr-19, adr-28) — plus the canonical `.claude-plugin/marketplace.json`, never a hard-coded `plugin.json`. +- **Given** at least one `impact: additive` intent and no `breaking` intent shipped since the last release, **when** `launch ship` runs, **then** the bump tier is **minor** (`v0.x.0`) and the launch report names the intents that drove it. +- **Given** any `impact: breaking` intent shipped since the last release, **when** `launch ship` runs, **then** the bump tier is **major** (`vx.0.0`) and the launch report names the breaking intent(s). +- **Given** a command, flag, or manifest surface removed or altered since the previous release with no `breaking` intent in the release, **when** `launch ship` runs, **then** the surface-diff guardrail **fails the launch** (adr-31) — the mislabel is reported, nothing is published. +- **Given** any `launch ship` run, **when** the release commit is written, **then** the commit message records the bump tier and its reason (e.g. `(minor: additive itd-40 shipped)`). - **Given** a documentation-auditor warn-fail, **when** `launch ship` runs without `--allow-doc-warnings`, **then** the user is shown the warnings and asked transparently whether to proceed. - **Given** a prior release of the same line (`vX.Y.(Z-1)`) exists, **when** `launch ship` publishes `vX.Y.Z`, **then** the superseded release's tag and GitHub Release + assets are removed, the removal is named in the launch report, and the last release of every *other* line is untouched. - **Given** a release newer than the just-published version already exists, **when** the retention step runs, **then** it refuses to prune anything and the launch report records the refusal reason. diff --git a/.abcd/development/brief/04-surfaces/05-intent.md b/.abcd/development/brief/04-surfaces/05-intent.md index 1b400b4d..ce6a4d3b 100644 --- a/.abcd/development/brief/04-surfaces/05-intent.md +++ b/.abcd/development/brief/04-surfaces/05-intent.md @@ -201,7 +201,7 @@ On demand: intent-fidelity-reviewer (shape-classification role) scans the corpus | `/abcd:intent ship ` | Kicks off implementation via the native ship/run seam. Only valid for `kind: standalone` or `kind: bundle-member`. If intent is still in `drafts/`, runs the full pipeline first (plan + plan-review). On spec completion the lifecycle hook completes the move automatically; this command can also force-move if hook missed. **Disciplines have no `ship` step** — they are continuously active once in `disciplines/`. | (eventually) → `shipped/` (or no-op for disciplines) | | `/abcd:intent review ` | **Role 1 — single-document fidelity.** Compares the intent's press release + acceptance criteria against delivered reality (code, configs, docs, tests). Per-criterion verdicts (`MET` / `MET_WITH_CONCERNS` / `NOT_MET` / `INCONCLUSIVE`) appended to the intent's `## Audit Notes`. Aligns with the spec store's `plan-review` / `impl-review` / `completion-review` vocabulary — same operation shape (adversarial second opinion), different opponent (press release vs engineering spec). spc-12 ships this **manual** verb; spc-28 shipped the on-close hook (move `planned → shipped` + queue a review), but auto-running the reviewer off that queue is still deferred (no spec currently owns it; spc-6 disowned auto-firing). | (stays) | | `/abcd:intent consistency []` | **Role 2 — cross-document fidelity.** Surfaces five judgement categories (terminology drift, premise contradictions, scope leakage, sequencing impossibilities, naming conflicts) across briefs + intents. **Bare** scans the whole corpus; **with ``** narrows to one intent's relationship with the rest. Findings land in `.abcd/logbook/audit/consistency-/report.{json,md}`. Live as of spc-29 (judgement half + on-demand verb); mechanical-half categories and pre-commit hook are deferred follow-ups (see `.work/issues.md` `[spc-29 follow-up]` entries). | (stays) | -| `/abcd:intent shape []` | **Role 3 — kind classification.** Examines whether an intent's declared `kind` (the noun) still fits the corpus. Surfaces *suggested* reclassifications across three live types: `kind_change`, `bundle`, `supersession`. **Bare** scans the corpus; **with ``** checks one intent. Pairs with `reclassify` (action verb that commits a `shape` finding). On-demand only as of spc-29; findings land in `.abcd/logbook/audit/shape-/report.{json,md}`. Concurrency via `flock(2)` on `.abcd/coordination/shape.lock` (see § 6). Scheduled / continuous invocation is a deferred follow-up (see `.work/issues.md` `[spc-29 follow-up]`). | (stays) | +| `/abcd:intent shape []` | **Role 3 — kind classification.** Examines whether an intent's declared `kind` (the noun) still fits the corpus. Surfaces *suggested* reclassifications across three live types: `kind_change`, `bundle`, `supersession`. **Bare** scans the corpus; **with ``** checks one intent. Pairs with `reclassify` (action verb that commits a `shape` finding). On-demand only as of spc-29; findings land in `.abcd/logbook/audit/shape-/report.{json,md}`. Concurrency via `flock(2)` on `.abcd/coordination/shape.lock` (see § 7). Scheduled / continuous invocation is a deferred follow-up (see `.work/issues.md` `[spc-29 follow-up]`). | (stays) | | `/abcd:intent reclassify --kind [--reason ]` | Late reclassification (e.g., a standalone intent realised to be a bundle-member; a draft realised to be a discipline; a shipped intent superseded by a later one). Records `reclassification_history` entry; moves the file between directories as the new kind dictates. `--kind superseded --by ` is the supersession path: the file moves to `superseded/`, frontmatter records `superseded_by: itd-M` AND `kind_at_supersession: ` so future readers know what shape the intent had when retired. | varies by destination kind | | `/abcd:intent link ` | Manual bidirectional link — used if the auto-link missed (rare) or for retroactive linking of pre-existing specs | (no move; updates frontmatter) | diff --git a/.abcd/development/brief/04-surfaces/07-memory.md b/.abcd/development/brief/04-surfaces/07-memory.md index 39819256..f244acc3 100644 --- a/.abcd/development/brief/04-surfaces/07-memory.md +++ b/.abcd/development/brief/04-surfaces/07-memory.md @@ -1,6 +1,6 @@ # `/abcd:memory` — Multi-Upstream Curated Knowledge Substrate -User-facing command for the per-project compounding-curated knowledge substrate at `.abcd/memory/`. Design target per itd-36 (idea-1 final shape after 5-round adversarial oracle review); the write core (ingest/ask/bare) shipped via spc-38 (the memory write core) and the lint family via spc-39 (the memory-coverage lints + the `MQ`/`MS`/`ML` codes). +User-facing command for the per-project compounding-curated knowledge substrate at `.abcd/memory/`. Design target per itd-36 (idea-1 final shape after 5-round adversarial oracle review); the write core (ingest/ask/bare) is spc-38's (the memory write core) and the lint family spc-39's (the memory-coverage lints + the `MQ`/`MS`/`ML` codes). itd-36 sits in `intents/planned/` — delivery state is the intent lifecycle's, not this page's (see the [brief README's provenance note](../README.md)). For the **substrate spec** (page-class enum, source-class taxonomy, curator behaviour, lifecycle class, integration with itd-26 loot), see [`05-internals/07-memory.md`](../05-internals/07-memory.md). This file is the surface contract: what the user types and what happens. @@ -11,7 +11,7 @@ Bare `/abcd:memory` shows status + help + render of current memory state — nev - **Bare `/abcd:memory`** — render: page count by class (e.g., "23 session_memory + 8 external_pdf + 4 oracle_review + 2 spec_modification_grammar"), last-ingest timestamp, recent contradictions surface, suggested next actions. No mutation. Quotation-budget headroom per source renders READ-ONLY from the spc-39 `.coverage_index.json`: when the index is present AND fingerprint-fresh (a read-only crawl recomputes the current fingerprint and matches the stored one) it shows per-source warn/block headroom; fingerprint drift shows a "stale — run /abcd:memory lint" hint; an absent index an info line; a malformed index or crawl failure a non-fatal "headroom unavailable" line. The bare render never rebuilds or mutates the index. - **`/abcd:memory ingest `** — read external source (PDF / transcript / article / URL), distil into typed entity/topic pages with citation frontmatter, append to ingest log. **Default: do NOT store original.** Flag-shaped modifier: `--keep-original` (opt-in storage at `.abcd/memory/sources/.`; the lifeboat licence gate — `/abcd:disembark`, NOT launch, per adr-18 — refuses publish without an explicit allowlist entry; launch excludes `.abcd/**` wholesale per [`04-launch.md § 2`](04-launch.md#2-curated-release-artefact-default-deny)). - **`/abcd:memory ask `** — query memory by domain + class; synthesise an answer with citations (every citation references `source.class` + `citation` + `source_hash`); optionally file the result back as a new memory page (interactive prompt). -- **`/abcd:memory lint` (spc-39 — shipped)** — full-store curator health-check: per-page quotation budgets (`MQ001`), cumulative source coverage (`MQ002`), coverage-unavailable diagnostic (`MQ003`, info), source-class single-class advisory (`MS001`), cross-class without weighting note (`MS002`), missing licence on `external_*` (`ML001`). ALWAYS crawls the full repo store, rebuilds the regenerable `.coverage_index.json`, emits findings to `.abcd/logbook/memory/lint-/report.{json,md}`. Exit: blockers → nonzero; warn-only → 0 (curator advisory — see [`06-lint.md §2`](../05-internals/06-lint.md#2-severity-model)). Mutates no memory-store state (coverage index + logbook report are its only writes). Per ADR-13's write/lint split, the spc-38 write core ships ingest/ask/bare; spc-39 ships this lint family ONLY — contradictions are rendered by spc-38's reconciliation (surfaced by the bare render), orphan/stale-claim audits are deferred. +- **`/abcd:memory lint` (spc-39)** — full-store curator health-check: per-page quotation budgets (`MQ001`), cumulative source coverage (`MQ002`), coverage-unavailable diagnostic (`MQ003`, info), source-class single-class advisory (`MS001`), cross-class without weighting note (`MS002`), missing licence on `external_*` (`ML001`). ALWAYS crawls the full repo store, rebuilds the regenerable `.coverage_index.json`, emits findings to `.abcd/logbook/memory/lint-/report.{json,md}`. Exit: blockers → nonzero; warn-only → 0 (curator advisory — see [`06-lint.md §2`](../05-internals/06-lint.md#2-severity-model)). Mutates no memory-store state (coverage index + logbook report are its only writes). Per ADR-13's write/lint split, the spc-38 write core ships ingest/ask/bare; spc-39 ships this lint family ONLY — contradictions are rendered by spc-38's reconciliation (surfaced by the bare render), orphan/stale-claim audits are deferred. ## 1. Default flow — distil, cite, discard @@ -22,7 +22,7 @@ Bare `/abcd:memory` shows status + help + render of current memory state — nev PROBE - Compute sha256 of source content - Look up in .abcd/memory/.sources_index.json (the provenance substrate per - itd-36 — shipped via spc-38, the provenance capability; distinct from the + itd-36/spc-38, the provenance capability; distinct from the ahoy history store that keys session transcripts on the root-commit SHA) - If found: bump ingest_count, update last_ingest, return cached citation - If new: continue @@ -68,9 +68,9 @@ See [the full acceptance criteria](../../intents/planned/itd-36-memory-unificati - **Ingest default-no-original**: original NOT stored unless `--keep-original`; citation + source_hash recorded; quotation budget applied per page (enforced at lint time by spc-39's `MQ001`, never at ingest). - **Ingest with `--keep-original`**: original stored at `.abcd/memory/sources/.`; the lifeboat licence gate (`/abcd:disembark`, not launch — adr-18) refuses publish without allowlist. - **Ask**: synthesises answer with per-citation provenance (class + citation + source_hash); optionally files result back. -- **Lint (spc-39 — shipped; not spc-38 behaviour)**: emits `MQ001` / `MQ002` / `MQ003` / `MS001` / `MS002` / `ML001` codes; cumulative coverage uses span-level dedup. spc-38 writes `licence: unknown` explicitly; spc-39's `ML001` is what lints it. +- **Lint (spc-39, not spc-38 behaviour)**: emits `MQ001` / `MQ002` / `MQ003` / `MS001` / `MS002` / `ML001` codes; cumulative coverage uses span-level dedup. spc-38 writes `licence: unknown` explicitly; spc-39's `ML001` is what lints it. - **Schema extension on existing**: existing flat-named pages preserved; `index.md` generated over them; `source.class: session_memory` backfilled as default. -- **Cross-consumer registry**: the provenance substrate's `.abcd/memory/.sources_index.json` (per itd-36 — shipped via spc-38, the provenance capability; not to be confused with the ahoy history store) is shared with itd-26 loot (a later phase, not yet built); same hash → same registry entry. +- **Cross-consumer registry**: the provenance substrate's `.abcd/memory/.sources_index.json` (per itd-36/spc-38, the provenance capability; not to be confused with the ahoy history store) is shared with itd-26 loot (a later phase, not yet built); same hash → same registry entry. ## 3. Logbook layout diff --git a/.abcd/development/brief/04-surfaces/README.md b/.abcd/development/brief/04-surfaces/README.md index 845477bc..5627f2a8 100644 --- a/.abcd/development/brief/04-surfaces/README.md +++ b/.abcd/development/brief/04-surfaces/README.md @@ -8,7 +8,7 @@ The brief's user-facing command surface is the set enumerated below (not all are | 2 | `/abcd:disembark` | Pack a lifeboat from the current project | [`02-disembark.md`](02-disembark.md) | | 3 | `/abcd:embark` | Unpack a lifeboat into a (typically empty) target | [`03-embark.md`](03-embark.md) | | 4 | `/abcd:launch` | Cut a curated release artefact from the repo | [`04-launch.md`](04-launch.md) | -| 5 | `/abcd:intent` | Capture / refine / grill / plan / ship / review / consistency / shape / reclassify / link intents (press-release format; three review roles, three verbs per [`05-intent.md § 6`](05-intent.md#6-the-intent-fidelity-reviewer-agent-three-roles-three-verbs)) | [`05-intent.md`](05-intent.md) | +| 5 | `/abcd:intent` | Capture / refine / grill / plan / ship / review / consistency / shape / reclassify / link intents (press-release format; three review roles, three verbs per [`05-intent.md § 7`](05-intent.md#7-the-intent-fidelity-reviewer-agent-three-roles-three-verbs)) | [`05-intent.md`](05-intent.md) | | 6 | `/abcd:capture` | Issue ledger (capture / list / promote / resolve / wontfix) | [`06-capture.md`](06-capture.md) | | 7 | `/abcd:memory` | Multi-upstream curated knowledge substrate (per itd-36) — `ingest` external sources / `ask` queries / `lint` health-checks. Component spec: [`05-internals/07-memory.md`](../05-internals/07-memory.md). | [`07-memory.md`](07-memory.md) | | 8 | `/abcd` | Top-level where-am-i status board (per itd-20) — cross-command re-orientation: project + visibility, lifeboat, dev-sync, recent logbook, active intents, next actions. `status` / `help` are byte-identical aliases. Read-only. | [`08-abcd.md`](08-abcd.md) | diff --git a/.abcd/development/brief/05-internals/01-agents.md b/.abcd/development/brief/05-internals/01-agents.md index 337fddde..d086a40b 100644 --- a/.abcd/development/brief/05-internals/01-agents.md +++ b/.abcd/development/brief/05-internals/01-agents.md @@ -4,22 +4,22 @@ The catalog below declares **16 agents** (the design-target roster — not all a | Agent | Pass | Status | Inputs (JSON) | Outputs (JSON) | |---|---|---|---|---| -| `flow-essence` | A | design target — Phase 4 | native spec store (newest-first) | `spec-essence.json` | -| `decision-archaeologist` | A | design target — Phase 4 | ADRs, CLAUDE.md, git log | `decisions-timeline.json` | -| `review-collator` | A | design target — Phase 4 | `.abcd/development/activity/reviews/oracle-review-*` | `reviews-consolidated.json` | -| `code-rescuer` | A | design target — Phase 4 | codemap adapter (when wired) or spec-window file selection | `code-principles.json` | -| `chat-distiller` | B | design target — Phase 4 | spine entry + time-windowed transcript subset (per call) | per-call: emits `rationale-fill`, `unrecorded-decision`, `pitfall` delta entries; aggregated across calls into `research/rationale-fills.json`, `research/unrecorded-decisions.json`, `research/pitfalls.json` (delta). Density measured on user-message denominator per Phase 0 Measurement Deviation; see `research/phase/0/transcript-sampling.md`. | -| `principle-distiller` | C | design target — Phase 4 | `.abcd/memory/`, ADRs, conventions, `spec-essence.json` (spine), `code-principles.json`, `candidate-pitfalls.json` (from review-collator), Pass B distiller deltas | `principles.json` (domain-grouped, with four-source pitfall dedup by topic-hash) | -| `artefact-curator` | C | design target — Phase 4 | user-docs (tutorials/guides/reference/explanation), assets (logos/charts/screenshots) | `assets/_manifest.json` with per-item classification: `keep` (copy verbatim), `adapt` (suggest adaptation, embark prompts user), `drop` (skip silently). Also writes `docs/` lifeboat copies. | -| `brief-composer` | C | design target — Phase 4 | `spec-essence.json`, `decisions-timeline.json`, `principles.json`, `code-principles.json`, `reviews-consolidated.json`, `rationale-fills.json`, `unrecorded-decisions.json`, `pitfalls.json`, `assets/_manifest.json` | `README.json` (lifeboat brief synthesising all Pass A/B/C inputs) | -| `press-release-composer` | C | design target — Phase 4 | spec-essence, decisions, principles, source CLAUDE.md/README/metadata | `press-release.json` + invokes the oracle seam for a product-thinker audit (host-delegated by default) → `audit/press-release-oracle-.json` | -| `issue-scout` | C (opt-in) | design target — Phase 4 | `.abcd/development/activity/issues/.md` entries | annotated entries with "Related upstream" sections; uses `gh` CLI. **Peer-preferred:** delegates to a peer github-scout over MCP when one is present; this native agent is the default. Default: disabled in `config.json`; ahoy asks. | -| `lifeboat-oracle` | C (audit) | design target — Phase 4 | rendered MD + JSON corpus | `audit/oracle-.json` | -| `embark-scaffolder` | embark | design target — Phase 5 | lifeboat JSONs + target probe | `scaffold-plan.json` + extended responsibilities for doc-architecture at scaffold time (legacy harvest) | -| `launch-gatekeeper` | launch | design target — Phase 5 | scan results + payload manifest | `preflight.json` + extended responsibilities for doc updates and OWASP/security auditing at promotion time (legacy harvest) | -| `intent-fidelity-reviewer` | intent — **three roles, three verbs** (`review` / `consistency` / `shape`) | shipped — spc-12 (`review` discipline subset) + spc-29 (`consistency` / `shape`) | varies by role (see [`04-surfaces/05-intent.md § 6`](../04-surfaces/05-intent.md#6-the-intent-fidelity-reviewer-agent-three-roles-three-verbs)) | varies by role | -| `documentation-auditor` | subagent (pre-pack, post-scaffold, pre-promotion) | design target — Phase 4/5 | source `docs/` directory or lifeboat `docs/` directory | `documentation-audit-.json` — invoked by disembark (pre-pack), embark (post-scaffold), and launch (pre-promotion). Subagent-only; not user-invoked. Lifted from legacy `~/ABCDevelopment/.claude/agents/documentation-auditor` | -| `reflection-composer` | reflect | shipped — spc-83 (thin V1) | selected spc-66 phase-audit receipt (`.abcd/logbook/audit/phase-/report.json`) — per-bullet acceptance verdicts + `member_specs` + `done_total` | single JSON object with the five retrospective section keys (`went_well` / `could_improve` / `lessons_learned` / `decisions_made` / `metrics`); the deterministic reflect writer (`internal/core/reflect`) renders `.abcd/retrospectives//README.md`. Dispatched by `/abcd:reflect ` (itd-24). Phase-only grain. | +| `flow-essence` | A | design target — Phase 6 | native spec store (newest-first) | `spec-essence.json` | +| `decision-archaeologist` | A | design target — Phase 6 | ADRs, CLAUDE.md, git log | `decisions-timeline.json` | +| `review-collator` | A | design target — Phase 6 | `.abcd/development/activity/reviews/oracle-review-*` | `reviews-consolidated.json` | +| `code-rescuer` | A | design target — Phase 6 | codemap adapter (when wired) or spec-window file selection | `code-principles.json` | +| `chat-distiller` | B | design target — Phase 6 | spine entry + time-windowed transcript subset (per call) | per-call: emits `rationale-fill`, `unrecorded-decision`, `pitfall` delta entries; aggregated across calls into `research/rationale-fills.json`, `research/unrecorded-decisions.json`, `research/pitfalls.json` (delta). Density measured on user-message denominator per Phase 0 Measurement Deviation; see `research/phase/0/transcript-sampling.md`. | +| `principle-distiller` | C | design target — Phase 6 | `.abcd/memory/`, ADRs, conventions, `spec-essence.json` (spine), `code-principles.json`, `candidate-pitfalls.json` (from review-collator), Pass B distiller deltas | `principles.json` (domain-grouped, with four-source pitfall dedup by topic-hash) | +| `artefact-curator` | C | design target — Phase 6 | user-docs (tutorials/guides/reference/explanation), assets (logos/charts/screenshots) | `assets/_manifest.json` with per-item classification: `keep` (copy verbatim), `adapt` (suggest adaptation, embark prompts user), `drop` (skip silently). Also writes `docs/` lifeboat copies. | +| `brief-composer` | C | design target — Phase 6 | `spec-essence.json`, `decisions-timeline.json`, `principles.json`, `code-principles.json`, `reviews-consolidated.json`, `rationale-fills.json`, `unrecorded-decisions.json`, `pitfalls.json`, `assets/_manifest.json` | `README.json` (lifeboat brief synthesising all Pass A/B/C inputs) | +| `press-release-composer` | C | design target — Phase 6 | spec-essence, decisions, principles, source CLAUDE.md/README/metadata | `press-release.json` + invokes the oracle seam for a product-thinker audit (host-delegated by default) → `audit/press-release-oracle-.json` | +| `issue-scout` | C (opt-in) | design target — Phase 6 | `.abcd/development/activity/issues/.md` entries | annotated entries with "Related upstream" sections; uses `gh` CLI. **Peer-preferred:** delegates to a peer github-scout over MCP when one is present; this native agent is the default. Default: disabled in `config.json`; ahoy asks. | +| `lifeboat-oracle` | C (audit) | design target — Phase 6 | rendered MD + JSON corpus | `audit/oracle-.json` | +| `embark-scaffolder` | embark | design target — Phase 6 | lifeboat JSONs + target probe | `scaffold-plan.json` + extended responsibilities for doc-architecture at scaffold time (legacy harvest) | +| `launch-gatekeeper` | launch | design target — itd-65 (gate suite, per [adr-33](../../decisions/adrs/0033-launch-phase-ownership-tiered.md)) | scan results + payload manifest | `preflight.json` + extended responsibilities for doc updates and OWASP/security auditing at promotion time (legacy harvest) | +| `intent-fidelity-reviewer` | intent — **three roles, three verbs** (`review` / `consistency` / `shape`) | design target — spc-12 (`review` discipline subset) + spc-29 (`consistency` / `shape`) | varies by role (see [`04-surfaces/05-intent.md § 7`](../04-surfaces/05-intent.md#7-the-intent-fidelity-reviewer-agent-three-roles-three-verbs)) | varies by role | +| `documentation-auditor` | subagent (pre-pack, post-scaffold, pre-promotion) | design target — Phase 6 (disembark/embark) + itd-65 (launch pre-promotion) | source `docs/` directory or lifeboat `docs/` directory | `documentation-audit-.json` — invoked by disembark (pre-pack), embark (post-scaffold), and launch (pre-promotion). Subagent-only; not user-invoked. Lifted from legacy `~/ABCDevelopment/.claude/agents/documentation-auditor` | +| `reflection-composer` | reflect | design target — spc-83 (thin V1) | selected spc-66 phase-audit receipt (`.abcd/logbook/audit/phase-/report.json`) — per-bullet acceptance verdicts + `member_specs` + `done_total` | single JSON object with the five retrospective section keys (`went_well` / `could_improve` / `lessons_learned` / `decisions_made` / `metrics`); the deterministic reflect writer (`internal/core/reflect`) renders `.abcd/retrospectives//README.md`. Dispatched by `/abcd:reflect ` (itd-24). Phase-only grain. | ## `intent-fidelity-reviewer`'s three roles, three verbs @@ -27,9 +27,9 @@ The catalog row above declares one agent with three roles, sharing the agent's p 1. **Single-document fidelity → `/abcd:intent review `** (per the itd-1 discipline). **Inputs (updated by spc-3/itd-27):** shipped intent's press release + acceptance criteria + delivered reality + **`terminology/` glossary** (when present) + **frozen PRD at `.abcd/intents//prd.md`** (when present). **Outputs (updated by spc-3/itd-27):** per-criterion verdicts (MET/MET_WITH_CONCERNS/NOT_MET/INCONCLUSIVE) + three-bucket prose audit (honoured/diverged/missing) + **term-drift findings** (terms used in delivered reality that have drifted from `terminology/` canonical definitions) + **PRD-fidelity findings** (delivered reality vs the frozen PRD's user stories and implementation/testing decisions — what was honoured, diverged, or missing). **Two passes, two destinations:** the itd-1 acceptance pass (a shipped intent) writes per-criterion verdicts into the intent's own `## Audit Notes` (the verdict of record) plus a per-run `audit/review-/` logbook report; the itd-37 `MG004` pass (a native spec's `## Modification Grammar`) writes its `PASS`/`FAIL` verdict to an `audit/spec-mg-/` logbook receipt (native specs have no `## Audit Notes` section). For bundles, runs per-member-intent against the same delivered reality. The verb name aligns with the native review vocabulary `plan-review` / `impl-review` / `completion-review`; `audit` is reserved for the top-level `/abcd:audit` (compliance / hash-chain). **spc-12 ships the discipline-judgement subset only** — the itd-1 per-criterion acceptance verdicts and the itd-37 `MG004` boilerplate check, with their writers and receipts; the broader prose / term-drift / PRD-fidelity outputs above are **deferred** to a later spec. spc-12 ships the **manual** `/abcd:intent review` surface. spc-28 then shipped the **on-close lifecycle hook**: when a linked native spec closes, the intent moves `planned/` → `shipped/` and a review is **queued** on that transition (spc-28 also backfilled already-shipped intents that never had a review queued). What remains deferred is **automatic firing of the reviewer** off the queue — the move and the queue entry are produced automatically, but running `intent-fidelity-reviewer` on a queued entry is still a manual `/abcd:intent review ` step (spc-6 disowned auto-firing; no spec currently owns it). 2. **Cross-document fidelity → `/abcd:intent consistency []`** (introduced by itd-48, which superseded itd-31). Inputs: brief + every intent. Outputs: five judgement-category findings (terminology drift, premise contradictions, scope leakage, sequencing impossibilities, naming conflicts) at `.abcd/logbook/audit/consistency-/report.{json,md}`. spc-29 ships the judgement half on demand via `/abcd:intent consistency` (bare = whole corpus; with `` = one intent vs the rest). **Deferred follow-up** (recorded in `.work/issues.md` under `[spc-29 follow-up]`): the Role 2 mechanical half (schema/state contradictions, reference rot, acknowledgement gaps) and pre-commit hook scheduling that would let consistency findings block commits. -3. **Kind classification → `/abcd:intent shape []`** (introduced alongside the three intent kinds in itd-34). Inputs: intent corpus (cross-references, scope sections, supersession candidates). Outputs: suggested reclassifications across the three live `suggestion_type` values (`kind_change`, `bundle`, `supersession`) at `.abcd/logbook/audit/shape-/report.{json,md}`. spc-29 ships the on-demand surface only: `/abcd:intent shape` (bare = corpus; with `` = one intent). Bare `/abcd:intent` (status+help) *surfaces the latest cached shape suggestions* in its summary output — bare invocation never runs a fresh scan or mutates the report. User accepts via `/abcd:intent reclassify`; declined suggestions are logged so they aren't re-surfaced. Concurrency between any future scheduled invocation and the on-demand verb is mediated by `flock(2)` on `.abcd/coordination/shape.lock` — see `04-surfaces/05-intent.md § 6` for the contract. **Deferred follow-up** (recorded in `.work/issues.md` under `[spc-29 follow-up]`): pre-commit hook wiring for continuous shape scanning (`shape(...)`'s `mode="pre_commit"` parameter is preserved as a seam but no hook invokes it). +3. **Kind classification → `/abcd:intent shape []`** (introduced alongside the three intent kinds in itd-34). Inputs: intent corpus (cross-references, scope sections, supersession candidates). Outputs: suggested reclassifications across the three live `suggestion_type` values (`kind_change`, `bundle`, `supersession`) at `.abcd/logbook/audit/shape-/report.{json,md}`. spc-29 ships the on-demand surface only: `/abcd:intent shape` (bare = corpus; with `` = one intent). Bare `/abcd:intent` (status+help) *surfaces the latest cached shape suggestions* in its summary output — bare invocation never runs a fresh scan or mutates the report. User accepts via `/abcd:intent reclassify`; declined suggestions are logged so they aren't re-surfaced. Concurrency between any future scheduled invocation and the on-demand verb is mediated by `flock(2)` on `.abcd/coordination/shape.lock` — see `04-surfaces/05-intent.md § 7` for the contract. **Deferred follow-up** (recorded in `.work/issues.md` under `[spc-29 follow-up]`): pre-commit hook wiring for continuous shape scanning (`shape(...)`'s `mode="pre_commit"` parameter is preserved as a seam but no hook invokes it). -The `intent-fidelity-reviewer`'s three roles still share **one** catalog entry — the count grows by user-facing responsibility, not by role. The roster reached **16** when spc-83 added `reflection-composer` (the `/abcd:reflect` retrospective composer, itd-24) — a genuinely new user-facing responsibility, not a role of an existing agent. See [`04-surfaces/05-intent.md § 6`](../04-surfaces/05-intent.md#6-the-intent-fidelity-reviewer-agent-three-roles-three-verbs) for the user-facing description of the reviewer's roles. +The `intent-fidelity-reviewer`'s three roles still share **one** catalog entry — the count grows by user-facing responsibility, not by role. The roster reached **16** when spc-83 added `reflection-composer` (the `/abcd:reflect` retrospective composer, itd-24) — a genuinely new user-facing responsibility, not a role of an existing agent. See [`04-surfaces/05-intent.md § 7`](../04-surfaces/05-intent.md#7-the-intent-fidelity-reviewer-agent-three-roles-three-verbs) for the user-facing description of the reviewer's roles. ## Oracle backend resolution @@ -58,7 +58,7 @@ Two verdict-enum families are in play across abcd: **1. Review verdicts** (oracle reviews of plans, implementations, completions; emitted as `...` tags in oracle output): `{SHIP, NEEDS_WORK, MAJOR_RETHINK}`. This is abcd's native review-verdict enum and a **shared convention** at the `spec`/`run` seam boundary (adr-24, adr-26): a review gates a **receipt** in the native run loop (adr-27) or a wired peer loop alike, so any abcd-produced review is portable across the seam without a tool-specific validator. -**2. Per-criterion intent acceptance verdicts** (per itd-1, used by `intent-fidelity-reviewer`): `{MET, MET_WITH_CONCERNS, NOT_MET, INCONCLUSIVE}`. These describe whether each acceptance bullet was honoured; rollup logic lives in [`04-surfaces/05-intent.md § 6`](../04-surfaces/05-intent.md). Different category from review verdicts — review verdicts assess a *change*, criterion verdicts assess a *promise vs reality*. +**2. Per-criterion intent acceptance verdicts** (per itd-1, used by `intent-fidelity-reviewer`): `{MET, MET_WITH_CONCERNS, NOT_MET, INCONCLUSIVE}`. These describe whether each acceptance bullet was honoured; rollup logic lives in [`04-surfaces/05-intent.md § 7`](../04-surfaces/05-intent.md). Different category from review verdicts — review verdicts assess a *change*, criterion verdicts assess a *promise vs reality*. These two enums are deliberately disjoint and never mixed. Reviews emit family 1; auditors emit family 2. diff --git a/.abcd/development/brief/05-internals/04-universal-patterns.md b/.abcd/development/brief/05-internals/04-universal-patterns.md index a2169926..5eed1eb6 100644 --- a/.abcd/development/brief/05-internals/04-universal-patterns.md +++ b/.abcd/development/brief/05-internals/04-universal-patterns.md @@ -98,7 +98,7 @@ Every command emits `-report.json` (full structured detail) and `.{json,md} ``` -**Note: `.abcd/logbook/` is for reports only.** Coordination state (file locks like `shape.lock`, multi-agent claims per itd-33) lives at `.abcd/coordination/` — a *sibling* of `logbook/` under `.abcd/`, not a subdirectory. See `04-surfaces/05-intent.md § 6` for the canonical lock-path contract (`.abcd/coordination/shape.lock`). +**Note: `.abcd/logbook/` is for reports only.** Coordination state (file locks like `shape.lock`, multi-agent claims per itd-33) lives at `.abcd/coordination/` — a *sibling* of `logbook/` under `.abcd/`, not a subdirectory. See `04-surfaces/05-intent.md § 7` for the canonical lock-path contract (`.abcd/coordination/shape.lock`). **Later-phase additions to `.abcd/logbook/`** (appear when their parent intent ships): - `dredge//` — cross-corpus synthesis output (itd-25) diff --git a/.abcd/development/brief/05-internals/05-prompt-quality.md b/.abcd/development/brief/05-internals/05-prompt-quality.md index 4f717002..8fe55349 100644 --- a/.abcd/development/brief/05-internals/05-prompt-quality.md +++ b/.abcd/development/brief/05-internals/05-prompt-quality.md @@ -1,8 +1,8 @@ # Prompt Quality Infrastructure -15 agents = 15 prompt `.md` files. Static prompts rot as models evolve and prompting best practices shift. abcd ships three layers (B+C+D) plus the itd-5 additions: +16 agents = 16 prompt `.md` files (the canonical roster is [`01-agents.md`](01-agents.md)). Static prompts rot as models evolve and prompting best practices shift. abcd ships three layers (B+C+D) plus the itd-5 additions: -**B — Per-agent golden-test fixtures.** Each agent spec ships 2–3 fixture inputs with expected output structure (JSON schema validation + oracle-judged "is this output good enough"). Fixtures live in `agents//fixtures/`. **Shipped so far:** fixtures for `intent-fidelity-reviewer` only (the one agent that exists). The generic `internal/core/prompttest` harness that runs fixtures in CI is **design target** — it lands with the first Pass-A agent spec (Phase 4), the point at which a second agent exists to generalize the runner over. Catches regressions when models change. +**B — Per-agent golden-test fixtures.** Each agent spec ships 2–3 fixture inputs with expected output structure (JSON schema validation + oracle-judged "is this output good enough"). Fixtures live in `agents//fixtures/`. The `intent-fidelity-reviewer` fixtures are spc-12's; the generic `internal/core/prompttest` harness that runs fixtures in CI lands with the first Pass-A agent spec ([Phase 6](../../roadmap/phases/phase-6-lifeboat.md), the lifeboat pipeline), the point at which a second agent exists to generalize the runner over. Catches regressions when models change. **C — Prompt linter.** the prompt-lint checks in `internal/core/lint` — static analysis of agent prompt files (`agents/.md`, excluding `CHANGELOG.md`, `README.md`, and `*_template.md` / `*.template` files, which are not prompts). diff --git a/.abcd/development/brief/05-internals/07-memory.md b/.abcd/development/brief/05-internals/07-memory.md index 3e8bdf15..165df299 100644 --- a/.abcd/development/brief/05-internals/07-memory.md +++ b/.abcd/development/brief/05-internals/07-memory.md @@ -106,7 +106,7 @@ recall: [, ...] **Curator rules** (enforced by `principle-distiller` + lint): -- Pages with single-source-class synthesis are flagged as **low cross-validation** (advisory, lint code `MS001`; not blocking). Surfaces in `/abcd:memory lint` (spc-39 — shipped). +- Pages with single-source-class synthesis are flagged as **low cross-validation** (advisory, lint code `MS001`; not blocking). Surfaces in `/abcd:memory lint` (spc-39). - Pages mixing source classes (e.g., `session_memory` + `external_pdf`) require a `weighting_note` field acknowledging the asymmetric trust gradient between class types. Lint blocks (lint code `MS002`) until the note is added. - Pages with `class: external_*` without a `licence` field block at lint (lint code `ML001`). `unknown` is acceptable — must be explicit. @@ -165,7 +165,7 @@ User-facing surface (per itd-36): | Bare `/abcd:memory` | Status + help + render of current memory state (page count by class, last-ingest timestamp, recent contradictions). Per the [bare-command-as-render discipline](../02-constraints/04-naming.md). Quotation-budget headroom renders per external source READ-ONLY from the spc-39 `.coverage_index.json`: a fingerprint-fresh index shows per-source warn/block headroom, fingerprint drift shows a "stale — run /abcd:memory lint" hint, an absent index an info line, and a malformed index/crawl failure a non-fatal "headroom unavailable" line. The bare render never rebuilds or mutates the index (the `lint` sub-verb is the sole writer). | | `/abcd:memory ingest ` | Read external source, distil into typed pages with citation, append to log. Default: do NOT store original. Flag: `--keep-original` (opt-in storage; the lifeboat licence-gate allowlist is required before a kept original could ever publish — via `/abcd:disembark`, not launch; adr-18). | | `/abcd:memory ask ` | Query memory by domain + class; synthesise answer with citations; optionally file result back. | -| `/abcd:memory lint` **(spc-39 — shipped)** | Full-store curator health-check: ALWAYS crawls the whole repo store (the cumulative `MQ002` needs the full corpus), runs the `MQ`/`MS`/`ML` family (`MQ001`/`MQ002`/`MQ003` quotation budgets + coverage, `MS001`/`MS002` source-class advisories, `ML001` missing licences), rebuilds the regenerable `.coverage_index.json`, and writes `.abcd/logbook/memory/lint-/report.{json,md}`. Mutates NO memory-store state — the coverage index + logbook report are its only writes. Exit: blockers → nonzero; warn-only → exit 0 (curator advisory; the recorded divergence from the standalone grammar, see [`06-lint.md §2`](06-lint.md#2-severity-model)). **Not part of spc-39:** contradiction surfacing is RENDERED by spc-38's reconciliation into `contradictions.md` (surfaced by the bare render, not lint-coded), and orphan/stale-claim audits are DEFERRED to a later intent — `lint` runs neither. | +| `/abcd:memory lint` **(spc-39)** | Full-store curator health-check: ALWAYS crawls the whole repo store (the cumulative `MQ002` needs the full corpus), runs the `MQ`/`MS`/`ML` family (`MQ001`/`MQ002`/`MQ003` quotation budgets + coverage, `MS001`/`MS002` source-class advisories, `ML001` missing licences), rebuilds the regenerable `.coverage_index.json`, and writes `.abcd/logbook/memory/lint-/report.{json,md}`. Mutates NO memory-store state — the coverage index + logbook report are its only writes. Exit: blockers → nonzero; warn-only → exit 0 (curator advisory; the recorded divergence from the standalone grammar, see [`06-lint.md §2`](06-lint.md#2-severity-model)). **Not part of spc-39:** contradiction surfacing is RENDERED by spc-38's reconciliation into `contradictions.md` (surfaced by the bare render, not lint-coded), and orphan/stale-claim audits are DEFERRED to a later intent — `lint` runs neither. | ## 8. Cross-cutting integration diff --git a/.abcd/development/brief/06-delivery/02-verification-matrix.md b/.abcd/development/brief/06-delivery/02-verification-matrix.md index 72a20b52..b5b366c6 100644 --- a/.abcd/development/brief/06-delivery/02-verification-matrix.md +++ b/.abcd/development/brief/06-delivery/02-verification-matrix.md @@ -32,7 +32,7 @@ | Launch curated release (single repo) | Packaging **excludes `.abcd/**`** from the release artifact; a `/abcd:launch dry-run` proves nothing under `.abcd/` appears in the artifact manifest (adr-28). There is no second repo — the cut is a build-time filter over one tree | | Launch manifest | Correct include/exclude; `.abcd/launch.allow` honoured | | Launch branch mode | `--mode=branch` → `launch/` branch; main untouched | -| Launch version stamp | Default patch bump; `--version` override; the version is stamped into the **curated release artifact** at cut time (the working tree stays unversioned — adr-19/adr-20 polarity on one tree); `marketplace.json` updated | +| Launch version stamp | Bump tier derived from shipped intents' `impact` with the surface-diff guardrail (adr-31); the version is stamped into the **curated release artifact** at cut time (the working tree stays unversioned — adr-19/adr-20 polarity on one tree); `marketplace.json` updated | | Launch documentation-auditor | docs/ inspected; warn-fail surfaces user prompt before proceeding | | Asset discovery | Prompt fires when assets found; user-supplied paths merged into curator input; `_provenance.json` records origin | | Intent capture | `/abcd:intent ""` (canonical bare quoted create, per spc-30/itd-46) runs interview → writes `intents/drafts/itd-N-.md` with press-release content + persona quote + acceptance criteria (per itd-1) | 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 a88cfc25..e0fd98ab 100644 --- a/.abcd/development/brief/06-delivery/03-out-of-scope.md +++ b/.abcd/development/brief/06-delivery/03-out-of-scope.md @@ -1,26 +1,18 @@ # Out of Phase Scope -This brief describes the work bundled into the six planned phases (see [`roadmap/phases/README.md`](../../roadmap/phases/README.md)). **All later-phase items live as press-release intents** in `.abcd/development/intents/drafts/` — see [intents/README.md](../../intents/README.md) for the full index. +This brief describes the work bundled into the seven planned phases (see [`roadmap/phases/README.md`](../../roadmap/phases/README.md)). **Later-phase items live as press-release intents**: the uncommitted bench in `.abcd/development/intents/drafts/` (enumerated below), and the committed-but-unscheduled intents in `planned/` — valid per [adr-34](../../decisions/adrs/0034-lifecycle-and-scheduling-orthogonal.md), listed in [intents/README.md](../../intents/README.md) § Planned, and scheduled when a phase doc's `## Scope` names them. -**In a later phase.** The set below is the live `drafts/` corpus minus the -intents already scoped into a planned phase (a phase doc's `## Scope` section is -the single source of truth for which intents a phase bundles — see -[adr-9](../../decisions/adrs/0009-phase-as-product-layer.md)). It is **not** -hand-counted: derive set membership from the filesystem and subtract the -phased-in IDs, rather than maintaining a total that re-drifts — +**In a later phase.** The set below is the live `drafts/` corpus — the +uncommitted bench. Per +[adr-34](../../decisions/adrs/0034-lifecycle-and-scheduling-orthogonal.md) no +phase-scoped intent lives in `drafts/` (scheduled ⇒ `planned/`), so there is +nothing to subtract: the filesystem is the list, and it is **not** +hand-counted — ```sh -# Live later-phase IDs = drafts minus phased-in. -# The command globs ONLY drafts/, so intents that have already left drafts/ for -# planned/ | shipped/ | disciplines/ (e.g. itd-6 planned, itd-27/28 planned, -# itd-37 a discipline, and itd-20/24/63/69 planned under spc-83) are excluded by -# the filesystem itself — they can never appear in the output. The exclusion list -# below is therefore ONLY the phased-in IDs that are STILL physically in drafts/ -# (lifecycle move pending): itd-2,3,4,7 -# (phase-0/1/2 scoped) and itd-34,36,40,42 (later phased-in, captured post-brief). +# Live later-phase (uncommitted bench) IDs = the drafts/ corpus, no exclusions. ls .abcd/development/intents/drafts/itd-*.md \ - | sed -E 's#.*/(itd-[0-9]+).*#\1#' | sort -V -u \ - | grep -vxE 'itd-(2|3|4|7|34|36|40|42)' + | sed -E 's#.*/(itd-[0-9]+).*#\1#' | sort -V -u ``` Intents that have left `drafts/` (moved to `planned/`, `shipped/`, `superseded/`, @@ -51,15 +43,24 @@ in the historical note at the end of this section, not here.) - itd-35 — `/abcd:audit lifeboat ` lifeboat-integrity verification (sibling sub-verb under itd-16's umbrella; captured 2026-05-08) - itd-39 — Scope-aware memory retrieval (extends itd-3's recall hook to the memory store) - itd-41 — Phase negotiator — Socratic phase-proposer (per [adr-10](../../decisions/adrs/0010-phase-negotiator-grounded-tradeoffs.md)) -- itd-43 — Spec-terminology rename (one canonical word for a specced block of work) — the remaining surface/prose/glossary sweep (lint enforcement + prose sweep); the atomic `epic_id`→`spec_id` field rename ([adr-11](../../decisions/adrs/0011-spec-terminology-rename.md)) is a separate concern. - itd-44 — A fourth intent kind for infrastructure choices the product thinker wants to record - `.work/issues.md` cleanup bundle (sweep the workshop before a later phase) -- itd-47 — oracle-backed gates pass honestly without a human in the loop (not yet shipped) +- itd-47 — oracle-backed gates pass honestly without a human in the loop - itd-51 — Harness-adoption-readiness rubric ("safe enough to adopt" before a new harness arrives) - abcd warns when you reach past it into a tool it was built to hide — **obsolete under no-hard-deps ([adr-22](../../decisions/adrs/0022-bundled-deps-as-pluggable-adapters.md))**: with native defaults there is no wrapped foreign surface to reach past; the abstraction boundary is retired - abcd's largest source files become navigable packages without changing behavior - itd-55 — abcd can tell whether its own reasoning rests on bedrock or an unexamined assumption - One command re-vendors upstream and restores the abcd overlay in a single guarded step — **obsolete under no-hard-deps ([adr-22](../../decisions/adrs/0022-bundled-deps-as-pluggable-adapters.md))**: no external tool re-vendors itself onto abcd's state, so there is no overlay to re-apply +- itd-57 — Manual-hold sentinel blocking a spec from autonomous pickup until a human lifts it +- itd-59 — Autonomous-run passes leave the same durable, queryable transcript an interactive session does +- itd-60 — Doc-fidelity anti-drift: a spec cannot close until the brief and public docs reflect what was built +- itd-61 — Brief-change derivation: a human brief edit reconciles its implied intents and principles before commit +- itd-62 — Pluggable fail-closed safety gate wrapping a trusted scanner +- itd-64 — Benchmark-driven configuration optimisation from abcd's own runs +- itd-70 — Launch release retention (newest-per-line prune of superseded releases) +- itd-73 — Derived versioning: the release number is computed, never typed (per [adr-31](../../decisions/adrs/0031-derived-versioning-from-intents.md)) +- itd-74 — Name banlist: banned names kept out of everything published +- itd-75 — CLI eval harness: fixture-driven proof the CLI actually runs **Phased-in additions captured post-brief (2026-05-07):** itd-27 (`/abcd:intent grill` sub-verb + glossary), itd-28 (spec-tied reviews in the native spec review store), and itd-34 (three intent kinds with three lifecycle paths) were captured after this brief was written and are scoped into the planned phases. They are listed in `intents/README.md` and the relevant phase docs; this section is canonical for **later-phase** items only and does not enumerate phased-in intents. diff --git a/.abcd/development/brief/06-delivery/README.md b/.abcd/development/brief/06-delivery/README.md index 450e517a..5a67794c 100644 --- a/.abcd/development/brief/06-delivery/README.md +++ b/.abcd/development/brief/06-delivery/README.md @@ -8,6 +8,6 @@ press-release intents in [`intents/drafts/`](../../intents/drafts). |---|---|---| | 1 | [`01-build-sequence.md`](01-build-sequence.md) | The delivery order (MVP → the companion harness → Claude Code) and what ships in each step | | 2 | [`02-verification-matrix.md`](02-verification-matrix.md) | Test coverage across the command surfaces | -| 3 | [`03-out-of-scope.md`](03-out-of-scope.md) | What sits outside the six planned phases, and where those items are tracked | +| 3 | [`03-out-of-scope.md`](03-out-of-scope.md) | What sits outside the seven planned phases, and where those items are tracked | For the chapters around this one, see the [brief index](../README.md). diff --git a/.abcd/development/brief/README.md b/.abcd/development/brief/README.md index b495d914..89713fc4 100644 --- a/.abcd/development/brief/README.md +++ b/.abcd/development/brief/README.md @@ -4,6 +4,15 @@ This is the canonical design brief for the abcd plug-in. The brief reflects the It is split across numbered folders for concurrent editing, diff legibility, and agent-context-budget friendliness. +> **Delivery-state provenance.** `spc-N` references throughout the brief trace +> the predecessor implementation's spec store, carried as design input for this +> from-scratch Go rebuild. They attribute *which spec owns which behaviour*; +> they are not delivery claims. In this repo nothing is shipped until its +> intent reaches `intents/shipped/` (see +> [`intents/README.md`](../intents/README.md)), and current delivery state +> lives in the roadmap dashboard, never in brief prose (per +> [adr-5](../decisions/adrs/0005-brief-is-current-state.md)). + > **Naming and structural conventions:** see [`00-meta.md`](00-meta.md). It explains why this directory uses numbered folders and the brief↔lifeboat shape contract. ## Navigation diff --git a/.abcd/development/brief/glossary/README.md b/.abcd/development/brief/glossary/README.md index cf7e180f..4300199a 100644 --- a/.abcd/development/brief/glossary/README.md +++ b/.abcd/development/brief/glossary/README.md @@ -47,7 +47,7 @@ provides narrative context, examples, and cross-references. ## Directory Layout ``` -terminology/ +glossary/ ← .abcd/development/brief/glossary/ (the home, per adr-30) ├── README.md ← this file (format spec + index) ├── _template.md ← copy this when adding new terms ├── core/ ← terms that apply across all abcd bounded contexts diff --git a/.abcd/development/decisions/adrs/0033-launch-phase-ownership-tiered.md b/.abcd/development/decisions/adrs/0033-launch-phase-ownership-tiered.md new file mode 100644 index 00000000..9f7e8049 --- /dev/null +++ b/.abcd/development/decisions/adrs/0033-launch-phase-ownership-tiered.md @@ -0,0 +1,85 @@ +--- +id: adr-33 +slug: launch-phase-ownership-tiered +status: accepted +date: 2026-07-08 +supersedes: null +superseded_by: null +related_intents: [itd-65, itd-66, itd-70, itd-72, itd-73] +related_rfcs: [] +related_adrs: [adr-9, adr-28, adr-31] +--- + +# ADR-33: Launch phase ownership is tiered; the phase index is the sole ownership source + +## Context + +The record disagreed about which phase owns `/abcd:launch`. The roadmap +(`phases/phase-1-ahoy.md`, `phases/README.md`) and the brief's build sequence +(`06-delivery/01-build-sequence.md`) make **install + launch the first +milestone** — Phase 1 cuts a curated single-repo release. But +`brief/04-surfaces/04-launch.md` opened with "builds in Phase 5 (round-trip and +ship)", and `05-internals/01-agents.md` anchored launch agents to "Phase 5". + +"Phase 5 (round-trip and ship)" is the **pre-rebuild six-phase numbering**, in +which the final phase bundled the lifeboat round-trip *and* the release flow. +The current roadmap has seven phases (0–6): the round-trip is Phase 6, and the +release cut moved forward to Phase 1 as the MVP proof of the packaging path. The +stale banner survived the copy of the design record; an implementer reading only +the brief would schedule launch five phases late. (Captured as `iss-1`; the +sibling six-vs-seven-phase and disembark/embark-banner findings are `iss-4` and +`iss-5`.) + +There is also a real distinction the stale banner was gesturing at: the *full* +launch flow (pre-flight gate suite, render parity, tier-b publishing, retention, +derived versioning) is deliberately not Phase 1 work. + +## Decision + +1. **The roadmap phase index is the sole source of phase numbering and phase + ownership.** `roadmap/phases/README.md` (Phases 0–6) and each phase doc's + `## Scope` own the mapping (per adr-9). A brief file states phase ownership + only by pointing at the owning phase doc — never with its own phase number + that can drift. The six-phase "Phase 0–5, round-trip-and-ship last" + numbering is superseded. + +2. **Launch ownership is tiered.** **Phase 1 owns the curated-release cut**: + packaging from the one repo with `.abcd/**` excluded, the secret/PII scan + gate, and the bootstrap release path (adr-28). The **launch deepenings are + separately scheduled intents** — the full pre-flight gate suite (itd-65), + payload render parity (itd-66), release retention (itd-70), tier-b + publishing (itd-72), and derived versioning (itd-73) — each entering a + phase's `## Scope` when sequenced, unscheduled until then (adr-9's + unscheduled-intent rule). + +3. **Deepened behaviour is attributed to its intent, not a phase number.** + Where `04-surfaces/04-launch.md` describes behaviour beyond the Phase 1 cut, + it names the owning intent (e.g. "the gate suite is itd-65's"), so the doc + stays correct however those intents are sequenced. + +## Alternatives Considered + +- **Keep launch whole and late (the banner's reading).** Rejected: it + contradicts the first-milestone MVP logic — install + launch is what proves + the Go core, adapter seams, and packaging path end to end (build sequence, + phase-1 doc), and the packaging boundary is the highest-risk privacy surface, + so it ships first, not last. +- **Make Phase 1 own the full launch flow.** Rejected: the gate suite and + versioning automation depend on stores and machinery from later phases (the + native spec store for intent-impact derivation, adr-31), and pinning them to + Phase 1 would either stall the milestone or ship them hollow. +- **Renumber the brief's banners to "Phase 6".** Rejected: it repairs the + number but keeps duplicated phase ownership in the brief, which is the drift + mechanism itself. Ownership statements live once, in the phase index. + +## Consequences + +- `04-surfaces/04-launch.md` loses its "builds in Phase 5" banner in favour of + a phase-ownership pointer (Phase 1 cut + intent-attributed deepenings); + in-body "Phase-5 `ship`" references become intent attributions. +- `05-internals/01-agents.md` anchors `launch-gatekeeper` to itd-65 rather than + a phase number. +- The six-vs-seven phase count and the disembark/embark banners (`iss-4`, + `iss-5`) now have their canonical basis: seven phases, ownership per the + phase index. +- Future phase renumbering touches exactly one file, the phase index. diff --git a/.abcd/development/decisions/adrs/0034-lifecycle-and-scheduling-orthogonal.md b/.abcd/development/decisions/adrs/0034-lifecycle-and-scheduling-orthogonal.md new file mode 100644 index 00000000..f29a5479 --- /dev/null +++ b/.abcd/development/decisions/adrs/0034-lifecycle-and-scheduling-orthogonal.md @@ -0,0 +1,82 @@ +--- +id: adr-34 +slug: lifecycle-and-scheduling-orthogonal +status: accepted +date: 2026-07-08 +supersedes: null +superseded_by: null +related_intents: [itd-7, itd-43] +related_rfcs: [] +related_adrs: [adr-3, adr-9, adr-33] +--- + +# ADR-34: Intent lifecycle and phase scheduling are orthogonal axes + +## Context + +The record carried two contradicting definitions of what `intents/planned/` +means. `intents/README.md` defined it as "scoped into a roadmap phase", but the +corpus disagreed in both directions: most planned intents (itd-20, itd-24, +itd-29, itd-46, itd-48, itd-49, itd-50, itd-53, itd-58, itd-63, itd-65, itd-66, +itd-67, itd-69, itd-72) appear in no phase doc's `## Scope`, while two intents +named in a phase `## Scope` (itd-43 in Phase 0, itd-7 in Phase 6) still lived in +`drafts/`. With "planned", "phased", and "draft" disagreeing, the roadmap cannot +be used as a scheduler. (Captured as `iss-3`.) + +The same README's own sequencing section already states the opposing model — +"an intent listed in no phase doc's `## Scope` is implicitly unscheduled" is a +valid state (per adr-9) — so the record was contradicting itself, not merely +drifting from the corpus. + +## Decision + +1. **Two orthogonal axes.** An intent's **lifecycle** is its commitment state, + carried by directory location (adr-3): `drafts/` = captured, uncommitted; + `planned/` = committed to build; `shipped/` = built. An intent's + **scheduling** is phase membership, carried editorially by a phase doc's + `## Scope` (adr-9). Neither axis is derived from the other. + +2. **One directional invariant: scheduled ⇒ committed.** Any intent named in a + phase doc's `## Scope` is committed by definition, so it lives in `planned/` + (or `disciplines/` for discipline-kind intents). The converse does not hold: + a planned intent with no phase is **committed but unscheduled** — a valid + state, the committed bench awaiting sequencing (adr-9's unscheduled-intent + rule, now explicitly extended beyond `drafts/`). + +3. **Applied to the corpus.** itd-43 (Phase 0 `## Scope`) and itd-7 (Phase 6 + `## Scope`) move `drafts/` → `planned/`; the fifteen planned-but-unscheduled + intents stay where they are, now legally. `intents/README.md`'s `planned/` + definition drops the "scoped into a roadmap phase" clause. + +4. **Enumerations derive from the axes, not from each other.** Any "later + phase" or "out of scope" list is derived from `## Scope` membership (the + scheduling axis), never from the `drafts/` directory (the lifecycle axis) — + the two sets are different by design. + +## Alternatives Considered + +- **`planned/` = phased (enforce the README's old definition).** Rejected: it + forces every committed-but-unsequenced intent back to `drafts/`, erasing the + commitment signal, or forces premature phase authoring just to keep files in + place — exactly the stale forecasting the phases README refuses ("naming + which intents land in which future phase before the phase is planned would + only go stale"). +- **A `scheduled:` frontmatter field on intents.** Rejected: duplicates the + phase docs' `## Scope` (adr-9 made that mapping editorial and single-sourced) + and reintroduces the stored-status drift adr-3/adr-5 exist to prevent. +- **Full orthogonality with no invariant (a phase may bundle a draft).** + Rejected: a phase `## Scope` is a commitment to build; letting it name an + uncommitted draft makes "committed" unreadable from either axis. + +## Consequences + +- itd-43 and itd-7 relocate to `planned/`; `intent_lint`-style checks can later + enforce the scheduled ⇒ committed invariant mechanically. +- `intents/README.md` describes `planned/` as committed (scheduled or awaiting + sequencing) and its directory listings match disk. +- The out-of-scope/later-phase enumeration (`brief/06-delivery/03-out-of-scope.md`) + is regenerated from `## Scope` membership rather than the drafts directory — + tracked as `iss-8`. +- Hand-maintained intent counts keyed to "phased intents" + (`brief/01-product/04-scope.md`) are re-derived on the scheduling axis — + tracked as `iss-7`. diff --git a/.abcd/development/decisions/adrs/README.md b/.abcd/development/decisions/adrs/README.md index 89b9d525..b3cef8ee 100644 --- a/.abcd/development/decisions/adrs/README.md +++ b/.abcd/development/decisions/adrs/README.md @@ -134,3 +134,5 @@ The intent lint (a Go implementation) extends to verify these reciprocally. | [adr-30](0030-record-information-architecture.md) | Design-record information architecture — flat artefact-type folders | accepted | 2026-07-06 | | [adr-31](0031-derived-versioning-from-intents.md) | The release version is derived from the intents in it, never authored (extends adr-19, adr-20) | accepted | 2026-07-07 | | [adr-32](0032-issue-ledger-is-working-tier-data.md) | The issue ledger is working-tier data, not authored record — move to `.abcd/work/issues/`, drop git-inferable timestamps, derive priority | accepted | 2026-07-08 | +| [adr-33](0033-launch-phase-ownership-tiered.md) | Launch phase ownership is tiered — Phase 1 owns the curated-release cut; deepenings are separately scheduled intents; the phase index is the sole ownership source | accepted | 2026-07-08 | +| [adr-34](0034-lifecycle-and-scheduling-orthogonal.md) | Intent lifecycle and phase scheduling are orthogonal axes — scheduled ⇒ committed (`planned/`), but planned intents may be unscheduled | accepted | 2026-07-08 | diff --git a/.abcd/development/intents/README.md b/.abcd/development/intents/README.md index 65753fc6..f4712d7e 100644 --- a/.abcd/development/intents/README.md +++ b/.abcd/development/intents/README.md @@ -51,7 +51,7 @@ The kind is **project-agnostic** — application projects (e.g., a macOS app und | Directory | Status / role | Meaning | |---|---|---| | `drafts/` | 📝 Draft | Press-release-shaped intent captured but no native spec yet. Bench of ideas / forward-looking work. Cheap to draft and discard. | -| `planned/` | 📅 Planned | A committed capability, scoped into a roadmap phase and awaiting its Go build. `spec_id` is `null` until the native spec layer schedules it (Phase 4), then points at a `spc-N`; bundle-member intents share a `spec_id` with their bundle-mates. | +| `planned/` | 📅 Planned | A committed capability awaiting its Go build — scheduled into a roadmap phase, or committed-but-unscheduled awaiting sequencing (the two axes are orthogonal, per [adr-34](../decisions/adrs/0034-lifecycle-and-scheduling-orthogonal.md)). `spec_id` is `null` until the native spec layer schedules it (Phase 4), then points at a `spc-N`; bundle-member intents share a `spec_id` with their bundle-mates. | | `shipped/` | ✅ Shipped | Linked spec closed; `intent-fidelity-reviewer` ran. The intent's "Audit Notes" section contains per-criterion verdicts (per the itd-1 discipline) plus a three-bucket prose audit. | | `disciplines/` | 📐 Active rule | Discipline-kind intents. Never get a native spec of their own; instead they impose acceptance gates that every *other* spec inherits and is checked against. **No `status` frontmatter field — the directory IS the state.** | | `superseded/` | 🗄️ Superseded | Intents killed by reclassification or absorption. The file records `superseded_by: ` (the successor) AND `kind_at_supersession: ` (what shape the intent had when retired). Preserved as historical record. | @@ -231,7 +231,7 @@ This is also a codified abcd principle: never use real names in press releases ( ## Sequencing — see `phases/` -Which intents a phase bundles, and in what order phases ship, is **not recorded here.** Sequencing lives in the phase docs at [`../phases/`](../roadmap/phases) — each phase doc's `## Scope` section is the single source of truth (per [adr-9](../decisions/adrs/0009-phase-as-product-layer.md)). An intent listed in no phase doc's `## Scope` is implicitly **unscheduled** — a `drafts/` bench item, captured but not yet sequenced. +Which intents a phase bundles, and in what order phases ship, is **not recorded here.** Sequencing lives in the phase docs at [`../phases/`](../roadmap/phases) — each phase doc's `## Scope` section is the single source of truth (per [adr-9](../decisions/adrs/0009-phase-as-product-layer.md)). An intent listed in no phase doc's `## Scope` is implicitly **unscheduled** — valid for `drafts/` and `planned/` alike: a draft is uncommitted, an unscheduled planned intent is committed but awaiting sequencing. The invariant runs one way only: any intent a phase `## Scope` names is committed by definition and lives in `planned/` (or `disciplines/`) — see [adr-34](../decisions/adrs/0034-lifecycle-and-scheduling-orthogonal.md). This README describes the intent corpus by *lifecycle state* (the directory listings below); it deliberately does not duplicate the phase→intent mapping. @@ -257,7 +257,6 @@ Captured intents that haven't been promoted to native specs yet. Each standalone ``` drafts/ -├── itd-7-rp-workspace-portability.md ├── itd-8-with-code-bundling.md ├── itd-9-schema-migration.md ├── itd-10-purge-uninstall.md @@ -282,7 +281,6 @@ drafts/ ├── itd-35-lifeboat-integrity-audit.md (sibling to itd-16) ├── itd-39-scope-aware-memory-retrieval.md (extends itd-3 recall hook to memory) ├── itd-41-phase-negotiator.md (Socratic phase-proposer, per adr-10) -├── itd-43-epic-to-spec-terminology.md ├── itd-44-fourth-intent-kind-decision.md ├── itd-47-oracle-gates-autonomous-mode.md ├── itd-51-harness-adoption-readiness-rubric.md @@ -294,7 +292,9 @@ drafts/ ├── itd-62-pluggable-safety-gate.md ├── itd-64-benchmark-driven-config-optimization.md ├── itd-70-launch-release-retention-newest-per-line.md -└── itd-73-derived-versioning.md +├── itd-73-derived-versioning.md +├── itd-74-name-banlist.md +└── itd-75-cli-eval-harness.md ``` --- @@ -318,7 +318,7 @@ See [`brief/04-surfaces/05-intent.md § 1`](../brief/04-surfaces/05-intent.md#1- ## Planned -`planned/` holds the committed capabilities — the intents scoped into the roadmap phases and awaiting their Go build. Their `spec_id` is `null` until the spec layer schedules them (Phase 4). +`planned/` holds the committed capabilities awaiting their Go build — some scheduled into a roadmap phase, others committed but not yet sequenced (per [adr-34](../decisions/adrs/0034-lifecycle-and-scheduling-orthogonal.md)). Their `spec_id` is `null` until the spec layer schedules them (Phase 4). ``` planned/ @@ -326,6 +326,7 @@ planned/ ├── itd-3-modular-rules-loader.md ├── itd-4-issue-capture.md ├── itd-6-rp-mcp-only-integration.md +├── itd-7-rp-workspace-portability.md ├── itd-20-top-level-abcd-dispatcher.md ├── itd-24-reflect-command.md ├── itd-27-grill-skill-and-glossary.md @@ -335,6 +336,7 @@ planned/ ├── itd-36-memory-unification.md ├── itd-40-folder-classification.md ├── itd-42-coherence-aware-grill.md +├── itd-43-epic-to-spec-terminology.md ├── itd-46-abcd-intent-quoted-text-create-symmetric.md ├── itd-48-intent-fidelity-reviewer-roles-2-3.md ├── itd-49-flow-state-drift-detector.md diff --git a/.abcd/development/intents/disciplines/itd-1-acceptance-gates.md b/.abcd/development/intents/disciplines/itd-1-acceptance-gates.md index 2f1ec01c..9eef9246 100644 --- a/.abcd/development/intents/disciplines/itd-1-acceptance-gates.md +++ b/.abcd/development/intents/disciplines/itd-1-acceptance-gates.md @@ -71,7 +71,7 @@ This is a small schema bump with a large quality return. Every intent gets a mea ## Open Questions - **Lint strictness on existing drafts** — pre-discipline drafts (already grandfathered above) may have malformed AC sections rather than missing ones. Should `/abcd:intent plan` warn-and-prompt or hard-block in that case? (Recommend: hard-block. The whole point is to force the discipline. Backfill happens at the user's own pace via `/abcd:intent refine`.) -- **Verdict-rollup logic** — lives in [`brief/04-surfaces/05-intent.md § 6`](../../brief/04-surfaces/05-intent.md#6-the-intent-fidelity-reviewer-agent-three-roles) (SSOT). Don't duplicate here. +- **Verdict-rollup logic** — lives in [`brief/04-surfaces/05-intent.md § 7`](../../brief/04-surfaces/05-intent.md#7-the-intent-fidelity-reviewer-agent-three-roles-three-verbs) (SSOT). Don't duplicate here. - **How many criteria are too many?** — 1 minimum is enforced; 5+ may indicate the intent is too big and should split. Document as a soft guideline, not a lint. - **Criterion language** — strict Given-When-Then only, or allow plain bullet criteria as a fallback? (Recommend: strict. Plain bullets are what scope sections already provide; criteria need to be observable, not aspirational.) - **Discipline-specific AC shape** — disciplines describe rules, not deliverables. Should their `## Acceptance Criteria` describe how the *rule* is verified (e.g., "Given an intent without AC, when plan runs, then it fails") rather than what the deliverable is? (Recommend: yes, explicit in the discipline template; this discipline's own AC above is a worked example.) diff --git a/.abcd/development/intents/drafts/itd-43-epic-to-spec-terminology.md b/.abcd/development/intents/planned/itd-43-epic-to-spec-terminology.md similarity index 99% rename from .abcd/development/intents/drafts/itd-43-epic-to-spec-terminology.md rename to .abcd/development/intents/planned/itd-43-epic-to-spec-terminology.md index 4aa96950..c3692fe9 100644 --- a/.abcd/development/intents/drafts/itd-43-epic-to-spec-terminology.md +++ b/.abcd/development/intents/planned/itd-43-epic-to-spec-terminology.md @@ -2,8 +2,8 @@ id: itd-43 slug: epic-to-spec-terminology spec_id: null -kind: null -suggested_kind: standalone +kind: standalone +suggested_kind: null reclassification_history: [] related_adrs: [adr-26] prd_path: null diff --git a/.abcd/development/intents/drafts/itd-7-rp-workspace-portability.md b/.abcd/development/intents/planned/itd-7-rp-workspace-portability.md similarity index 100% rename from .abcd/development/intents/drafts/itd-7-rp-workspace-portability.md rename to .abcd/development/intents/planned/itd-7-rp-workspace-portability.md diff --git a/.abcd/development/roadmap/README.md b/.abcd/development/roadmap/README.md index 33ba2264..b1e3dd9e 100644 --- a/.abcd/development/roadmap/README.md +++ b/.abcd/development/roadmap/README.md @@ -23,9 +23,12 @@ they replace plugin-version language (`v1`, `v2`). See format under `intents/{drafts,planned,shipped,disciplines,superseded}/`. An intent's phase membership is recorded editorially in the owning phase doc's `## Scope`, not in intent frontmatter. -- **Plugin releases**: tracked by `.claude-plugin/plugin.json` `version`. A - release version is an *output* of completing a phase, never an input that - organises work. +- **Plugin releases**: tracked by the `v*` tag on the released artefact — the + working tree carries no version + ([adr-19](../decisions/adrs/0019-plugin-json-version-carve-out.md)). The + number is *derived* from the intents shipped since the previous release + ([adr-31](../decisions/adrs/0031-derived-versioning-from-intents.md)): an + output of cutting a release, never an input that organises work. The brief is not re-versioned per release; it stays the canonical current-state record. What has shipped is defined by which phases are complete and which @@ -35,7 +38,7 @@ intents are in `shipped/`. ## Current State -**Plugin v1** — in active design and implementation. The brief at [`../brief/README.md`](../brief/README.md) is the source of truth. +**In active design and implementation** — phases, not version numbers, are the sequencing axis. The brief at [`../brief/README.md`](../brief/README.md) is the source of truth. This dashboard does **not** hand-maintain spec or intent counts — they drift the moment work ships. Status is read live from the **native spec store** (specs, via diff --git a/.abcd/development/roadmap/phases/README.md b/.abcd/development/roadmap/phases/README.md index bbc04a6b..50d5157f 100644 --- a/.abcd/development/roadmap/phases/README.md +++ b/.abcd/development/roadmap/phases/README.md @@ -67,8 +67,11 @@ that backend is attached) via the Go CLI. Phases 1–6 are organised by **user-capability moment** — each one ends in a milestone a contributor can demo. **Install and launch (Phase 1) is the first milestone**, and the delivery order is MVP → the companion harness → Claude Code. Phase 0 is -the exception: it has no user-facing command, and is numbered 0 to say so -honestly — it is the floor the capability phases stand on. Phases are sequenced +the exception: it delivers no product-capability user moment, and is numbered 0 +to say so honestly — it is the floor the capability phases stand on. (It does +carry one user-typed verb, the `/abcd:intent review` discipline-audit sub-verb — +the substrate inspecting itself, not a product capability; see +[phase-0-substrate.md](phase-0-substrate.md) for the qualifier.) Phases are sequenced but their *contents* may run in any dependency-respecting order — see each phase's `## Dependency rationale`. diff --git a/.abcd/development/roadmap/phases/phase-3-intent.md b/.abcd/development/roadmap/phases/phase-3-intent.md index 960fe41b..81f0c72b 100644 --- a/.abcd/development/roadmap/phases/phase-3-intent.md +++ b/.abcd/development/roadmap/phases/phase-3-intent.md @@ -28,8 +28,9 @@ is one the planner can consume without re-interrogating it. Phase 1 Socratic vagueness interrogation, Phase 2 silent PRD synthesis. The PRD is frozen at `.abcd/intents//prd.md` on promotion. - The emergent glossary is written under - `.abcd/development/foundation/terminology/`; grill's lint codes - (GL001–GL005, GR001–GR005) are live as Go lints. + `.abcd/development/brief/glossary/` (the bounded-context glossary home, per + [adr-30](../../decisions/adrs/0030-record-information-architecture.md)); + grill's lint codes (GL001–GL005, GR001–GR005) are live as Go lints. - The coherence-aware grill tiers work: Tier 2 (brief-coherence) and Tier 3 (sibling-intent index) run; light vs. full grill is selected by lifecycle position. diff --git a/.abcd/work/issues/resolved/iss-1-launch-phase-ownership.md b/.abcd/work/issues/resolved/iss-1-launch-phase-ownership.md new file mode 100644 index 00000000..c5a7f4c7 --- /dev/null +++ b/.abcd/work/issues/resolved/iss-1-launch-phase-ownership.md @@ -0,0 +1,13 @@ +--- +schema_version: 1 +id: "iss-1" +slug: "launch-phase-ownership" +severity: "critical" +category: "inconsistency" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: ".abcd/development/brief/04-surfaces/04-launch.md" +resolution: "ADR-33: phase index is the sole ownership source; Phase 1 owns the curated-release cut, deepenings are intent-attributed (itd-65/66/70/72/73). 04-launch.md banner and Phase-5 references rewritten; launch-gatekeeper row re-anchored." +--- + +launch phase ownership contradicts across the record: phase-1-ahoy.md and build-sequence.md make install plus launch the first milestone, but 04-surfaces/04-launch.md says full launch builds in Phase 5. ADR-bound. \ No newline at end of file diff --git a/.abcd/work/issues/resolved/iss-10-phase-0-user-command-wording.md b/.abcd/work/issues/resolved/iss-10-phase-0-user-command-wording.md new file mode 100644 index 00000000..b25ca65a --- /dev/null +++ b/.abcd/work/issues/resolved/iss-10-phase-0-user-command-wording.md @@ -0,0 +1,13 @@ +--- +schema_version: 1 +id: "iss-10" +slug: "phase-0-user-command-wording" +severity: "major" +category: "inconsistency" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: ".abcd/development/roadmap/phases/README.md" +resolution: "phases README Phase 0 wording aligned to phase-0-substrate.md's qualifier: no product-capability user moment, but it does carry the /abcd:intent review sub-verb." +--- + +Phase 0 user-command wording contradicts: phase-0-substrate.md says Phase 0 carries /abcd:intent review; phases README says Phase 0 has no user-facing command. \ No newline at end of file diff --git a/.abcd/work/issues/resolved/iss-11-agent-count-drift.md b/.abcd/work/issues/resolved/iss-11-agent-count-drift.md new file mode 100644 index 00000000..03c1ac2b --- /dev/null +++ b/.abcd/work/issues/resolved/iss-11-agent-count-drift.md @@ -0,0 +1,13 @@ +--- +schema_version: 1 +id: "iss-11" +slug: "agent-count-drift" +severity: "minor" +category: "inconsistency" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: ".abcd/development/brief/05-internals/01-agents.md" +resolution: "Agent count corrected 15 -> 16 in press-release, 04-scope and 05-prompt-quality, each now pointing at the 01-agents.md catalog as the canonical roster." +--- + +agent count drift: 01-agents.md declares 16 agents; press-release, 04-scope and 05-prompt-quality still say 15. \ No newline at end of file diff --git a/.abcd/work/issues/resolved/iss-12-memory-shipped-vs-planned.md b/.abcd/work/issues/resolved/iss-12-memory-shipped-vs-planned.md new file mode 100644 index 00000000..b637555f --- /dev/null +++ b/.abcd/work/issues/resolved/iss-12-memory-shipped-vs-planned.md @@ -0,0 +1,13 @@ +--- +schema_version: 1 +id: "iss-12" +slug: "memory-shipped-vs-planned" +severity: "minor" +category: "inconsistency" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: ".abcd/development/intents/planned/itd-36-memory-unification.md" +resolution: "Memory docs no longer assert shipped state: spc-38/spc-39 references demoted from delivery claims to spec attribution, 07-memory header states itd-36 is planned/ and defers delivery state to the intent lifecycle, backed by the new brief-README provenance note." +--- + +memory shipped versus planned is ambiguous: docs say spc-38/spc-39 shipped, but itd-36 lives in planned and intents README says shipped is empty until Go capabilities ship. \ No newline at end of file diff --git a/.abcd/work/issues/resolved/iss-13-brief-stale-status-narration.md b/.abcd/work/issues/resolved/iss-13-brief-stale-status-narration.md new file mode 100644 index 00000000..729afa91 --- /dev/null +++ b/.abcd/work/issues/resolved/iss-13-brief-stale-status-narration.md @@ -0,0 +1,13 @@ +--- +schema_version: 1 +id: "iss-13" +slug: "brief-stale-status-narration" +severity: "minor" +category: "drift" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: ".abcd/development/brief" +resolution: "Stale status narration stripped from brief contracts: 'shipped —' status cells corrected to design target (no agents/ exist in this repo), '(spc-N — shipped)' parentheticals reduced to spec attribution, dated capture-history prose removed from 04-scope.md, and a delivery-state provenance note added to the brief README covering residual spc-N references (per adr-5)." +--- + +current-state brief files carry stale status narration (spc-X shipped, today only stubs ship) inside canonical design contracts, against ADR-5. \ No newline at end of file diff --git a/.abcd/work/issues/resolved/iss-14-stale-intent-section-deeplinks.md b/.abcd/work/issues/resolved/iss-14-stale-intent-section-deeplinks.md new file mode 100644 index 00000000..8c1d3e11 --- /dev/null +++ b/.abcd/work/issues/resolved/iss-14-stale-intent-section-deeplinks.md @@ -0,0 +1,13 @@ +--- +schema_version: 1 +id: "iss-14" +slug: "stale-intent-section-deeplinks" +severity: "nitpick" +category: "documentation" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: ".abcd/development/brief/04-surfaces/README.md" +resolution: "Reviewer deep links corrected from 05-intent.md section 6 to section 7 (with the current anchor) in 04-surfaces README, 01-agents.md, 04-universal-patterns.md, itd-1, and the internal section 6 self-reference; the intents-README section 6 lint-rule link verified still correct (IL013 lives in section 6)." +--- + +stale deep links: 04-surfaces README and 01-agents.md point to the intent reviewer as 05-intent.md section 6, but that section now appears later. \ No newline at end of file diff --git a/.abcd/work/issues/resolved/iss-15-capture-vs-record-lint.md b/.abcd/work/issues/resolved/iss-15-capture-vs-record-lint.md new file mode 100644 index 00000000..a535d837 --- /dev/null +++ b/.abcd/work/issues/resolved/iss-15-capture-vs-record-lint.md @@ -0,0 +1,13 @@ +--- +schema_version: 1 +id: "iss-15" +slug: "capture-vs-record-lint" +severity: "critical" +category: "tech-debt" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: "internal/core/capture" +resolution: "Fixed by ADR-32 / PR #4 (2be0b81): ledger moved to .abcd/work/issues and created/updated dropped, so capture no longer writes git-inferable metadata into the record-lint root." +--- + +capture wrote a schema-required created field into the record-lint root, so running capture broke record-lint. This drove moving the ledger to work/issues and dropping created/updated. Fixed by refactor/capture-ledger-schema-tier. \ No newline at end of file diff --git a/.abcd/work/issues/resolved/iss-2-release-version-source-of-truth.md b/.abcd/work/issues/resolved/iss-2-release-version-source-of-truth.md new file mode 100644 index 00000000..203c3db5 --- /dev/null +++ b/.abcd/work/issues/resolved/iss-2-release-version-source-of-truth.md @@ -0,0 +1,13 @@ +--- +schema_version: 1 +id: "iss-2" +slug: "release-version-source-of-truth" +severity: "critical" +category: "inconsistency" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: ".abcd/development/brief/04-surfaces/04-launch.md" +resolution: "Aligned to ADR-31: roadmap README now tracks releases by the v* tag with the number derived from shipped intents' impact; 04-launch.md bump-tier rule rewritten to impact derivation + surface-diff guardrail (phase-completion tiering and --version dropped); verification matrix row updated." +--- + +release-version source of truth conflicts: roadmap README tracks releases by plugin.json; ADR-31 derives versions from shipped intents; 04-launch.md still describes --version and phase-completion tiering. ADR-bound. \ No newline at end of file diff --git a/.abcd/work/issues/resolved/iss-3-phase-membership-vs-lifecycle.md b/.abcd/work/issues/resolved/iss-3-phase-membership-vs-lifecycle.md new file mode 100644 index 00000000..e1519031 --- /dev/null +++ b/.abcd/work/issues/resolved/iss-3-phase-membership-vs-lifecycle.md @@ -0,0 +1,13 @@ +--- +schema_version: 1 +id: "iss-3" +slug: "phase-membership-vs-lifecycle" +severity: "critical" +category: "inconsistency" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: ".abcd/development/intents" +resolution: "ADR-34: lifecycle (commitment, directory) and scheduling (phase Scope) are orthogonal; invariant runs one way — scheduled implies planned/. itd-43 and itd-7 moved drafts->planned (itd-43 kind bound standalone per its suggested_kind); intents README planned/ definition and listings corrected." +--- + +phase membership and lifecycle directories disagree: planned intents (itd-20, itd-24, itd-29, itd-46) appear in no phase Scope, while draft itd-43 is scoped into Phase 0/1 yet listed later-phase. ADR-bound. \ No newline at end of file diff --git a/.abcd/work/issues/resolved/iss-4-six-vs-seven-phases.md b/.abcd/work/issues/resolved/iss-4-six-vs-seven-phases.md new file mode 100644 index 00000000..8f145718 --- /dev/null +++ b/.abcd/work/issues/resolved/iss-4-six-vs-seven-phases.md @@ -0,0 +1,14 @@ +--- +schema_version: 1 +id: "iss-4" +slug: "six-vs-seven-phases" +severity: "major" +category: "inconsistency" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: ".abcd/development/brief/06-delivery/03-out-of-scope.md" +blocked_by: [iss-1] +resolution: "Six-phase language corrected to the seven-phase index (Phase 0 Foundations through Phase 6 Lifeboat round-trip) in 04-scope.md, 03-mental-model.md, 03-out-of-scope.md, and the 06-delivery README, per ADR-33's canonical-index rule." +--- + +phase count mismatch: 04-scope.md, 03-out-of-scope.md and 06-delivery README say six phases (Phase 0-5), but roadmap phases README has Phase 0-6 with Phase 6 as lifeboat round-trip. \ No newline at end of file diff --git a/.abcd/work/issues/resolved/iss-5-disembark-embark-phase-banners.md b/.abcd/work/issues/resolved/iss-5-disembark-embark-phase-banners.md new file mode 100644 index 00000000..5b9f007f --- /dev/null +++ b/.abcd/work/issues/resolved/iss-5-disembark-embark-phase-banners.md @@ -0,0 +1,14 @@ +--- +schema_version: 1 +id: "iss-5" +slug: "disembark-embark-phase-banners" +severity: "major" +category: "inconsistency" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: ".abcd/development/brief/04-surfaces/02-disembark.md" +blocked_by: [iss-1] +resolution: "Disembark and embark banners re-anchored to Phase 6 (phase-6-lifeboat.md) per ADR-33; the agent catalog's lifeboat-pipeline rows (Pass A/B/C, embark-scaffolder, documentation-auditor) re-anchored from old Phase 4/5 numbering to Phase 6 + itd-65." +--- + +disembark and embark status banners point to the wrong phase: 02-disembark.md says Phase 4, 03-embark.md says Phase 5, but phase-6-lifeboat.md owns both. \ No newline at end of file diff --git a/.abcd/work/issues/resolved/iss-6-command-inventory-seven-vs-nine.md b/.abcd/work/issues/resolved/iss-6-command-inventory-seven-vs-nine.md new file mode 100644 index 00000000..a9c8efe6 --- /dev/null +++ b/.abcd/work/issues/resolved/iss-6-command-inventory-seven-vs-nine.md @@ -0,0 +1,13 @@ +--- +schema_version: 1 +id: "iss-6" +slug: "command-inventory-seven-vs-nine" +severity: "major" +category: "inconsistency" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: ".abcd/development/brief/01-product/04-scope.md" +resolution: "04-scope.md user-facing command list extended with /abcd (itd-20) and /abcd:reflect (itd-24), matching the nine-command inventory in 04-surfaces/README.md." +--- + +command inventory mismatch: 04-scope.md lists seven user-facing commands; 04-surfaces README lists nine (adds /abcd and /abcd:reflect). \ No newline at end of file diff --git a/.abcd/work/issues/resolved/iss-7-hand-maintained-intent-counts.md b/.abcd/work/issues/resolved/iss-7-hand-maintained-intent-counts.md new file mode 100644 index 00000000..bbf5f359 --- /dev/null +++ b/.abcd/work/issues/resolved/iss-7-hand-maintained-intent-counts.md @@ -0,0 +1,14 @@ +--- +schema_version: 1 +id: "iss-7" +slug: "hand-maintained-intent-counts" +severity: "major" +category: "drift" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: ".abcd/development/brief/01-product/04-scope.md" +blocked_by: [iss-3] +resolution: "Hand-maintained 'thirteen phased intents' counts in 04-scope.md and 03-mental-model.md replaced with derivation-by-pointer to the phase docs' Scope sections (adr-9): the phased set is the union across phase docs, never transcribed into the brief." +--- + +04-scope.md hand-maintains intent counts (thirteen phased intents) that the phase docs and planned corpus have outgrown. \ No newline at end of file diff --git a/.abcd/work/issues/resolved/iss-8-out-of-scope-stale-corpus.md b/.abcd/work/issues/resolved/iss-8-out-of-scope-stale-corpus.md new file mode 100644 index 00000000..bda8def9 --- /dev/null +++ b/.abcd/work/issues/resolved/iss-8-out-of-scope-stale-corpus.md @@ -0,0 +1,14 @@ +--- +schema_version: 1 +id: "iss-8" +slug: "out-of-scope-stale-corpus" +severity: "major" +category: "drift" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: ".abcd/development/brief/06-delivery/03-out-of-scope.md" +blocked_by: [iss-3] +resolution: "03-out-of-scope.md regenerated against the live drafts/ corpus under ADR-34: itd-43 removed (now planned+scheduled), ten missing drafts added (itd-57/59/60/61/62/64/70/73/74/75), derivation command simplified to no-exclusions since scheduled intents cannot live in drafts/; verified in lockstep with disk." +--- + +03-out-of-scope.md omits current drafts itd-74 and itd-75 while including scoped itd-43; regenerate from the actual draft corpus. \ No newline at end of file diff --git a/.abcd/work/issues/resolved/iss-9-glossary-terminology-path.md b/.abcd/work/issues/resolved/iss-9-glossary-terminology-path.md new file mode 100644 index 00000000..5989a91b --- /dev/null +++ b/.abcd/work/issues/resolved/iss-9-glossary-terminology-path.md @@ -0,0 +1,13 @@ +--- +schema_version: 1 +id: "iss-9" +slug: "glossary-terminology-path" +severity: "major" +category: "inconsistency" +source: "review-followup" +found_during: "roadmap-consistency-review" +found_at: ".abcd/development/roadmap/phases/phase-3-intent.md" +resolution: "Glossary home standardised to .abcd/development/brief/glossary/ per ADR-30: phase-3 milestone path, disembark terminology render source, and the glossary README layout-root label corrected." +--- + +glossary output path is inconsistent: Phase 3 writes to foundation/terminology while the record uses brief/glossary and ADR-30 names that the glossary home. \ No newline at end of file diff --git a/.abcd/work/reviews/2026-07-07-roadmap-consistency/00-summary.md b/.abcd/work/reviews/2026-07-07-roadmap-consistency/00-summary.md new file mode 100644 index 00000000..4a1b2af7 --- /dev/null +++ b/.abcd/work/reviews/2026-07-07-roadmap-consistency/00-summary.md @@ -0,0 +1,30 @@ +# Roadmap-Consistency Review - Consolidated Summary + +**Scope:** `.abcd/development/brief/`, `.abcd/development/roadmap/`, and `.abcd/development/intents/`, with emphasis on phase ownership, lifecycle state, release policy, and command-surface consistency. + +**Method:** external consistency review of the design record. The review looked for contradictions between canonical brief files, roadmap phase documents, ADRs, and intent lifecycle directories. + +--- + +## Verdict + +The current design record has several consistency gaps that make the roadmap difficult to use as an implementation scheduler. The highest-risk issues are phase ownership for `/abcd:launch`, the release-version source of truth, and disagreement between intent lifecycle directories and phase membership. + +## Findings + +| Severity | Enhancement | Why it matters | +|---|---|---| +| **Critical** | Reconcile `/abcd:launch` phase ownership. `roadmap/phases/phase-1-ahoy.md` and `brief/06-delivery/01-build-sequence.md` say install + launch is the first milestone, but `brief/04-surfaces/04-launch.md` says full launch builds in Phase 5. | Implementers cannot know whether launch is Phase 1 MVP work or late round-trip work. | +| **Critical** | Reconcile release-version source of truth. `roadmap/README.md` says plugin releases are tracked by `.claude-plugin/plugin.json`; ADR-31 says release versions are derived from shipped intents and never authored in the working tree; `brief/04-surfaces/04-launch.md` still describes `--version` and phase-completion tiering. | Release automation will encode the wrong versioning model unless one policy wins. | +| **Critical** | Make phase membership and lifecycle directories agree. `intents/README.md` says `planned/` contains capabilities scoped into roadmap phases, but many planned intents do not appear in any phase `## Scope` (`itd-20`, `itd-24`, `itd-29`, `itd-46`, etc.). Conversely, draft `itd-43` is scoped into Phase 0/1 and still listed later-phase. | The roadmap cannot be used as a scheduler if "planned", "phased", and "draft" disagree. | +| **Major** | Fix "six planned phases" to match the seven phase docs. `brief/01-product/04-scope.md`, `brief/06-delivery/03-out-of-scope.md`, and `brief/06-delivery/README.md` say six phases / Phase 0-5, but `roadmap/phases/README.md` has Phase 0-6 with Phase 6 as lifeboat round-trip. | Readers will miss or misplace the final round-trip phase. | +| **Major** | Move disembark/embark status banners to Phase 6. `brief/04-surfaces/02-disembark.md` says Phase 4, `brief/04-surfaces/03-embark.md` says Phase 5, while `roadmap/phases/phase-6-lifeboat.md` owns both. | The core product surface is assigned to three different milestones. | +| **Major** | Update the brief's command inventory to include `/abcd` and `/abcd:reflect`, or mark them non-user-facing consistently. `brief/01-product/04-scope.md` lists seven user-facing commands; `brief/04-surfaces/README.md` lists nine. | Scope, docs, and command wiring will diverge around the top-level status board and reflection surface. | +| **Major** | Replace hand-maintained intent counts/lists in `brief/01-product/04-scope.md`. It still says "thirteen phased intents"; the phase docs and `planned/` corpus now describe a much larger set. | This repeats the drift the roadmap says it avoids by deriving counts from disk. | +| **Major** | Regenerate `brief/06-delivery/03-out-of-scope.md` from the actual draft corpus. It omits current draft files such as `itd-74` and `itd-75`, while including scoped `itd-43`; its derivation command also excludes only a stale phased-in set. | The canonical later-phase list is no longer canonical. | +| **Major** | Standardise the glossary/terminology path. Phase 3 still writes glossary output to `.abcd/development/foundation/terminology/`, while the current record uses `brief/glossary/` and ADR-30 names that as the bounded-context glossary home. | Lint, grill, and documentation will write/read different vocabulary stores. | +| **Major** | Align Phase 0's "no user-facing command" claim. `roadmap/phases/phase-0-substrate.md` explicitly says Phase 0 carries `/abcd:intent review`; `roadmap/phases/README.md` says Phase 0 has no user-facing command. | The phase principle is sound, but the wording currently contradicts the exception. | +| **Minor** | Fix agent count drift. `brief/05-internals/01-agents.md` declares 16 agents; `brief/01-product/01-press-release.md`, `brief/01-product/04-scope.md`, and `brief/05-internals/05-prompt-quality.md` still say 15. | This is easy to fix and prevents future generated prompt/test counts being wrong. | +| **Minor** | Resolve `/abcd:memory` shipped/planned state. Memory docs say spc-38/spc-39 shipped, but `itd-36` lives in `planned/` and `intents/README.md` says `shipped/` is empty until Go capabilities ship. | The shipped/planned model loses authority if product docs describe shipped capability outside `shipped/`. | +| **Minor** | Remove stale status narration from current-state brief files, or move it to spec/logbook records. Many files contain "spc-X shipped", "today only stubs ship", and historical notes inside canonical design contracts. | ADR-5 says the brief is current state; embedded delivery history will keep re-drifting. | +| **Nitpick** | Fix stale deep links to `brief/04-surfaces/05-intent.md` section 6. `brief/04-surfaces/README.md` and `brief/05-internals/01-agents.md` point to the reviewer as section 6, but the current section appears later in the file. | Low severity, but it undermines the brief's use as agent-loadable reference material. | diff --git a/.gitignore b/.gitignore index 9483ed60..e46f63d5 100644 --- a/.gitignore +++ b/.gitignore @@ -43,3 +43,6 @@ go.work.sum # Committed dev material lives in .abcd/development/ (durable record) and # .abcd/work/ (shared CONTEXT.md + DECISIONS.md); only Tier 3 is local. .abcd/.work.local/ + +# capture ledger allocator lock (runtime artefact) +.abcd/work/issues/.iss-alloc.lock