Core error taxonomy + name validation (ADR-008 §4/§5, ADR-017 §3); AGENTS.md updated to Phase 1 posture

AGENTS.md

@@ -7,27 +7,30 @@ unless their own prompts say otherwise.
 
 ## Repo posture
 
-This repo is in **Phase 0 (Exploration)** per `docs/sdd_process.md`.
-There is no crate yet — no `Cargo.toml`, no `src/`, no README (the README
-gets written just before first publish, so it can be honest about what
-shipped). What exists is `docs/research/phase-0.md` (the Phase 0
-document: vision, prior art, open questions, POC register), the SDD
-process (`docs/sdd_process.md`), and the agent defs
-(`.opencode/agents/`). Do not scaffold implementation code
-from this posture unless a task or the user asks for a POC.
+This repo is in **Phase 1 (Implementation)** per `docs/sdd_process.md`.
+Phase 0 concluded with the converged recommendation and the accepted ADRs
+(`docs/architecture/decisions/`, `docs/architecture/README.md`); the
+implementation plan (`docs/plans/implementation.md`) decomposes waves of
+work into task files in `tasks/`. Three crates exist (ADR-001's Cargo
+workspace split): `alkstore` (core — the contract artifact),
+`alkstore-sqlite`, `alkstore-postgres`. Work proceeds task-by-task from
+`tasks/`; check a task's `status` and `depends_on` before picking it up.
 
-Do not treat `docs/research/phase-0.md` as settled architecture — it is
-a working research document whose open questions are genuinely open.
-The hedging rules of `docs/sdd_process.md` (no circular deferrals, no
-"resolved with escape hatches") still apply to it.
+The architecture documents — `docs/architecture/` (core-contract.md, the
+ADRs, the engine specs) — are the normative spec for code work. Where
+code and ADR disagree, the ADR wins: fix the code, or (if the ADR is
+genuinely wrong for a reason no ADR anticipated) raise the discrepancy
+with the user before deviating. ADR amendments pre-implementation are
+class-1 events under ADR-017 §2 — but that class terminates at first
+release, so the window is now, not forever.
 
 ## Git Workflow
 
 **Commit and push when reasonable.** When a change is complete and
 verified, commit and push to `origin/main` without asking. This
 overrides the built-in default of "only commit when explicitly asked."
-In Phase 0 "verified" means the doc checks below — there is no build
-gate yet.
+"Verified" means the Verification Commands below pass for any crate the
+change touches.
 
 Exceptions — **do not** commit or push without asking:
 
@@ -44,87 +47,78 @@ failed one.
 Git identity is preconfigured (`glm-5.3-flash <glm-5.3-flash@alk.dev>`). Do
 not change `git config`, skip hooks, or use `git commit -i`.
 
-## Phase 0 conventions
+## Code conventions
 
