Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 19 additions & 17 deletions .abcd/development/brief/04-surfaces/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,25 @@

The brief's user-facing command surface is the set enumerated below (not all are shipped yet — see [`06-delivery/`](../06-delivery) for current delivery state). Each has its own file with the surface contract: purpose, flow, acceptance criteria. (Operator-internal commands are wiring, not part of this user-facing surface — e.g. `run`, the autonomous-run operator surface over the pluggable run seam (`status`/`pause`/`resume`/`preflight`): a design target (itd-29, `intents/planned/`); no `run` verb or `commands/abcd/run.md` is on any shipped surface.)

| # | Command | Purpose | File |
|---|---|---|---|
| 1 | `/abcd:ahoy` | Install / update abcd in any project | [`01-ahoy.md`](01-ahoy.md) |
| 2 | `/abcd:disembark` | Pack a lifeboat from the current project — design target, not shipped: no `disembark` binary verb or `commands/abcd/disembark.md` (Phase 6, adr-33) | [`02-disembark.md`](02-disembark.md) |
| 3 | `/abcd:embark` | Unpack a lifeboat into a (typically empty) target — design target, not shipped: no `embark` binary verb or `commands/abcd/embark.md` (Phase 6, adr-33) | [`03-embark.md`](03-embark.md) |
| 4 | `/abcd:launch` | Preview the curated release bundle and gates (read-only); cutting/publishing the artefact is a design target (itd-72) — see [`04-launch.md`](04-launch.md) | [`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 § 7`](05-intent.md#7-the-intent-fidelity-reviewer-agent-three-roles-three-verbs)) — design target, not shipped: no `intent` binary verb or `commands/abcd/intent.md` (backing intents in `intents/planned/`) | [`05-intent.md`](05-intent.md) |
| 6 | `/abcd:capture` | Issue ledger (capture / list / resolve / wontfix; `promote` is a design target per spc-30/itd-46, skill-orchestrated — see [`06-capture.md`](06-capture.md)) | [`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, `intents/planned/`) — cross-command re-orientation. The shipped bare render is four read-only lines (directory, git repo, record present, `.abcd/` work tiers); the richer board (visibility, lifeboat, dev-sync, recent logbook, active intents, next actions) is a design target. `status` is a positional plugin alias for the bare render; `help` is not an alias (the binary has no `status` verb, and `abcd help` prints command usage). Read-only. | [`08-abcd.md`](08-abcd.md) |
| 9 | `/abcd:reflect` | Phase retrospective (per itd-24) — `/abcd:reflect <phase-id>` composes a five-section retrospective (went well / could improve / lessons / decisions / metrics) seeded by the spc-66 phase-audit receipt. Phase-only grain — design target, not shipped: no `reflect` binary verb or `commands/abcd/reflect.md` (itd-24) | [`09-reflect.md`](09-reflect.md) |
| 10 | `/abcd:docs` | Documentation-currency lint (`lint`) — change-narration, broken links, stray root markdown; read-only, the deterministic half of the docs release gate | [`10-docs.md`](10-docs.md) |
| 11 | `/abcd:history` | Session-transcript store (`capture` / `list` / `show`) — per-repo, redact-on-write, keyed on the root-commit SHA | [`11-history.md`](11-history.md) |
| 12 | `/abcd:version` | Print the installed abcd version — read-only | [`12-version.md`](12-version.md) |
| 13 | `/abcd:consult` | Consult the local sources corpus (`~/.abcd/sources`) and record source→decision provenance — host-delegated command, no Go verb | [`13-consult.md`](13-consult.md) |
| 14 | `/abcd:ingest` | Register a URL or document into the local sources corpus — host-delegated command, no Go verb | [`14-ingest.md`](14-ingest.md) |
| 15 | `/abcd:prepare-this-repo` | Bring an owned repo up to abcd's conventions (interim bridge) — host-delegated command, no Go verb | [`15-prepare-this-repo.md`](15-prepare-this-repo.md) |
| # | Command | Status | Purpose | File |
|---|---|---|---|---|
| 1 | `/abcd:ahoy` | shipped | Install / update abcd in any project | [`01-ahoy.md`](01-ahoy.md) |
| 2 | `/abcd:disembark` | staged | Pack a lifeboat from the current project — design target, not shipped: no `disembark` binary verb or `commands/abcd/disembark.md` (Phase 6, adr-33) | [`02-disembark.md`](02-disembark.md) |
| 3 | `/abcd:embark` | staged | Unpack a lifeboat into a (typically empty) target — design target, not shipped: no `embark` binary verb or `commands/abcd/embark.md` (Phase 6, adr-33) | [`03-embark.md`](03-embark.md) |
| 4 | `/abcd:launch` | shipped | Preview the curated release bundle and gates (read-only); cutting/publishing the artefact is a design target (itd-72) — see [`04-launch.md`](04-launch.md) | [`04-launch.md`](04-launch.md) |
| 5 | `/abcd:intent` | staged | 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)) — design target, not shipped: no `intent` binary verb or `commands/abcd/intent.md` (backing intents in `intents/planned/`) | [`05-intent.md`](05-intent.md) |
| 6 | `/abcd:capture` | shipped | Issue ledger (capture / list / resolve / wontfix; `promote` is a design target per spc-30/itd-46, skill-orchestrated — see [`06-capture.md`](06-capture.md)) | [`06-capture.md`](06-capture.md) |
| 7 | `/abcd:memory` | shipped | 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` | shipped | Top-level where-am-i status board (per itd-20, `intents/planned/`) — cross-command re-orientation. The shipped bare render is four read-only lines (directory, git repo, record present, `.abcd/` work tiers); the richer board (visibility, lifeboat, dev-sync, recent logbook, active intents, next actions) is a design target. `status` is a positional plugin alias for the bare render; `help` is not an alias (the binary has no `status` verb, and `abcd help` prints command usage). Read-only. | [`08-abcd.md`](08-abcd.md) |
| 9 | `/abcd:reflect` | staged | Phase retrospective (per itd-24) — `/abcd:reflect <phase-id>` composes a five-section retrospective (went well / could improve / lessons / decisions / metrics) seeded by the spc-66 phase-audit receipt. Phase-only grain — design target, not shipped: no `reflect` binary verb or `commands/abcd/reflect.md` (itd-24) | [`09-reflect.md`](09-reflect.md) |
| 10 | `/abcd:docs` | shipped | Documentation-currency lint (`lint`) — change-narration, broken links, stray root markdown; read-only, the deterministic half of the docs release gate | [`10-docs.md`](10-docs.md) |
| 11 | `/abcd:history` | shipped | Session-transcript store (`capture` / `list` / `show`) — per-repo, redact-on-write, keyed on the root-commit SHA | [`11-history.md`](11-history.md) |
| 12 | `/abcd:version` | shipped | Print the installed abcd version — read-only | [`12-version.md`](12-version.md) |
| 13 | `/abcd:consult` | shipped | Consult the local sources corpus (`~/.abcd/sources`) and record source→decision provenance — host-delegated command, no Go verb | [`13-consult.md`](13-consult.md) |
| 14 | `/abcd:ingest` | shipped | Register a URL or document into the local sources corpus — host-delegated command, no Go verb | [`14-ingest.md`](14-ingest.md) |
| 15 | `/abcd:prepare-this-repo` | shipped | Bring an owned repo up to abcd's conventions (interim bridge) — host-delegated command, no Go verb | [`15-prepare-this-repo.md`](15-prepare-this-repo.md) |

The **Status** column is machine-checked: the `surface_coverage` record-lint rule asserts every `shipped` row has a backing surface (`commands/abcd/<name>.md` or `skills/<name>/`) and every `staged` row (a design target) has none — and, in reverse, that every real surface has a row here. The bare `/abcd` top-level is binary-backed (no command file) and is exempt from the file check. Keeping this column honest is how the brief's surface set stays reconciled with the shipped binary; the semantic half — whether each row's *prose* matches binary behaviour — stays a release-gate agent check.

**Bare-command-as-help is a universal abcd convention** — every command shows read-only status when invoked without args (bare `abcd`, `abcd ahoy`, `abcd capture`, `abcd memory` all render status). The **suggested-next-actions** half of this convention is a design target: no shipped bare invocation yet emits next actions (bare `abcd launch` currently only hints to pass `--dry-run`). Provides discoverability without forcing the user to remember subcommand names.

Expand Down
3 changes: 2 additions & 1 deletion .abcd/record-lint.json
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@
"directory_coverage": {"enabled": true, "severity": "warn", "exempt": []},
"intent_lifecycle": {"enabled": true, "severity": "blocker", "intents_dir": "intents"},
"persona_registry": {"enabled": true, "severity": "blocker", "registry": ".abcd/development/personas.json"},
"context_status_free": {"enabled": true, "severity": "blocker", "target": ".abcd/work/CONTEXT.md"}
"context_status_free": {"enabled": true, "severity": "blocker", "target": ".abcd/work/CONTEXT.md"},
"surface_coverage": {"enabled": true, "severity": "blocker", "commands_dir": "commands/abcd", "skills_dir": "skills", "registry": ".abcd/development/brief/04-surfaces/README.md"}
},
"exempt_paths": [".abcd/development/research/", ".abcd/development/intents/superseded/"],
"exempt_if_status": ["superseded"]
Expand Down
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,17 @@ called out in a **Breaking** section.

### Added

- A `surface_coverage` record-lint rule (iss-35): the deterministic half of the
brief↔surface cross-check. It reads the plugin surface
(`rules.surface_coverage.commands_dir`, `skills_dir` — outside the lint roots)
and the brief's surface registry table (`rules.surface_coverage.registry`, by
convention `.abcd/development/brief/04-surfaces/README.md`), and asserts three
invariants: every real surface has a registry row; every row marked `shipped`
in the registry's **Status** column has a backing surface while every `staged`
row (a design target) has none; and every row's status is `shipped` or
`staged`. The bare `/abcd` top-level is binary-backed and exempt from the file
check. Chapter-link resolution stays with `links_resolve`; the semantic half —
each row's prose vs. binary behaviour — stays a release-gate agent check.
- A managed-repo **git-identity gate** (iss-62): a repo can pin its expected
commit identity in `.abcd/config/identity.json`, and every commit is checked
against it. `ahoy doctor` reports a divergence (a repo-local override that
Expand Down
13 changes: 11 additions & 2 deletions internal/core/lint/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -59,9 +59,18 @@ type RuleConfig struct {
// Allowlist is the stray_root_docs permitted basename-stem list (upper-cased,
// extension-stripped) for top-level markdown files.
Allowlist []string `json:"allowlist"`
// Registry is the persona_registry roster file, repo-relative
// (.abcd/development/personas.json).
// Registry is a rule's registry file, repo-relative. For persona_registry it
// is the persona roster (.abcd/development/personas.json); for
// surface_coverage it is the brief surface table
// (.abcd/development/brief/04-surfaces/README.md).
Registry string `json:"registry"`
// CommandsDir is the surface_coverage plugin-command directory (commands/abcd);
// each *.md file (README excepted) is a shipped command surface. It lies
// outside Roots — the rule reads the surface tree and cross-checks the brief.
CommandsDir string `json:"commands_dir"`
// SkillsDir is the surface_coverage skills directory (skills); each immediate
// subdirectory is a shipped skill surface. Also outside Roots.
SkillsDir string `json:"skills_dir"`
// Target is the context_status_free single-file target, repo-relative
// (.abcd/work/CONTEXT.md). The rule runs even though the target lies outside
// Roots; a missing target is not an error.
Expand Down
Loading
Loading