glm-5.3-flash
4165c94ab0
Arm A: honker-core linked on our rusqlite (bridge per REQ-TTY-01, honker's watcher). Arm B: honker extension .so over sqlx-sqlite (natively async call path, own watcher, per-pool-connection extension + bootstrap — stress-testing what the CI proof script doesn't cover: pool wiring, lost connections, full surface). Option 2 (honker-rs-as-substrate) dropped from scope with reasoning: its mutex-pinned sync transaction model is subsumed by both other postures' trade space. Five probes (async seam, watcher, transactional contract, packaging, cross-process interop), a decision gate including a legitimate hybrid verdict, and out-of-scope boundaries (postgres side, full surface, extension-as-consumer-feature regardless of outcome). Phase-0: POC register added, plan/frontmatter updated; AGENTS.md: POC-register convention codified.
130 lines
6.3 KiB
Markdown
130 lines
6.3 KiB
Markdown
# AGENTS.md
|
|
|
|
Operating instructions for opencode agents working in this repo. opencode
|
|
auto-loads this file as instructions, overriding the built-in defaults for
|
|
this project. Custom agents in `.opencode/agents/` inherit these rules
|
|
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.
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
Exceptions — **do not** commit or push without asking:
|
|
|
|
- The change is exploratory / speculative (you're not sure the user
|
|
wants it kept)
|
|
- The user is actively reviewing the diff and may ask for changes
|
|
- You'd be force-pushing, amending a pushed commit, creating an empty
|
|
commit, or skipping hooks
|
|
|
|
Never commit secrets, keys, or credentials. If a commit fails or hooks
|
|
reject it, fix the issue and create a new commit — do not amend the
|
|
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
|
|
|
|
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:
|
|
|
|
- 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).
|
|
- 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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
- 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. |