-1. **Findings land in `docs/research/`.** Research notes, POC
-   specifications, and POC findings all go there, named consistently
-   (`poc-<name>-spec.md` / `poc-<name>-findings.md` follows the
-   alkblobs precedent). A POC that needs this repo's code runs in a
-   worktree (`.worktrees/research/<task-id>/` per the SDD process); a
-   self-contained POC (like the alkblobs ones) runs as a standalone
-   crate in the global workspace. Findings land in this repo either
-   way.
-2. **Open questions get OQ-ST-NN IDs** and live in the register in
-   `docs/research/phase-0.md` until Phase 1 promotes them to
-   `docs/architecture/open-questions.md`. Numbering is stable — never
-   renumber; append. POCs live in the register there too (numbered,
-   spec'd under `docs/research/poc-<name>-spec.md`, findings in
-   `poc-<name>-findings.md`).
-3. **Cite reference checkouts by path and revision.** The external
-   references for this crate (`/workspace/honker` @ f4e53c6,
-   `/workspace/pgboss-rs` @ 98f7d9e) are reference checkouts of
-   third-party projects — read freely, but never wire the checkout
-   itself into our code. Use the published version unless we vendor or
-   fork it (alksocks' fast-socks5 precedent); if a fork is warranted,
-   forking is normal work. Note the checkout state when your findings
-   depend on code specifics; licenses and provenance get recorded when
-   we adopt code, not while only reading.
-4. **POC code stays out of this repo** until Phase 1 adopts it. A POC
-   crate proves the hypothesis and reports findings; it does not
-   pre-scaffold the real crate layout.
-5. **No mock/main-repo documentation.** No README, no CHANGELOG, no
-   crate-level docs until the shape exists. Docs that describe a thing
-   that doesn't exist are exactly the kind of dishonest artifact we
-   write docs to avoid.
-6. **No comments in code** (when POC crates get written) unless the
-   user explicitly asks. Doc comments (`///`, `//!`) are fine on public
-   API. Inline `//` comments only when a non-obvious safety/correctness
-   constraint would otherwise be missed, or the user asks.
-
-## Conventions that will apply once the crate exists
-
-These are family-standard and pre-committed; they'll be duplicated into
-task prompts and tightened by Phase 1 ADRs:
+Family-standard and pre-committed; the ADRs carry the load-bearing
+decisions:
 
 - Rust crate, `tokio` async runtime, `thiserror` error types, no panics
   in library code, no `unwrap()`/`expect()` outside tests.
-- No comments in code (see 6 above).
+- No comments in code unless the user explicitly asks. Doc comments
+  (`///`, `//!`) are fine on public API — and required where a task pins
+  semantics into doc text (core's docs are part of the contract).
+  Inline `//` comments only when a non-obvious safety/correctness
+  constraint would otherwise be missed, or the user asks.
 - Module-per-file under `src/`, re-exported from `src/lib.rs`; public
   API surface is the lib re-exports.
-- Optional dependencies (the postgres engine likely being the first)
-  are feature-gated; the base crate compiles lean; both
-  `cargo test --features <set>` and default-feature builds pass when
-  features exist.
-- Categorical estimates (`scope`, `risk`, `impact`, `level`) in every
-  task file — per `docs/sdd_process.md` these are structurally
-  required, not optional metadata.
+- No CI wiring (manual CI per `docs/plans/implementation.md`).
+- `#[non_exhaustive]` policy is ADR-017 §3's: on consumer-*read* types
+  (`Error`, `StreamEvent`, `Job`, `Schedule`, `Wake`), never on opts
+  structs consumers construct.
+- Core (`alkstore`) has no driver dependencies, ever (ADR-001); payload
+  encoding's `serde`/`serde_json` are the sole core deps (ADR-020 §4).
+- Engine crates depend on core with the versioned path pin (ADR-017
+  §4.1) — never the reverse.
+
+## Task files
+
+Every task file in `tasks/` carries categorical estimates (`scope`,
+`risk`, `impact`, `level`) — per `docs/sdd_process.md` these are
+structurally required, not optional metadata. On completion: update the
+task's `status` to `completed`, and fill its **Notes** (decisions of
+record the implementation made that the description didn't pin) and
+**Summary** (what landed, verified how) sections — the next agent reads
+those instead of re-deriving them.
 
 ## Verification Commands
 
-Phase 0 — none (no code yet). The doc conventions above are checked by
-reading. When the crate appears, this section gets the standard Rust
-gates (`cargo test`, `cargo clippy --all-targets -- -D warnings`,
-`cargo fmt --check`, and the fuzz corpus replay if fuzzing is adopted —
-the alksocks/alktty/alktunnels pattern) and becomes the merge gate the
-coordinator runs.
+Standard Rust gates, run from the workspace root; they are the merge
+gate:
+
+```
+cargo build            # workspace compiles
+cargo test             # workspace tests (task-scoped: cargo test -p <crate>)
+cargo clippy --all-targets -- -D warnings
+cargo fmt --check
+```
+
+No fuzzing is adopted (no fuzz corpus replay gate — the
+alksocks/alktty/alktunnels fuzz posture was not carried into this
+crate's plan); revisit only if a task or ADR introduces it.
 
 ## Architecture Context
 
-- `docs/research/phase-0.md` — the Phase 0 document: vision, prior
-  art, open questions (OQ-ST-01..NN), the POC register, and (eventually)
-  the converged recommendation. Read it before any non-trivial work in
-  this repo.
-- `docs/research/consumer-inventory.md` — the per-feature scope
-  synthesis answering OQ-ST-01 from the paused consumers' documents.
-  New consumer needs get a row there *before* any scope decision
-  assumes them.
-- `docs/sdd_process.md` — the SDD process. Phase 0 in progress;
-  `docs/architecture/` does not exist yet.
+- `docs/architecture/README.md` — the decision index; start here.
+- `docs/architecture/core-contract.md` — the contract of record for the
+  core crate's surface (the traits, types, error taxonomy, naming /
+  reserved namespace, delivery-guarantee table, verification backlog).
+- `docs/architecture/decisions/` — the accepted ADRs (ADR-001..021).
+- `docs/architecture/open-questions.md` — the open-question register;
+  resolved OQs cite their ADRs. Numbering is stable — never renumber;
+  append.
+- `docs/plans/implementation.md` — the wave-based implementation plan;
+  `tasks/` decomposes its waves.
+- `docs/research/` — the Phase 0 record (phase-0.md, POC specs and
+  findings, the honker/pgboss reference reads,
+  consumer-inventory.md). Reading it is background, not obligation;
+  the ADRs supersede it where they disagree. New consumer needs still
+  get a `docs/research/consumer-inventory.md` row *before* any scope
+  decision assumes them (the row-first gate, ADR-017 §2).
 - The SDD process and agent defs were copied from downstream projects
   (alkblobs) in the workspace; project-specific stale references were
   cleaned at Phase 0 setup (2026-10-03). If you find a section that
   assumes another crate's machinery, fix it rather than working around
   it — same discipline as stale TODOs.
 - If a TODO or doc reference cites a design direction that a later ADR
-  or Phase 0 decision rejected, the reference is stale — remove it and
-  align; do not implement the rejected design.
+  or decision rejected, the reference is stale — remove it and align;
+  do not implement the rejected design.