@agentsfleet/orly 0.5.0

package/dispatch/lifecycle.md

@@ -0,0 +1,187 @@
+# lifecycle.md — stage-runbook latent façade
+
+Read this at a lifecycle stage transition: CHORE(open), PLAN, EXECUTE onboarding,
+CHORE(close), LAND, worktree setup, or milestone bootstrap. The generated
+`AGENTS.md` carries each stage's binding essence; this façade carries the
+runbooks — the checklists, recipes, and output formats an agent needs only at
+that moment. 🤔 judgment-only — no `.sh` pair; CONFORM's deterministic gates and
+`orly gate` remain the mechanical anchors.
+
+Section-scan first (`grep -n "^## " dispatch/lifecycle.md`); read the stage you
+are entering, not the whole file.
+
+## CHORE (open) — runbook
+
+1. Spec `docs/v*/pending/` → `active/`; `Status: IN_PROGRESS`; `Branch:` set.
+2. **Test Baseline** — run the repository's declared `verify.unit` (and
+   `verify.integration` where declared) from `.oracle/orly.json`; copy the
+   reported counts into the spec header as `**Test Baseline:** unit=<N>
+   integration=<M>` (VERIFY's Test Delta row compares against it; a product
+   pack may name a dedicated counter — see the product block below).
+3. Create the worktree; verify CWD is inside it (`pwd` + `git worktree list`).
+4. Commit the four steps on the feature branch. No code until the commit lands.
+
+<!-- oracle-packs:start product.agentsfleet -->
+## Worktree recipe (agentsfleet)
+
+`git checkout main && git branch feat/mNN-name && git worktree add ../agentsfleet-mNN-name feat/mNN-name && cd ../agentsfleet-mNN-name && bun install && (cd cli && bun install && bun run build)`.
+The root `bun install` hydrates the workspace (`ui/packages/*`); `cli/` is its
+own Bun project needing install + build. `git worktree add` fires
+`.githooks/post-checkout` → symlinks `~/.config/agentsfleet/{ui,runner}.env.local`
+into the tree; on 🟠 run `provision-env-1password`, re-link. Post-merge:
+`git worktree remove ../agentsfleet-mNN-name`.
+
+**agentsfleet Test Baseline counter:** `make _lint_zig_test_depth`.
+
+**agentsfleet CHORE(close) paths:** the `<Update>` lands in
+`~/Projects/docs/changelog.mdx` (template + version-bump matrix:
+`skills/release-template.md` in the governance checkout — re-source each
+release, never paraphrase). Version sync: `VERSION` touched → `make
+sync-version`; commit propagated `build.zig.zon` / `agentsfleet/package.json` /
+`agentsfleet/src/cli.js`; `make check-version` passes.
+
+**dotfiles takes NO worktree — feature branches in the main checkout.** Every
+agent-home symlink and every consumer's `ORLY_ROOT` resolves to
+`~/Projects/dotfiles`; a linked worktree's `.git` is a *file*, and the audit
+chain the hooks run spawns git against other directories. Under a hook that
+combination corrupted the real index and flipped `core.bare` (Aug 16, 2026).
+So: `git checkout -b feat/mNN-name` in `~/Projects/dotfiles` itself, and
+`orly update` always renders the one true root. One stream at a time —
+a second concurrent agent coordinates in-session rather than forking a tree.
+This is the dotfiles exception; product repos keep the worktree recipe above.
+<!-- oracle-packs:end -->
+
+**Mid-stream spec → ask before hydrating (default: same tree).** A spec created
+inside an active worktree → ask the user before spinning up a second one. Lean
+same tree: a second tree fragments the outcome and adds a PR to babysit.
+Complete the outcome in place; fold new scope into the current spec/PR (reopen
+`done/`→`active/` if closed) unless the work is genuinely disjoint AND the user opts
+into a separate tree.
+
+## Bootstrap & milestone gates
+
+- **Complete `.oracle/orly.json` on first sight.** `orly init` seeds it
+  mechanically — it reads the Makefile (following `include` one level) and
+  `package.json` scripts, matches a fixed list of target names, and writes what
+  it matched. It finds the obvious ones and misses the rest, and it never
+  guesses `surfaces`.
+  First session in a repository whose config is still that seed:
+  1. Read the build files properly. Fill every `verify.*` the repository really
+     has — the tiering is fixed (`conform` + `verify.unit` are the fast tier,
+     every other `verify.*` is slow and skips on prose-only branches).
+  2. Set `surfaces.user` and `surfaces.docs` to real path prefixes, or the docs
+     gate can never fire and a user-visible change ships undocumented.
+  3. Add any opt-in pack the repository's own sources cannot imply
+     (`persona.indy`, `product.agentsfleet`, `workflow.governance`), then run
+     `orly update` so they materialise.
+  4. Commit it. Every teammate and every later session reads this file, and
+     `orly` never rewrites it — so an edit here is permanent.
+  A seeded-but-uncompleted config is why `orly gate` reports a repository with
+  no declared commands: the fix is this list, not another `orly init`.
+- **Priming:** (1) Human runs `playbooks/founding/01_bootstrap/001_playbook.md`.
+  (2) Agent runs `./playbooks/founding/02_preflight/00_gate.sh` (green before
+  next). (3) Agent runs `playbooks/founding/03_priming_infra/001_playbook.md`.
+  Milestones only after PRIMING_INFRA verified.
+- **Credential gate** — milestones needing external creds start `M{N}_001`
+  enumerating every downstream credential (name + fetch location). Fail loud
+  listing all missing before any `M{N}_002+`.
+- **Agent-first sequencing** — minimize human steps; post-handoff steps
+  retryable + idempotent. Vault is the inter-step interface; never pass creds
+  by argument/env.
+
+## PLAN — expansions
+
+**Quality-ceiling line** — would it be more performant / leaner / a better user
+experience (fluid) / sounder under concurrency if built differently, and would a
+larger refactor beat the patch? Default solution-size ≈ problem-size; "yes" →
+surface option + cost, the user picks. Read docs when behavior is unclear.
+
+**Surface-area checklist** — yes/no + reason each: OpenAPI changes (list paths)
+· the product's CLI · user-facing docs · release notes
+/ version bump · schema changes (≤100 lines/file, single-concern, update
+`schema/embed.zig` + migration array) · Schema Removal Guard output ·
+spec-vs-rules conflict (amend spec).
+
+## EXECUTE — spec discipline expansions
+
+- **Golden-path before PLAN approval** — walk the concrete end-to-end with every
+  lookup/data-source/secret-storage named; any `[?]` blocks the spec.
+- **DONE = called in production + tested** — grep the production entry-point for
+  the named symbol; no call → not DONE.
+- **Changelog claim challenge** — before any `<Update>`, ask "Would this be true
+  if the test file vanished?" Only test evidence (not middleware/handler/CLI) →
+  claim unearned.
+- **Spec → Code → Test alignment:** every Dimension → test case (no test = not
+  implemented); every Interface → exact spec signature (signature change →
+  update spec first); every Acceptance Criterion → verifiable command ("works
+  correctly" is not a criterion; "`make test` passes" is); no code commits
+  without tests (`/orly-write-unit-test`); every Error Table row → negative test.
+- **Recovery notes:** local Docker `ENOSPC` → `~/bin/mac-cleanup.sh`, verify
+  `docker system df`, retry.
+
+## CHORE (close) — required outputs
+
+- All Dimensions/Sections `DONE` (`IN_PROGRESS` if parked); spec moved
+  `docs/v*/active/` → `docs/v*/done/` iff complete.
+- Changelog: a new entry on the repository's declared docs surface
+  (`surfaces.docs`; `write_changelog` façade where materialised) for
+  user-visible changes **AND, re-reading the spec, the affected published docs
+  pages revised to match (endpoints/CLI/flags/behavior)** — an entry alone is
+  insufficient when documented behavior changes. Product-specific paths: the
+  product pack block above.
+- `docs/architecture/**` carries a non-empty diff for flow-defining changes, or
+  Session Notes says why not (`dispatch/name_architecture.md` covers both homes).
+- PR `## Session notes`: decisions, assumptions, dead ends, deferrals,
+  `/orly-write-unit-test` + runtime review outcomes, `orly-babysit-prs` final
+  report.
+- Orphan sweep complete (RULE ORP); ephemeral handoff docs deleted
+  (`docs/**/HANDOFF_*.md`, `docs/**/handoff*.md`, `HANDOFF.md` at any depth —
+  they brief the next agent, never the PR).
+- Pre-commit `git status -uall` audit — every modified/untracked/
+  conflict-resolved/hook-managed file staged into the CHORE(close) commit, or
+  documented-as-excluded with reason in the commit body; `git status` MUST be
+  empty post-commit before opening/updating the PR.
+- Version sync where the repository defines it: declared version targets green
+  before the PR. Product-specific targets: the product pack block above.
+
+## Deferral discipline — expansion
+
+Any claim that a spec Section/Dimension was "deferred to follow-up" — in
+`HANDOFF.md`, PR description, Session Notes, or chat — requires an
+**user-acked verbatim quote** in PR Session Notes (or spec Discovery). Format:
+`> Indy (YYYY-MM-DD HH:MM): "<verbatim ack>" — context: <which item, why>`.
+Agent-unilateral deferral = incomplete scope, not deferral; CHORE(close) blocks
+until the item lands or the quote is captured. **HANDOFF.md is a faithful state
+report** — a pickup agent reading a HANDOFF claiming items were deferred without
+ack-quotes must treat them as in-scope and surface the contradiction to the user
+before continuing.
+
+## Pre-PR gates
+
+Spec in `docs/v*/done/` in diff (skip iff parked); the repository's changelog
+surface carries a new entry in diff (skip iff internal-only or parked);
+`Status: DONE` but spec not in `done/` → do not open PR; the repository's
+version-sync check passes where defined; branch contains `origin/main` HEAD
+(rebase pre-push / merge post-push — never force-push an open PR branch).
+
+**`orly gate pr` follows the spec through the close.** A spec moved to `done/`
+on this branch is still discovered — its `Branch:` header names the branch —
+and every spec criterion runs against it; skip-pass is only for genuinely
+spec-less branches. Mechanical criteria: `spec.moved` (`Status: DONE` ⇒ the
+spec sits under `done/` and was moved on this branch) · `spec.baseline`
+(`Test Baseline:` recorded) · `spec.ordering` (the branch's first commit
+carries the spec — no code before CHORE(open)) · `spec.deferrals` (a deferral
+claim needs the `> Indy (` ack quote in the spec). An Indy-acked deferral that
+leaves a Dimension open ships via `orly override spec.dimensions --reason
+"<the ack>"` — visible in the PR, dead after the merge.
+
+**Babysit detail:** `orly-babysit-prs` covers all three surfaces — CI check
+runs (fix every failure your diff caused), greptile inline comments, and the
+PR-level summary thread — and stops on two consecutive empty polls with CI
+green. Never `gh pr checks --watch` for greptile.
+
+## LAND (after merge, or when the user confirms it merged)
+
+`git checkout <default> && git pull origin <default>`; prune the merged worktree
+and branch; `make down` where the repository defines it. Pending files → stash,
+pull, diff against the new default; already-landed → drop.

package/dispatch/name_architecture.md

@@ -0,0 +1,93 @@
+# name_architecture.md — architecture-consult dispatch (LATENT façade)
+
+This is the prose the AGENT reads **before naming an architectural element or
+describing a data flow**. Like `verify`, it has **no deterministic `.sh` half** —
+no script can detect the moment an agent is *about to name a stream* or *assert a
+cardinality*. It is a pure **🤔 judgment** dispatch grounded in `docs/architecture/`.
+(This is the former Architecture Consult & Update gate absorbed into the dispatch model.)
+
+**Signal legend:**
+
+- 🤔 DECIDE — judgment-only; the agent greps the relevant `docs/architecture/`
+  topic file and grounds its naming/flow claim in it. Blocks the *turn*, not a
+  commit.
+
+## Trigger — grep/read the relevant `docs/architecture/` topic file before
+
+- Naming a stream / pub-sub channel / Redis key namespace / consumer group /
+  queue / RPC method / Postgres schema / table.
+- Asserting cardinality ("one row per X", "exactly one consumer per stream",
+  "fleet-wide vs per-tenant").
+- Describing a flow ("on crash → X reclaims via Y", "trigger source A lands on
+  stream B with actor C").
+- Answering a user question about how data flows between components.
+- Proposing a change to any of the above as part of a spec or implementation.
+- A new architecture-adjacent question that arises mid-task — re-consult per
+  topic, not once per task.
+
+**Override:** none — doc wins until reconciled.
+
+## Why
+
+`docs/architecture/` (the directory; topic files linked from
+`docs/architecture/README.md`) is canonical for stream/channel/queue names, table
+cardinality, ownership, and end-to-end flows. The failure mode is reinventing
+terms or asserting flow shapes from training data instead of grounding in the
+doc. Specs are *instances*; this doc is the *constant* — when they disagree, the
+doc wins until reconciled.
+
+## Behavior
+
+- **Doc answers** → proceed (no citation block).
+- **Doc silent** → proceed with extra care; land doc decision in same commit.
+- **Doc conflicts** → surface with a one-line citation (`grounded in §X.Y,
+  proposal extends/conflicts because <reason>`) and wait.
+- **Greenfield** → land initial doc + code in same commit.
+
+## Landing rule (non-negotiable)
+
+An architecture decision lands its `docs/architecture/` edit either:
+
+- **(a)** immediate doc-only commit on the active branch (preferred), OR
+- **(b)** same commit as the implementation.
+
+**Never** (c) follow-up commit AFTER the code.
+
+**Chat brainstorming counts as "describing a flow."** A multi-turn chat designing
+a new pattern (naming a channel, asserting cardinality, tracing a flow, defining
+an invariant) HAS fired the dispatch even if no code touched yet. Acceptable
+resolutions: (a) doc-only commit BEFORE the next agent action, or (b) Indy-acked
+deferral quote (per CHORE(close) deferral discipline) routing the capture into
+same-commit-with-code. The failure mode this clause names explicitly: encoding the
+brainstorm as a "punchlist task to land after the code ships" — that's exactly (c)
+and is forbidden. Pickup agents reading a task whose description says "capture
+architecture in docs/architecture/ AFTER <slice> lands" must rewrite it to
+same-commit OR doc-only-now before continuing.
+
+## Required output (only when doc conflicts or is silent)
+
+```
+ARCH: grounded in <topic-file>:<§X.Y> | proposal: <one-line> | status: <extends|conflicts|silent> | landing: <a|b>
+```
+
+When the doc directly answers, no output is required.
+
+## CHORE(close) check — both doc homes
+
+Architecture truth has TWO homes with different audiences; an architecture-touching
+branch settles both before the Pull Request (PR) opens:
+
+- **Product repo `docs/architecture/**`** (internal design truth). Every M-spec
+  branch that touched flow-defining code produces a non-empty
+  `git diff origin/main..HEAD -- docs/architecture/`. Else PR Session Notes
+  documents why nothing architectural changed.
+- **Docs project `~/Projects/docs/`** (user-facing, `docs.agentsfleet.net`). When
+  the change alters documented user-facing behaviour (endpoints, Command-Line
+  Interface (CLI) surface, flags, flows users see), the affected pages are
+  revised per the CHORE(close) required
+  outputs in `AGENTS.md` — a changelog `<Update>` alone is insufficient.
+  Internal-only reshaping with no documented-behaviour change → no docs-project
+  edit, and Session Notes say so.
+
+Updating one home and not the other is the failure mode this section names: the
+internal doc drifts from what users are told, or vice versa.

package/dispatch/verify.md

@@ -0,0 +1,111 @@
+# write — verify.md — verification dispatch (LATENT façade)
+
+This is the prose the AGENT reads **before emitting any message that asserts work
+is verified**. Unlike `write_zig` / `write_any`, `verify` has **no deterministic
+`.sh` half** — no script can detect the moment an agent is *about to claim done*.
+It is a pure **🤔 judgment** dispatch: the agent reads this, runs the canonical
+`make` targets, and emits the verdict block. The trigger is a *claim*, not a file
+edit. (This is the former Verification gate absorbed into the dispatch model.)
+
+**Signal legend:**
+
+- 🤔 DECIDE — judgment-only; the agent must run the targets below and report
+  honestly. No script gates this — it blocks the *turn*, not a commit.
+- 🟣 delegated — the `make` targets themselves live in the product repo; dotfiles
+  carries only the discipline of *which* targets are canonical and when.
+
+## Trigger
+
+Fires before any user-facing message asserting verification: *"tests pass",
+"ready to merge", "shipping", "ready for review", "CHORE(close) ready"* — or any
+equivalent.
+
+**Override:** `VERIFY GATE: <target> skipped per environment constraint (reason: ...)`.
+Only when a target is genuinely unrunnable (e.g. Docker missing for integration
+tests). Surface the limitation in the done message — never dress a skip as "tests
+pass".
+
+## Why `make` is canonical
+
+Package-scoped runners (`bun run test`, `vitest <file>`, `zig build test` without
+the integration tier) are **not** verification — they skip cross-package lint,
+cross-compile, pg-drain, and integration. `make` targets are the canonical gates.
+
+## Required runs
+
+| Target | When |
+|---|---|
+| `make lint` | Always. |
+| `make test` | Always (tier 1, unit-only by definition). |
+| `make test-integration` | Tier 2: diff touches HTTP handlers, schema, DB code, Redis code, or any `_integration_test.zig`. Focused subsets: `make test-integration-db` / `make test-integration-redis`. |
+| `make test-integration` | Tier 3: at least once per branch before declaring ship-ready, from a clean state (e.g. after `make down`) when tier 2 is intermittent — fresh DB proves no state carry-over. |
+| `make memleak` | Server lifecycle (`src/http/**`, `src/cmd/serve.zig`), allocator wiring, cross-thread heap ownership. |
+| `make bench` (local) | Diff touches request-path code, allocator wiring, or startup/shutdown sequencing. |
+| `API_BENCH_URL=https://api-dev.agentsfleet.net/healthz make bench` | After branch deploys to dev. |
+| Cross-compile `x86_64-linux` + `aarch64-linux` | Whenever `*.zig` touched. |
+| `make check-pg-drain` | Whenever `*.zig` touched. |
+| `/orly-write-integration-test` (skill) | With `/orly-write-unit-test` at VERIFY when the diff crosses module boundaries with real I/O; otherwise record `N/A — <reason>`. |
+| Acceptance e2e (product repo's live tier) | Diff touches a surface the live/acceptance tier covers — relevant acceptance suites green, or their opt-in skip matrix recorded. |
+
+`make test` never substitutes for tier 2/3. Tier 2 passing but tier 3 failing
+means state pollution — fix isolation before shipping.
+
+## Memleak evidence rule
+
+Before CHORE(close) reports green, paste the final `make memleak` result line into
+the PR Session Notes block OR cite the CI memleak job URL. Branches touching
+`src/http/**`, `src/cmd/serve.zig`, or allocator wiring MUST include the last 3
+lines verbatim. No "I ran it, trust me."
+
+## Coverage discipline
+
+- **Branch coverage is the goal; line coverage is the floor.** One input "covers" a multi-clause condition while leaving its logic untested (`trimmed === "" || === "y" || === "yes"` passes line coverage with a single `"y"`). Feed varied inputs across the equivalence classes — each OR clause independently, success-retry AND fail-retry paths, every early-return guard, empty/casing/whitespace/garbage for normalizers. bun's lcov emits no branch records, so this is test-design discipline, not a number to chase.
+- **Do not chase per-file 97% on declaration-heavy files.** bun marks compiler-erased lines (`import type`, `interface`) as 0-hit — no test can execute them, and restructuring to lift the number backfires (inlined type literals get instrumented as 0-hit too). The enforced gates are **aggregates** (`enforce-coverage.mjs` global row; codecov patch across uploaded packages); a few erased lines dilute to noise there. No codecov `ignore` entries either — gate on the aggregate.
+
+## Bench knobs
+
+`make/test-bench.mk` env vars: `API_BENCH_METHOD`, `API_BENCH_DURATION_SEC`,
+`API_BENCH_CONCURRENCY`, `API_BENCH_TIMEOUT_MS`, `API_BENCH_MAX_ERROR_RATE`,
+`API_BENCH_MAX_P95_MS`, `API_BENCH_MAX_RSS_GROWTH_MB`.
+
+## Required output (done-message)
+
+**Success:**
+
+```
+✅ Verified: 🧪 lint ✓ · 🧪 test ✓ <N>p/<M>s · 🧩 test-integration ✓ (or N/A — no handler/schema/redis) · 🎯 cross-compile ✓ (zig only)
+```
+
+**Failure (any required target failed):**
+
+```
+🔴 NOT VERIFIED: <target> ✗ — <one-line reason>
+```
+
+**Skipped (environment constraint, not a pass):**
+
+```
+🟠 <target> skipped per environment constraint (reason: ...)
+```
+
+A skipped target MUST be surfaced — never dressed up as "tests pass".
+
+## PR description results table
+
+Before opening/updating the PR at CHORE(close), the PR/MR description carries a
+✅/❌ results table covering the skill chain (`/orly-write-unit-test` ·
+`/orly-write-integration-test` or its recorded N/A · `/review`) and the verification
+lanes above — **all ✅ (or an explicit recorded N/A/skip) required**. A lane
+missing from the table counts as ❌.
+
+## Emoji legend
+
+| Glyph | Meaning |
+|---|---|
+| ✅ | Verified — all required targets passed |
+| 🔴 | Verification failed — at least one target failed |
+| 🟠 | Skipped per environment constraint — read the reason |
+| 🧪 | Lint / unit / integration test |
+| 🧩 | Integration test (cross-process) |
+| 🎯 | Cross-compile target |
+| 🔆 | Informational note (does not affect verdict) |