ADR-0141 — Artifacts live beside the agent's native artifacts; the store retires
Context
- A tool still owned the location. ADR-0137 Decision 2 placed artifacts "beside the agent's own scaffold" but made the CLI resolve the directory; ADR-0139 hardened that into a deterministic rule keyed on the repo's absolute path. Rule or service, the effect is the same: Suspec prescribes a filesystem location, and everything downstream (launch-prompt path handover, store commands, reconcilers) exists to serve the prescription.
- The agent already solves placement. A harness lands its own artifacts — plans, notes, memories — in its own conventions without any external rule. Describing intent ("put this next to your own artifacts, in a folder named for the repo you're working on, or wherever fits") is sufficient and portable across vendors; prescribing a path re-creates the store under another name.
- The management organs exist only because a tool owned a directory. Doctor, gc, decay, WIP caps, migrate, near-miss reconciliation — every one presumes Suspec is responsible for a location's hygiene. No owned location, no organs.
Decision
-
Skills describe placement; the agent chooses. The skills instruct: place Suspec artifacts next to your own native artifacts — the same place you keep your plans, notes, and memories — in a folder named after the repo you are working on, or wherever fits your harness best; keep them out of the repo unless the project's own governance says otherwise. No path is prescribed, no directory is set in stone, and no rule needs a tool to compute (upholds ADR-0134 Decision 3 trivially). Level: convention.
-
The store retires. No state root, no repo keying or encoding, no
suspec.config.jsonlocation config, no seeding or init, no doctor/gc/decay/WIP-cap/migrate, no launch-prompt path-handover contract, no store commands. Level: convention. -
Paths flow explicitly. Whoever needs a file names it by full path — a skill carrying a path forward through the work, a dispatch prompt naming its inputs, the checker receiving artifact paths as arguments (ADR-0143). Nothing discovers, resolves, or infers a store, a config, a repo root, or a workspace tree; the narrow exception is ADR-0143 Decision 4's artifact-relative sibling lookup for three reference checks (C009, C015, C010) — one level beside the passed artifact, never a tree walk. Level: convention.
Superseded and narrowed decisions
Superseded:
- ADR-0139 — the deterministic store-location rule loses its subject with the store; nothing computes a location anymore.
- ADR-0106 — keep-clean tooling (promotion-or-die, gc) managed a record Suspec owned; zero-noise is now structural by absence — there is nothing to manage.
Narrowed:
- ADR-0137 — "artifacts are transient and never
committed to any repo" stands as the default (Decision 1 above narrows it with a governance
exception, mirrored in ADR-0140 Decision 6);
Decision 2's CLI-resolved store, Decision 6's structural anti-rot machinery, and Decision 7's
suspec.config.jsonexception retire. Decision 4's repo-root worktree launch and its launch-prompt-as-store-pointer retire along with it — both the store it points into (Decision 2, above) and the CLI-generated launch prompt / worktree orchestration itself (ADR-0143, superseding ADR-0136). Durability by promotion (Decision 3) is retired by ADR-0142.
Alternatives considered
| Alternative | Why rejected |
|---|---|
| Keep the ADR-0139 rule (deterministic store location) | Any prescribed location — rule or service — drags the management organs back in and makes Suspec own hygiene it has no business owning. |
| Prescribe a canonical folder name only (no root) | Still a prescription; harnesses differ, and the agent knows its own conventions better than a cross-vendor rule can. |
Keep a minimal suspec.config.json for overrides | Config that configures nothing: with no resolution, there is nothing to override. |
Consequences
- Positive: zero Suspec footprint anywhere — no repo files, no owned home directory, no lifecycle machinery; placement guidance is one paragraph of prose that works on every harness.
- Negative: artifact locations vary by developer and harness; anything that wants a file must be handed its path (this is the design, but it forbids "list all my specs" tooling).
- Neutral: an agent that places artifacts beside its plans-and-memories scaffold will often produce something store-shaped anyway — by its choice, not Suspec's rule.
Status
Accepted (2026-07-10). Supersedes ADR-0139 and ADR-0106; narrows ADR-0137; upholds ADR-0134 Decision 3. Part of the ADR-0140 re-founding.
Propagation
docs/adrs/README.md— ledger row + disposition flips (0139, 0106, 0137).- Canon:
docs/03-where-files-live.md(rewritten around this decision), plus every page the ADR-0140 sweep names. - corpus-skills: the placement paragraph (byte-identical across the artifact-authoring skills)
and the self-containment editing rule in
AGENTS.md. - corpus-cli: the store module and every command premised on it (ADR-0143 owns the surface).
Need a starting point? Install the skills