internal/

README

internal/

abcd's Go implementation. The organising rule is a transport-agnostic core: all behaviour lives in core/ as functions that take a structured request and return a structured result, and the front doors under surface/ only marshal those results for their transport. This is what lets the CLI, the markdown plugin surface, and a future MCP server share one engine.

Package map

• core/ — the engine. One package per capability; no stdout, prompt text, or transport coupling. The capability set is the subdirectory set — browse core/ for it rather than a list kept here, which drifts the moment a phase lands (adr-5, derive don't store). The bullets below cover the packages whose boundary is not obvious from the name.
• core/changelog/ — release derivation. Holds impact, the one product judgement a record declares, and derives the next SemVer from the records that entered the terminal folders since the anchor tag. It owns the enum so the lints that GATE the judgement (core/lint), the ledger reader that VALIDATES it (core/capture), and the derivation that CONSUMES it cannot drift apart.
• core/surface/ — the compatibility surface as DATA: the snapshot of every command, flag, and manifest entry a consumer binds to, and the diff that names what a release narrowed. It shares a word with the surface/ front-door tier and nothing else — that tier is about transports, this package is about what those transports expose — so it is cobra-free like the rest of core/. The walk that reads the live command tree needs cobra and therefore lives in surface/cli, which hands its result in; the dependency never points back.
• core/site/ — the website as a rendering of this repository (adr-47). It shares a word with nothing else here and is easy to mistake for a front door, so: it is a pure producer of files, transport-free like the rest of core/, and it writes only inside the output directory it is handed. It carries LAYOUT and no prose — every sentence it emits is a span of a repository file selected by .abcd/site.json, and the only words it may add are the closed allowlist in site-src/ui.json. The record graph it renders comes from core/lint's own record scan (LoadRecordGraph), never a second parser; the dates come from one git log pass; the chart arrangements are computed here so the published pages need no layout engine and make no requests.
• core/cite/ — the live half of the citation gate: the bounded fetcher and the refresh that writes the committed baseline core/lint then enforces with zero network. It is the only place abcd dials out on behalf of documentation, and it holds the seam a specialist link checker would later slot into — the baseline schema and the lint rules are the contract, the fetcher is a replaceable producer.
• core/lifeboat/ — the brief↔lifeboat contract. mapping.go is the single source of truth for which brief section a lifeboat fills from which source tier, and it is rendered into the brief's 00-meta.md with a test asserting the two agree. The table is a hypothesis: abcd disembark probe measures the same sections against real repositories in the same grounded/partial/blank vocabulary, and the evidence is expected to revise it (adr-35, itd-88).
• core/glossary/ — the brief glossary's index, derived. The term files under .abcd/development/brief/glossary/ are the source of truth for what terms exist and in which bounded context; this package renders the directory tree and the term index its README carries, and a test in the same package holds the committed README to that render. It is a generator and a gate, not a validator: the frontmatter shape is specified by the glossary README, and the rule that READS a term's frontmatter for enforcement is GL002 in core/lint.
• core/guard/ — the shell-hazard registry. Bundled hazard entries (id, command-position pattern over shell tokens, blocker/warn tier, safe successor, plain-language why) plus the deterministic allow/warn/block decision a harness hook calls before a command runs. Matching is token-aware and command-position only, so a hazard named inside a quoted argument never fires; every bundled entry ships known-bad and known-good fixtures, and the admission gate test holds each one to its own corpus (100% true-negative floor, at least 40% known-good). An allow means no entry matched, never that a command is safe: a hazard reached another way — a string handed to an interpreter (eval, sh -c), a launcher outside the wrappers set, a launcher inside it carrying a value-taking flag wrapperValueFlags does not name, an ArgPaths root segment the host serves under a prefix (a GitHub Enterprise Server /api/v3/ mount; pathOf normalises a scheme://host URL, not a mount point), a backtick substitution, or a form no entry describes — is not seen. Each limit is stated here and in the abcd guard check reference doc, never left implicit. Load reads the working tree, so a disabled: true takes effect before it is reviewed; the front door compensates by making a disabled registry loud rather than silent. Fail-open-loud on a broken guard belongs to the hook shim (hooks/hooks.json) and the abcd guard hook adapter, not here.
• core/banlist/ — the two banned-names stores (itd-74, spc-20). The public layer is managed IN the docs-lint banned_tokens family under a names/ id prefix: one banned-token primitive, and the prefix is the ownership boundary a removal respects. The private layer is the gitignored per-machine store, whose FIRST line declares its format — keyed (KEY<space-or-tab>PATTERN) or legacy (one whole-line pattern per line) — which the committed .githooks/pre-commit guard parses identically. Three shared fixture corpora under testdata/ are read by both parsers, so their agreement on the keyed format, the legacy format, and every unusable line class is checked rather than assumed. Enforcement is NOT here: the hook is the private layer's enforcement point and core/lint the public one, so this package owns the stores, their formats, and their editing discipline. It does VALIDATE against each layer's own engine, though — a private pattern goes to grep on stdin, a public one through the linter's compile path — because a pattern checked against a third engine is stored as healthy while it matches nothing. Redaction is structural — the exported private entry type carries no pattern field, so no rendering can leak a value — and edits are surgical (a line for the private store, byte surgery on the located array for the config), never a whole-file re-marshal. Scaffolding is NOT here either: core/ahoy writes the five artefacts (the two committed guard hooks, the .gitattributes line keeping them at LF, the public family, and the gitignored stub) into a repo it configures, importing this package for the paths and for the one canonical statement of the private layer's reach.
• adapter/scanner/ — the secret/PII seam, and the first adapter seam to ship. Its native implementation is pure Go with no external dependency: a bundled secret-pattern set plus the probed machine identity, layered with an optional per-repo .abcd/config/pii.json override that may raise a severity but never lower one past the floor. It fails closed — an override that cannot be read, parsed, or compiled marks the scanner unavailable rather than letting a caller sanitise with a silently weakened pattern set — and redaction masks by byte span, so two secrets on one line cannot leak each other through the snippet they share. core/launch consumes it before a bundle is published; external scanners stay config-selected plug-ins behind the same seam.
• surface/cli/ — the default front door: a Cobra command tree that calls core and formats results as text or --json. Holds no business logic.
• surface/mcp/ (later) — an additive front door exposing the same core verbs as mcp:abcd:* tools. Added once a surface is worth exposing; no core rework required because the core is transport-agnostic.

Planned seams (added when a phase consumes them, never as dead scaffolding)

Per the project rule "wired or it isn't done," the remaining pluggable adapter seams are introduced by the phase that first uses them, not pre-emptively. The list is gated rather than trusted: the index_drift record-lint rule holds every path in the marked region to being absent from the tree, so a seam that ships cannot go on being described here as planned.

• adapter/oracle/ — LLM review. Native default = host-delegated (the host runs subagents); opt-in plug-ins: claude CLI, Anthropic API, MCP oracle.
• adapter/history/ — transcripts. Native default = redacted local store; opt-in: private companion/remote, specstory cloud.
• adapter/spec/ — spec/task store. Native minimal default; opt-in: the companion harness ccpm at the convention level.
• adapter/run/ — autonomous run. Native thin loop fallback; host backends: Claude Workflows, the companion harness's agent loop.
• registry/, config/ — declarative wiring of chosen adapters.

The full rationale is in the plan and the design record under .abcd/development/.