From ba5e701f75976b38180d25d1c0ae990379eaf77a Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Tue, 28 Jul 2026 11:43:24 +0100 Subject: [PATCH 1/4] docs: bring the brief surface docs current with the shipped v0.4.1 surface A tier-full brief<->surface cross-check found 22 discrepancies between the development brief's surface docs and the shipped v0.4.1 binary/tree. Correct each doc claim to match ground truth (binary --help, hooks/hooks.json, commands/abcd/, internal/core/audit/rules.go): - 04-surfaces/01-ahoy.md: dry-run JSON envelope now carries a top-level `guard` key; hooks manifest wires a fifth PreToolUse event (`abcd guard hook`, matcher Bash); `ahoy install` gains a `--dev` flag. - 04-surfaces/05-intent.md: `abcd intent [text]` gains a create-time `--impact` flag; bare render emits an ideate-routing line. - 04-surfaces/06-capture.md: `capture resolve` now requires `--impact`; bare render hint is three-way (adds ideate); only 4 of the 7 provenance flags carry a default. - 04-surfaces/07-memory.md: spec-store range spc-2..spc-13 -> spc-2..spc-19. - 04-surfaces/08-abcd.md: commands/abcd/ is 17 files, not 14; add guard, ideate, identity. - 04-surfaces/15-prepare-this-repo.md: audit engine registers six convention rules, not five (identity-positioning). - 05-internals/08-skills.md: fourteen binary-backed commands, not eleven; add guard/ideate/identity and their sub-verbs; identity has a bare status render. - 05-internals/03-configuration.md: hooks.json annotation adds the PreToolUse guard-hook wiring (five events, not four). - commands/abcd/disembark.md: document the probe and coverage sub-verbs and update the argument-hint (resolves ledger issue iss-137). Assisted-by: Claude:claude-opus-4-8 --- .../development/brief/04-surfaces/01-ahoy.md | 16 ++++++---- .../brief/04-surfaces/05-intent.md | 6 ++-- .../brief/04-surfaces/06-capture.md | 14 ++++----- .../brief/04-surfaces/07-memory.md | 2 +- .../development/brief/04-surfaces/08-abcd.md | 5 ++-- .../brief/04-surfaces/15-prepare-this-repo.md | 2 +- .../brief/05-internals/03-configuration.md | 2 +- .../brief/05-internals/05-prompt-quality.md | 4 +-- .../brief/05-internals/08-skills.md | 6 ++-- ...k-plugin-surface-missing-probe-coverage.md | 2 ++ commands/abcd/disembark.md | 30 +++++++++++++++++-- 11 files changed, 62 insertions(+), 27 deletions(-) rename .abcd/work/issues/{open => resolved}/iss-137-disembark-plugin-surface-missing-probe-coverage.md (78%) diff --git a/.abcd/development/brief/04-surfaces/01-ahoy.md b/.abcd/development/brief/04-surfaces/01-ahoy.md index a3df5aa8..d138975a 100644 --- a/.abcd/development/brief/04-surfaces/01-ahoy.md +++ b/.abcd/development/brief/04-surfaces/01-ahoy.md @@ -165,7 +165,9 @@ Steps, run in parallel where independent: required event entries (`UserPromptSubmit`, `SessionStart`, `PreCompact`) each referencing the expected prompt-router hook commands. The shipped manifest also wires `abcd hook session-start` (a second `SessionStart` - command) and `abcd hook session-end` (a fourth `SessionEnd` event); + command), `abcd hook session-end` (a `SessionEnd` event), and `abcd guard + hook` (a `PreToolUse` event, matcher `Bash`, that checks a shell command + against the hazard registry before it runs) — five event types in all; verification covers only the three prompt-router commands above. A missing or malformed manifest surfaces as a non-resolvable `plugin-owned` diagnostic gap. Neither install nor uninstall ever mutates `hooks.json` — the manifest @@ -205,8 +207,10 @@ resolvable category without prompting, `--adopt` / `--refuse-adopt` decide the unmanaged-repo adoption question, `--docs-target` (`claude_md` | `agents_md` | `both` | `skip`) sets the marker target, `--oracle-backend` (`host-delegated` | `native` | `cli` | `api` | `mcp`) sets the oracle, -`--scan-deep` (`true` | `false`) toggles the deep scan, and `--visibility` -(`private` | `public`) sets repo visibility. `--yes` does not adopt an +`--scan-deep` (`true` | `false`) toggles the deep scan, `--visibility` +(`private` | `public`) sets repo visibility, and `--dev` selects track-latest +dogfood mode (the PATH entry rebuilds from the source tip on every call instead +of pinning the built binary). `--yes` does not adopt an unmanaged repo or pin an unset git identity — those still need `--adopt` and an interactive confirmation. @@ -314,7 +318,9 @@ acceptance criterion, not just prose — see § Acceptance. canonical `DetectionResult` envelope as JSON (per spc-16 T1 — JSON ONLY; no unified-diff renderer in this command surface). Exits without writing. The JSON envelope shape is `{folder_kind, adopted, root_sha, -plugin_root_status, repo_identity, signals, gaps}` so the plugin command +plugin_root_status, repo_identity, signals, guard, gaps}` (the `guard` key +reports the guard-hook health: `plugin_root_resolved`, `hook_installed`, +`binary_reachable`, `registry_loadable`, `disabled`, and `entries`) so the plugin command (`commands/abcd/ahoy.md`) summarises state off `folder_kind` + `gaps` and names `abcd ahoy install` for anything actionable. @@ -379,7 +385,7 @@ user-scope app-state. - **Given** the user runs `/abcd:ahoy dry-run`, **when** the command completes, **then** the detection pass runs, the canonical `DetectionResult` JSON envelope (`{folder_kind, adopted, root_sha, - plugin_root_status, repo_identity, signals, gaps}` per spc-16 T1) is printed + plugin_root_status, repo_identity, signals, guard, gaps}` per spc-16 T1) is printed to stdout, and no files are modified. - **Given** the user runs `/abcd:ahoy doctor` on an installed repo whose registered history-store `path` no longer matches `index.json`, **then** an diff --git a/.abcd/development/brief/04-surfaces/05-intent.md b/.abcd/development/brief/04-surfaces/05-intent.md index 779b8a4f..2130f0e5 100644 --- a/.abcd/development/brief/04-surfaces/05-intent.md +++ b/.abcd/development/brief/04-surfaces/05-intent.md @@ -174,8 +174,8 @@ Later phase — intent-fidelity-reviewer (shape-classification role) scans the c | Subcommand | Purpose | File movement | |---|---|---| -| `/abcd:intent` (no args) | Read-only status: bucket counts (drafts / planned / shipped / disciplines / superseded), open/closed spec counts, the itd↔spc links, and a ledger-routing hint (`abcd capture "…"` for an observation, `abcd intent "…"` for a user-facing change) | — | -| `/abcd:intent ""` | **Canonical create** (spc-30 (predecessor store)/itd-46): a leading quoted seed is the canonical create entry. Seeds a draft skeleton from the text — placeholder Press Release and Acceptance Criteria sections for the human to expand — and assigns `itd-N`; writes `suggested_kind: null`. A leading quote always creates — never falls through to bare render | writes to `drafts/itd-N-.md` (no spec created) | +| `/abcd:intent` (no args) | Read-only status: bucket counts (drafts / planned / shipped / disciplines / superseded), open/closed spec counts, the itd↔spc links, a ledger-routing hint (`abcd capture "…"` for an observation, `abcd intent "…"` for a user-facing change), and an ideate-routing line (a big, unproven idea? `abcd ideate` runs the optional admission gauntlet and records the verdict either way) | — | +| `/abcd:intent ""` | **Canonical create** (spc-30 (predecessor store)/itd-46): a leading quoted seed is the canonical create entry. Seeds a draft skeleton from the text — placeholder Press Release and Acceptance Criteria sections for the human to expand — and assigns `itd-N`; writes `suggested_kind: null`. An optional `--impact ` flag stamps the draft's product impact at create time. A leading quote always creates — never falls through to bare render | writes to `drafts/itd-N-.md` (no spec created) | | `/abcd:intent new ` | Deprecated alias for the quoted-text create (`abcd intent ""`); files a draft from the text | writes to `drafts/itd-N-.md` (no spec created) | | `/abcd:intent grill ` | Socratic adversarial interview that stress-tests an intent for vagueness, missing acceptance, hidden assumptions before planning. Glossary-aware once `terminology/` exists. `--brief-section ` flag for stress-testing a brief section instead. (per itd-27, `intents/planned/` — a later phase; no `grill` sub-verb ships yet) | (stays in current state) | | `/abcd:intent plan ` | Plans a draft: mints its native spec, injects the bidirectional link (intent `spec_id` ↔ spec `intent`), and moves the file `drafts/` → `planned/`. Single intent ID. | `drafts/` → `planned/` | @@ -211,7 +211,7 @@ builds_on: [] # itd-N ids this intent builds on severity: minor # seeded capture-grain severity of the draft # Added later, not part of the seed skeleton: # bundle: — for kind: bundle-member, the bundle ID -# impact: additive|breaking|fix — the compatibility judgement the derived version is computed from. Never "internal" (a press-release-first intent is user-facing by definition), and required before the intent may move to shipped/ +# impact: additive|breaking|fix — the compatibility judgement the derived version is computed from. Never "internal" (a press-release-first intent is user-facing by definition), and required before the intent may move to shipped/. Optionally stamped at create time via the `--impact` flag, otherwise added later # surface_history: [] — appended when an intent's user-facing surface shape changes (e.g., skill → sub-verb, top-level command → sub-verb, command → flag) WITHOUT changing kind. Distinct from reclassification_history. Schema: { date, from, to, reason } --- diff --git a/.abcd/development/brief/04-surfaces/06-capture.md b/.abcd/development/brief/04-surfaces/06-capture.md index 77a4d286..e1150982 100644 --- a/.abcd/development/brief/04-surfaces/06-capture.md +++ b/.abcd/development/brief/04-surfaces/06-capture.md @@ -8,14 +8,14 @@ See itd-4 for the full intent. Ledger schema lives in the Go binary (`internal/c | Subcommand | Purpose | File movement | |---|---|---| -| `/abcd:capture` (no args) | Help + status: shows the most recent open issues and closes with a capture-vs-intent routing hint. Bare invocation owns the default status/help render — there is no implicit-default filtered list. | — | -| `/abcd:capture ""` | Fast path: appends a structured issue entry to the ledger with auto-assigned `iss-N`; provenance and taxonomy are caller-supplied flags, each with a default — `--severity`, `--category`, `--source`, `--found-during`, `--found-at`, `--slug`, `--blocked-by` (comma-separated `iss-N` dependency edges; blocked/priority status is derived from `blocked_by`, never stored) | writes `.abcd/work/issues/open/iss-N-.md` | +| `/abcd:capture` (no args) | Help + status: shows the most recent open issues and closes with a three-way routing hint — capture vs intent, plus an ideate route (a big, unproven idea? `abcd ideate` runs the optional admission gauntlet and records the verdict either way). Bare invocation owns the default status/help render — there is no implicit-default filtered list. | — | +| `/abcd:capture ""` | Fast path: appends a structured issue entry to the ledger with auto-assigned `iss-N`; provenance and taxonomy are caller-supplied flags — `--severity`, `--category`, `--source`, and `--found-during` each carry a default; `--found-at`, `--slug`, and `--blocked-by` (comma-separated `iss-N` dependency edges; blocked/priority status is derived from `blocked_by`, never stored) have none | writes `.abcd/work/issues/open/iss-N-.md` | | `/abcd:capture list --open` | Query the ledger for currently-open issues (flag immediately adjacent — earned SD001 exception) | — | | `/abcd:capture list --resolved` | Query the ledger for resolved issues | — | | `/abcd:capture list --wontfix` | Query the ledger for wontfix issues | — | | `/abcd:capture list --all` | Query the ledger across all three states | — | | `/abcd:capture promote ` | Promote an issue to an intent draft: command-orchestrated (never a `capture promote` CLI sub-verb), it hands the issue body to `abcd intent ""`, which files a new draft under `intents/drafts/` seeded from that text. The reciprocal back-link (`promoted_to` scalar + `related_issues` ↔ `related_intents` lists) onto the `iss-N` record is written by hand — no engine verb writes that edge. | (issue stays; intent created in `drafts/`) | -| `/abcd:capture resolve ""` | Mark issue resolved | `open/` → `resolved/` | +| `/abcd:capture resolve "" --impact ` | Mark issue resolved (`--impact` is required — resolving without it exits 1) | `open/` → `resolved/` | | `/abcd:capture wontfix ""` | Explicit non-action decision | `open/` → `wontfix/` | The unfiltered CLI shape `abcd capture list` (no flag) is rejected with @@ -24,8 +24,8 @@ message. The four flagged forms above are the only earned SD001 exception under the capture surface; each flag must appear immediately adjacent to `list`, never pipe-joined into a single token. There is no implicit-default filtered list — bare `/abcd:capture` is what renders -status and recent captures, closing with a capture-vs-intent routing -hint. +status and recent captures, closing with a three-way routing hint +(capture vs intent, plus an ideate route for a big, unproven idea). ## 2. Ledger structure @@ -71,12 +71,12 @@ A later phase, not yet built — the migration rides the `abcd dev-sync work` su ## 4. Acceptance - **Given** an abcd-installed repo, **when** the user runs `/abcd:capture "review nitpick: T7 cache_ttl_days dead-config alternative"`, **then** a new file `.abcd/work/issues/open/iss-N-.md` exists with frontmatter populated and the captured text in the body. -- **Given** an existing issue at `.abcd/work/issues/open/iss-3-foo.md`, **when** the user runs `/abcd:capture resolve iss-3 "fixed in spc-7 task 4"`, **then** the file moves to `.abcd/work/issues/resolved/iss-3-foo.md` with the resolution recorded. +- **Given** an existing issue at `.abcd/work/issues/open/iss-3-foo.md`, **when** the user runs `/abcd:capture resolve iss-3 "fixed in spc-7 task 4" --impact fix` (`--impact` is required and has no default), **then** the file moves to `.abcd/work/issues/resolved/iss-3-foo.md` with the resolution recorded. - **Given** an existing issue, **when** the user runs `/abcd:capture promote iss-N`, **then** the issue body is handed to `abcd intent ""`, which files a new draft intent under `intents/drafts/` seeded from that text; the reciprocal back-link (`promoted_to` scalar + `related_issues` ↔ `related_intents` lists) is recorded by hand, since no engine verb writes that edge. - **Given** a fresh `/abcd:ahoy` upgrade with an existing scratch buffer under `.abcd/.work.local/`, **when** `dev-sync` runs (a later phase, not yet built — § 3), **then** every entry in that scratch buffer is promoted to the structured ledger with provenance noting "migrated from `.abcd/.work.local/` scratch". - **Given** a ledger containing 5 open issues, **when** the user runs `/abcd:capture list --open` (the flag is explicit — there is no implicit default), **then** the output lists all 5 with id, state, severity, and slug, in derived-priority order — unblocked issues first, then severity (`critical` → `nitpick`); rows blocked by an open dependency are demoted and annotated with their open blockers. - **Given** a ledger with a mix of open, resolved, and wontfix issues, **when** the user runs `/abcd:capture list --all`, **then** every issue across all three states is listed; the equivalent unfiltered CLI form `abcd capture list` (no flag) instead exits 2 with a "choose a filter" message. -- **Given** an abcd-installed repo, **when** the user runs bare `/abcd:capture` (no args), **then** the output is a read-only status render — counts (`open N · resolved N · wontfix N`), up to 10 most recent open issues, and a capture-vs-intent routing hint — and no `iss-*.md` file is created, moved, or field-mutated by the invocation itself. +- **Given** an abcd-installed repo, **when** the user runs bare `/abcd:capture` (no args), **then** the output is a read-only status render — counts (`open N · resolved N · wontfix N`), up to 10 most recent open issues, and a three-way routing hint (capture vs intent, plus an ideate route) — and no `iss-*.md` file is created, moved, or field-mutated by the invocation itself. ## 5. Implementation status diff --git a/.abcd/development/brief/04-surfaces/07-memory.md b/.abcd/development/brief/04-surfaces/07-memory.md index 098fe5cd..0034ecef 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) traces to the predecessor store's spc-38 (the memory write core) and the lint family to the predecessor store's spc-39 (the memory-coverage lints + the `MQ`/`MS`/`ML` codes). Every bare `spc-38`/`spc-39` on this page is a predecessor-store id cited as provenance — this repo's spec store holds only spc-2..spc-13, and none of these ids names a spec in it. 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)). +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) traces to the predecessor store's spc-38 (the memory write core) and the lint family to the predecessor store's spc-39 (the memory-coverage lints + the `MQ`/`MS`/`ML` codes). Every bare `spc-38`/`spc-39` on this page is a predecessor-store id cited as provenance — this repo's spec store holds only spc-2..spc-19, and none of these ids names a spec in it. 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. diff --git a/.abcd/development/brief/04-surfaces/08-abcd.md b/.abcd/development/brief/04-surfaces/08-abcd.md index f81d6789..45c587c8 100644 --- a/.abcd/development/brief/04-surfaces/08-abcd.md +++ b/.abcd/development/brief/04-surfaces/08-abcd.md @@ -74,8 +74,9 @@ surfaces. The `disembark`, `embark`, `launch`, and `intent` CLI verbs all ship today, and each has its plugin command file present (`commands/abcd/disembark.md`, `embark.md`, `launch.md`, `intent.md`). `commands/abcd/` ships `ahoy`, `audit`, `capture`, -`consult`, `disembark`, `docs`, `embark`, `history`, `ingest`, `intent`, -`launch`, `memory`, `prepare-this-repo`, and `version` (14 files). The investigation found no predecessor spc-17 probe STUB behind the +`consult`, `disembark`, `docs`, `embark`, `guard`, `history`, `ideate`, +`identity`, `ingest`, `intent`, `launch`, `memory`, `prepare-this-repo`, and +`version` (17 files). The investigation found no predecessor spc-17 probe STUB behind the top-level command to replace — the "stub replacement" premise is therefore recorded here as not-applicable. The top-level command file itself is present today (`commands/abcd.md`, referenced above and scaffolded with the repo), so a diff --git a/.abcd/development/brief/04-surfaces/15-prepare-this-repo.md b/.abcd/development/brief/04-surfaces/15-prepare-this-repo.md index 4b33de3a..ccc7dede 100644 --- a/.abcd/development/brief/04-surfaces/15-prepare-this-repo.md +++ b/.abcd/development/brief/04-surfaces/15-prepare-this-repo.md @@ -39,7 +39,7 @@ Four phases, each gated on the one before: principles, ADRs, intents, `docs/` Diátaxis rules, and the lint configs as patterns. 2. **Audit** — run `abcd audit --json` for the engine-backed conformance core - (the five convention rules), supplement it with the structure/principles + (the six convention rules), supplement it with the structure/principles judgement the binary does not make, write the gap report to the target's `.abcd/.work.local/scratch/`, and present it before any change. 3. **Adopt** — create the three tiers with a repo-specific `CONTEXT.md`, migrate diff --git a/.abcd/development/brief/05-internals/03-configuration.md b/.abcd/development/brief/05-internals/03-configuration.md index b118949a..ed90364e 100644 --- a/.abcd/development/brief/05-internals/03-configuration.md +++ b/.abcd/development/brief/05-internals/03-configuration.md @@ -357,7 +357,7 @@ abcd/ │ └── sota-researcher.md # plus per-agent fixtures/ dirs, README.md, CHANGELOG.md └── hooks/ # Claude Code event hooks — each command shells directly to the binary └── hooks.json # UserPromptSubmit → hook prompt-router; SessionStart → prompt-router-reset + session-start; - # PreCompact → prompt-router-reset; SessionEnd → session-end + # PreToolUse (matcher Bash) → guard hook; PreCompact → prompt-router-reset; SessionEnd → session-end ``` The core is organised one package per capability under `internal/core/`, and the diff --git a/.abcd/development/brief/05-internals/05-prompt-quality.md b/.abcd/development/brief/05-internals/05-prompt-quality.md index 06359282..348fff3a 100644 --- a/.abcd/development/brief/05-internals/05-prompt-quality.md +++ b/.abcd/development/brief/05-internals/05-prompt-quality.md @@ -14,8 +14,8 @@ The linter is delivered in two stages. **Shipped by spc-8 — the mechanical itd **itd-5 prompt-quality additions on top of B+C+D:** -- **`prompt_version` frontmatter** — every `agents/*.md` carries `prompt_version: ` alongside existing `name`, `description`, `tools`, `model`. Initial value `1.0.0`. A consolidated `agents/CHANGELOG.md` records each version bump with: agent name, old → new version, one-line rationale, eval delta (golden-test pass/fail count change). Bump rules (semver-adapted): MAJOR for behaviour-breaking output schema change; MINOR for behaviour change preserving schema; PATCH for typo / non-behavioural edit. -- **One-shot oracle self-improvement pre-flight** — before each agent's prompt is locked at `1.0.0`, the author runs the pre-flight: submit candidate prompt to `lifeboat-oracle` with rewrite-for-clarity directive; run all golden-test fixtures against both candidate and oracle-rewritten variants; if oracle variant ≥ candidate on goldens AND shorter by >10%, accept oracle variant; otherwise keep candidate. Log decision + diff in `agents/CHANGELOG.md` as the agent's first entry. One-time gate per agent at v1.0.0 lock-time, not recurring. +- **`prompt_version` frontmatter** — every `agents/*.md` carries `prompt_version: ` alongside existing `name`, `description`, `tools`, `model`. Initial value `0.1.0` (agents ship in the 0.x band). A consolidated `agents/CHANGELOG.md` records each version bump with: agent name, old → new version, one-line rationale, eval delta (golden-test pass/fail count change). Bump rules (semver-adapted): MAJOR for behaviour-breaking output schema change; MINOR for behaviour change preserving schema; PATCH for typo / non-behavioural edit. +- **One-shot oracle self-improvement pre-flight** — before each agent's prompt is locked at `0.1.0`, the author runs the pre-flight: submit candidate prompt to `lifeboat-oracle` with rewrite-for-clarity directive; run all golden-test fixtures against both candidate and oracle-rewritten variants; if oracle variant ≥ candidate on goldens AND shorter by >10%, accept oracle variant; otherwise keep candidate. Log decision + diff in `agents/CHANGELOG.md` as the agent's first entry. One-time gate per agent at v0.1.0 lock-time, not recurring. - **Injection-canary fixtures** — every agent that reads untrusted input (transcripts, lifeboat content, GitHub issues, commit messages, model-emitted reviews) MUST have at least one fixture with a prompt-injection payload. Agents in scope: `chat-distiller`, `embark-scaffolder`, `issue-scout`, `code-rescuer`, `decision-archaeologist`, `review-collator`. Failing the canary fixture blocks the agent's spec from closing. **Research-driven prompts.** Every agent has a research file at `.abcd/development/research/prompting/agents/.md` — current SOTA best practices for that agent's role (e.g., "best practices for prompting a content-fidelity auditor", "best practices for prompting a product-thinker critic"). One general baseline at `.abcd/development/research/prompting/01-general-best-practices.md` covers cross-cutting prompting SOTA (structure, role definition, output formats, extended thinking, examples, etc.). diff --git a/.abcd/development/brief/05-internals/08-skills.md b/.abcd/development/brief/05-internals/08-skills.md index 6efb613d..8db39c6a 100644 --- a/.abcd/development/brief/05-internals/08-skills.md +++ b/.abcd/development/brief/05-internals/08-skills.md @@ -14,11 +14,11 @@ A **command** is a stateful operation that creates, modifies, or moves artefacts - A **brief surface file** (`04-surfaces/NN-.md`) describing acceptance criteria, interaction flow, and side effects (or a sub-verb row in an existing parent's surface file) — for example `docs`, `history`, and `version` are chapters `10`–`12`. The CLI-only binary verbs `changelog`, `rules`, and `spec` have a Go verb but no surface chapter. - A **per-invocation report subdirectory** under the gitignored `.abcd/.work.local/logs//` tier for commands that emit run reports — `memory lint` writes each run to `logs/memory/lint-/`. -- A **status + help** mode when called bare — the bare-status-board convention holds for `ahoy`, `capture`, `memory`, `intent`, and `spec` (and bare `abcd`); it is not universal (`version` prints only the version string, and the `docs`/`history`/`disembark` cobra parents print help/usage with no status board). +- A **status + help** mode when called bare — the bare-status-board convention holds for `ahoy`, `capture`, `memory`, `intent`, `identity`, and `spec` (and bare `abcd`); it is not universal (`version` prints only the version string, and the `docs`/`history`/`disembark` cobra parents print help/usage with no status board). -abcd ships **eleven binary-backed top-level commands**, each with both a Go verb and a `commands/abcd/` file: `/abcd:ahoy`, `/abcd:audit`, `/abcd:capture`, `/abcd:disembark`, `/abcd:docs`, `/abcd:embark`, `/abcd:history`, `/abcd:intent`, `/abcd:launch`, `/abcd:memory`, and `/abcd:version`. The `disembark` parent carries the largest sub-verb tree (`coverage`, `graveyard`, `oracle`, `pack`, `plan`, `press-release`, `principles`, `probe`); the `intent` parent's shipped sub-verbs are `link`, `plan`, `ready`, and `review` (alongside the deprecated `new` alias and the canonical bare quoted create `/abcd:intent ""`), with `refine`, `grill`, `ship`, `consistency`, `shape`, and `reclassify` as design targets. Three further binary verbs — `changelog`, `rules`, and `spec` — expose a Go verb but no `commands/abcd/` file, so they are CLI-only. See [`04-surfaces/`](../04-surfaces) for per-command detail. +abcd ships **fourteen binary-backed top-level commands**, each with both a Go verb and a `commands/abcd/` file: `/abcd:ahoy`, `/abcd:audit`, `/abcd:capture`, `/abcd:disembark`, `/abcd:docs`, `/abcd:embark`, `/abcd:guard`, `/abcd:history`, `/abcd:ideate`, `/abcd:identity`, `/abcd:intent`, `/abcd:launch`, `/abcd:memory`, and `/abcd:version`. The `disembark` parent carries the largest sub-verb tree (`coverage`, `graveyard`, `oracle`, `pack`, `plan`, `press-release`, `principles`, `probe`); the `intent` parent's shipped sub-verbs are `link`, `plan`, `ready`, and `review` (alongside the deprecated `new` alias and the canonical bare quoted create `/abcd:intent ""`), with `refine`, `grill`, `ship`, `consistency`, `shape`, and `reclassify` as design targets. The three newest parents carry small trees: `guard` exposes `check` and `hook`, `ideate` exposes `record`, and `identity` exposes `init` and `render` (with a bare read-only status render). Three further binary verbs — `changelog`, `rules`, and `spec` — expose a Go verb but no `commands/abcd/` file, so they are CLI-only. See [`04-surfaces/`](../04-surfaces) for per-command detail. -Alongside the eleven binary-backed verbs, abcd ships **three host-delegated commands** — `/abcd:consult`, `/abcd:ingest`, and `/abcd:prepare-this-repo` (chapters `13`–`15`). They are commands (state-mutating) but have **no Go verb**: the workflow runs in the host agent, so they have no bare-status render and no binary sub-verbs. This is the shape a command takes when its work is host-delegated rather than owned by the transport-agnostic core. +Alongside the fourteen binary-backed verbs, abcd ships **three host-delegated commands** — `/abcd:consult`, `/abcd:ingest`, and `/abcd:prepare-this-repo` (chapters `13`–`15`). They are commands (state-mutating) but have **no Go verb**: the workflow runs in the host agent, so they have no bare-status render and no binary sub-verbs. This is the shape a command takes when its work is host-delegated rather than owned by the transport-agnostic core. ## Skill vs command — decision criteria diff --git a/.abcd/work/issues/open/iss-137-disembark-plugin-surface-missing-probe-coverage.md b/.abcd/work/issues/resolved/iss-137-disembark-plugin-surface-missing-probe-coverage.md similarity index 78% rename from .abcd/work/issues/open/iss-137-disembark-plugin-surface-missing-probe-coverage.md rename to .abcd/work/issues/resolved/iss-137-disembark-plugin-surface-missing-probe-coverage.md index 13c828f8..5f0bfc41 100644 --- a/.abcd/work/issues/open/iss-137-disembark-plugin-surface-missing-probe-coverage.md +++ b/.abcd/work/issues/resolved/iss-137-disembark-plugin-surface-missing-probe-coverage.md @@ -7,6 +7,8 @@ category: "inconsistency" source: "agent-finding" found_during: "itd-88 fidelity review (2026-07-24 run queue, burst 10)" found_at: "commands/abcd/disembark.md" +resolution: "commands/abcd/disembark.md now documents probe (coverage readout) and coverage (aggregate probe reports) sub-verbs; argument-hint updated" +impact: additive --- probe and coverage ship as CLI verbs only: the plugin markdown surface (commands/abcd/disembark.md) documents plan and pack alone, while itd-88's press release headlines /abcd:disembark probe and coverage — either the surface doc grows the two verbs or the intent's diverged claim is the accepted record (dispositioned in itd-88's Audit Notes) \ No newline at end of file diff --git a/commands/abcd/disembark.md b/commands/abcd/disembark.md index 700c7bb0..2415ae77 100644 --- a/commands/abcd/disembark.md +++ b/commands/abcd/disembark.md @@ -1,7 +1,7 @@ --- name: disembark description: Pack a lifeboat from a repository into a destination directory — read-only over the source, behind a destination safety gate, secret-scanned before any write. Point it at any repo (including a dead or archived one) and write the lifeboat elsewhere. -argument-hint: " | plan " +argument-hint: " | plan | probe " --- # `/abcd:disembark` — pack a lifeboat @@ -11,7 +11,21 @@ Mine a repository's record into a portable lifeboat at ``. The source is to the destination. This is the out-of-tree model (adr-35): point it at any repo, touch nothing, write elsewhere. -## Dry run first (recommended) +## Probe first (coverage readout) + +See which brief sections a lifeboat could ground from the source, without writing +anything. The repo argument is optional and defaults to the current directory: + +```bash +abcd disembark probe --json +``` + +This is the coverage experiment's read-only readout: every brief section comes +back marked `grounded`, `partial`, or `blank`, alongside what was searched. It +writes nothing into the source and runs in a small fraction of a full pack's time +(no delegated model work). `coverage.{json,md}` are written only by `pack`. + +## Dry run next (recommended) Show the exact file set a pack would write, without writing anything: @@ -22,6 +36,18 @@ abcd disembark plan --json Report `file_count`, `total_bytes`, `manifest_sha256`, and any `omissions` (records too large or unreadable to carry). Then pack for real. +## Coverage (aggregate probe reports) + +Aggregate one or more saved probe reports into the cross-repo section×repo +coverage table — the experiment's evidence that the packer's section list holds +across a rich-record repo and a git-only one: + +```bash +abcd disembark coverage ... --json +``` + +Each positional argument is a probe report emitted with `probe --json`. + ## Pack ```bash From 62f40808312d59c435649453a7bff9e8b9d5ac67 Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Wed, 29 Jul 2026 06:09:24 +0100 Subject: [PATCH 2/4] docs: list launch scaffold in the brief's shipped-surface enumeration The 04-launch.md sub-verb enumeration and the dry-run argument-hint predated itd-93; add scaffold to both (crosscheck round 3). Assisted-by: Claude:claude-fable-5 --- .abcd/development/brief/04-surfaces/04-launch.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.abcd/development/brief/04-surfaces/04-launch.md b/.abcd/development/brief/04-surfaces/04-launch.md index 394d0117..63ec4d12 100644 --- a/.abcd/development/brief/04-surfaces/04-launch.md +++ b/.abcd/development/brief/04-surfaces/04-launch.md @@ -4,11 +4,11 @@ ## Sub-verbs -The shipped verb surface is the `--dry-run` flag on `abcd launch` — a read-only preview of the bundle and gates — plus the `abcd launch ship` subcommand, which cuts the release (the RELEASE CUT slice only; see the ship bullet below). Bare `abcd launch` never mutates state: it refuses (exit 1) with a hint to pass `--dry-run`; a bare-as-status render is a design target, unshipped. The sub-verb design: +The shipped verb surface is the `--dry-run` flag on `abcd launch` — a read-only preview of the bundle and gates — plus the `abcd launch ship` subcommand, which cuts the release (the RELEASE CUT slice only; see the ship bullet below), and the `abcd launch scaffold` subcommand, which writes the release machinery into a managed repo (itd-93; see the scaffold bullet below). Bare `abcd launch` never mutates state: it refuses (exit 1) with a hint to pass `--dry-run`; a bare-as-status render is a design target, unshipped. The sub-verb design: - **`/abcd:launch ship`** — **partly shipped: the RELEASE CUT only** (itd-73 derived versioning + itd-67's changelog slice). `abcd launch ship` derives the version and the record set from what shipped since the newest tag, runs the surface guardrail, and — with `--changelog-json` — validates the host-composed prose against the record set (the completeness bijection) and writes the dated `CHANGELOG.md` heading `.github/workflows/auto-release.yml` turns into a tag; `commands/abcd/launch.md` carries the emit → compose → ingest orchestration and the `release-changelog-composer` agent it dispatches. The `Ship` engine is wired: `abcd launch ship` is a live subcommand, and `--payload-dir ` stages the versioned release payload — the derived version stamped into the payload's `plugin.json`/`marketplace.json` and lockstep-proved before return. Commit, tag, and publish stay a design target (itd-65 gate suite + itd-72 publishing): the verb neither commits, tags, nor publishes. The full-cut design: 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` and `--allow-doc-warnings` belong to this sub-verb's design; the shipped `ship` accepts `--changelog-json` and `--payload-dir` (plus the global `--json`), and bare `abcd launch` accepts only `--dry-run` and the global `--json`. 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 scaffold`** — **shipped** (itd-93, spc-14). `abcd launch scaffold` writes the changelog-driven release machinery — `.github/workflows/release.yml`, `.github/workflows/auto-release.yml`, and the adr-37 release runbook (`.abcd/development/release-gate/README.md`) — into a managed repo that lacks it, wired to the repo's own default branch and Go version, `GITHUB_TOKEN`-only and injection-safe. The workflows ship from a single embedded template that abcd-cli's own release workflows are regenerated from (self-scaffold parity, a byte-exact test); the scaffolded `release.yml` carries a `workflow_dispatch` **rehearsal** that arms the full gate against a simulated changelog roll and reviewed-content commit and publishes nothing, so a green rehearsal is the runbook precondition for the first real release. A bare repo with no semantic detector degrades cleanly to the deterministic gates and a generic build. It is idempotent and fail-safe: a re-run on current machinery is a no-op (exit 0), a hand-edited file is refused (exit 1) rather than clobbered unless `--confirm` is passed, and a structural fault exits 2. `commands/abcd/launch.md` carries the flow. Accepts `--confirm` plus the global `--json`. -- **`/abcd:launch dry-run`** — shipped as the `--dry-run` flag (the plugin command `commands/abcd/launch.md` maps the `dry-run` of its `[dry-run | ship]` argument hint onto `abcd launch --dry-run`; the binary has no `dry-run` subcommand). **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 (predecessor store) 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 **installability smoke** runs for real at its light tier (see [§ 1](#1-pre-flight-gates)); the **manifest lockstep check** runs for real at its `dev` polarity over the working tree — the polarity adr-19 requires the committed manifests to satisfy (no version key), see [§ 3](#3-versioning--marketplace) — reports its result and folds any drift or an unreadable version-location contract into what it *would* refuse on; the remaining gates (marker-block, documentation-auditor) are the gate-suite intent's (itd-65): `--dry-run --json` reports each as `{"status": "not_implemented", "detail": "Phase-5 deferred"}`, while the plain-text `--dry-run` render omits the gate list entirely (it prints only version, files bundled, scan hardfails, and would-publish, plus a would-refuse-on line when there is a finding). 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. +- **`/abcd:launch dry-run`** — shipped as the `--dry-run` flag (the plugin command `commands/abcd/launch.md` maps the `dry-run` of its `[dry-run | ship | scaffold]` argument hint onto `abcd launch --dry-run`; the binary has no `dry-run` subcommand). **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 (predecessor store) 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 **installability smoke** runs for real at its light tier (see [§ 1](#1-pre-flight-gates)); the **manifest lockstep check** runs for real at its `dev` polarity over the working tree — the polarity adr-19 requires the committed manifests to satisfy (no version key), see [§ 3](#3-versioning--marketplace) — reports its result and folds any drift or an unreadable version-location contract into what it *would* refuse on; the remaining gates (marker-block, documentation-auditor) are the gate-suite intent's (itd-65): `--dry-run --json` reports each as `{"status": "not_implemented", "detail": "Phase-5 deferred"}`, while the plain-text `--dry-run` render omits the gate list entirely (it prints only version, files bundled, scan hardfails, and would-publish, plus a would-refuse-on line when there is a finding). 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 From 9f759c1f54a62fc204f75d2f3102e71af2a95cfc Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Wed, 29 Jul 2026 06:21:03 +0100 Subject: [PATCH 3/4] docs: the CLI reference is generated and drift-tested, not planned docs/README.md and docs/reference/README.md described the generated CLI reference as a 'planned'/'not yet wired' placeholder; it is generated from the Cobra command tree and gated by a drift test (docs-currency review, v0.4.1 release gate). Assisted-by: Claude:claude-fable-5 --- docs/README.md | 7 +++---- docs/reference/README.md | 5 ++--- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/README.md b/docs/README.md index 785d92b3..70f82437 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,9 +8,8 @@ under [`../.abcd/development/`](../.abcd/development/), not here. |-----------|---------------|-----| | [`tutorials/`](tutorials/) | Tutorial | Learning-oriented — a guided first run. | | [`how-to/`](how-to/) | How-to | Task-oriented — accomplish a specific goal. | -| [`reference/`](reference/) | Reference | Information-oriented — config, schemas, and the [CLI reference](reference/cli/) (a planned generated reference; today `abcd --help` is authoritative). | +| [`reference/`](reference/) | Reference | Information-oriented — config, schemas, and the [CLI reference](reference/cli/) (generated from the Cobra command tree and gated against drift by a build test). | | [`explanation/`](explanation/) | Explanation | Understanding-oriented — the mental model and the why. | -The CLI reference under `reference/cli/` is a placeholder for a planned generated -reference (from the Cobra command tree); that generation is not yet wired, so the -live CLI reference today is `abcd --help`. Everything else is hand-authored. +The CLI reference under `reference/cli/` is generated from the Cobra command tree +and gated against drift by a build test. Everything else is hand-authored. diff --git a/docs/reference/README.md b/docs/reference/README.md index 105194f7..1251f374 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -7,6 +7,5 @@ configuration keys, environment variables, file schemas, and the command referen - [`terminology.md`](terminology.md) — the terminology crosswalk: established agentic-AI terms mapped to abcd's position on each (uses / adapts / rejects / watching), every definition cited to a primary source. -- [`cli/`](cli/) is a placeholder for a **planned** auto-generated command - reference (from the Cobra command tree); that generation is not yet wired, so - until it ships the live CLI reference is `abcd --help`. +- [`cli/`](cli/) is the auto-generated command reference (from the Cobra command + tree), gated against drift by a build test. From 9349f17fb17d685b8c7e9bc03210d0b498523eb5 Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Wed, 29 Jul 2026 06:35:00 +0100 Subject: [PATCH 4/4] chore: track brief-currency residual (iss-152) from the v0.4.1 release gate Assisted-by: Claude:claude-fable-5 --- ...-crosscheck-residual-non-deterministic-tail-aft.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 .abcd/work/issues/open/iss-152-brief-surface-crosscheck-residual-non-deterministic-tail-aft.md diff --git a/.abcd/work/issues/open/iss-152-brief-surface-crosscheck-residual-non-deterministic-tail-aft.md b/.abcd/work/issues/open/iss-152-brief-surface-crosscheck-residual-non-deterministic-tail-aft.md new file mode 100644 index 00000000..d386a12b --- /dev/null +++ b/.abcd/work/issues/open/iss-152-brief-surface-crosscheck-residual-non-deterministic-tail-aft.md @@ -0,0 +1,11 @@ +--- +schema_version: 1 +id: "iss-152" +slug: "brief-surface-crosscheck-residual-non-deterministic-tail-aft" +severity: "minor" +category: "observation" +source: "user-observation" +found_during: "manual-capture" +--- + +brief-surface crosscheck residual (non-deterministic tail after 4 tier-full rounds, 27 items fixed): (1) 04-surfaces/01-ahoy.md bare-render enumeration omits the guard: health line the shipped bare 'abcd ahoy' now prints (5 lines not 4); (2) 04-surfaces/07-memory.md:104 enumerates 4 launch dry-run gates but marker-block and documentation-auditor are Status:not_implemented (Phase-5 deferred) stubs — only secret/PII scan + installability smoke actually run. Both minor brief-internal staleness, no user-facing doc affected (docs-currency PROMOTE). Deferred from v0.4.1 release gate via disposition; fix in a brief-currency sweep. \ No newline at end of file