@agentsfleet/orly 0.10.14 → 0.12.0

package/docs/LOGGING_STANDARD.md

@@ -9,7 +9,7 @@ Pre-design rules, decisive defaults, and the anti-patterns each rule exists to p
 Triggers on every `Edit`/`Write` that adds, removes, or changes a log emit:
 
 - `*.zig` outside `vendor/`/`third_party/`/`.zig-cache/` — `std.log.*`, `std.debug.print`, `std.io.getStdErr().writer().print`, any helper in `src/lib/logging/`.
-- `*.rs` under `rustd/` outside test and benchmark scopes — `tracing::{error,warn,info,debug,trace}!`, `println!`, `eprintln!`, and `dbg!`.
+- Runtime `*.rs` outside test and benchmark scopes — `tracing::{error,warn,info,debug,trace}!`, `println!`, `eprintln!`, and `dbg!`.
 - `*.ts`/`*.tsx`/`*.js`/`*.jsx` outside `vendor/`/`node_modules/` — `console.*`, custom logger calls.
 - `*.sh` outside generated directories — `echo`, `printf` to `&2`.
 
@@ -19,8 +19,10 @@ Out of scope (explicitly):
 - Build/release scripts — the harness's own `audits/*`, `audits/release-*`, and any governance-repo tooling — toolchain output, not application logs.
 - Generated framework noise (Next.js startup banners, Bun runtime warnings) — out of our control.
 
-The **LOGGING GATE** (`dispatch/write_any.md`, Logging Gate) sits on top of this file — it fires in addition to the language-level rules in `dispatch/write_zig.md` and `dispatch/write_ts_adhere_bun.md`, not instead of them.
+The LOGGING GATE in `dispatch/write_any.md` applies alongside the repository's
+selected language rules.
 
+<!-- oracle-packs:start product.agentsfleet -->
 ## §2 · Today's de-facto standard (survey-derived)
 
 Documented honestly, not aspirationally. Pre-M62 baseline (the fix-pass converges every existing emit toward §3 onward):
@@ -39,6 +41,7 @@ Documented honestly, not aspirationally. Pre-M62 baseline (the fix-pass converge
 - No collector-friendly format. Logs are a mix of free-form English and ad-hoc `key={value}` fragments.
 
 The proposed standard below is what every new emit must conform to and what the fix-pass converges existing emits toward.
+<!-- oracle-packs:end -->
 
 ## §3 · Wire format — logfmt
 
@@ -168,12 +171,16 @@ Log the source (`source=env:OPENAI_API_KEY`), never the value, at every level.
 
 > [DETERMINISTIC → LOG]
 
-Every `err` and `warn` record that maps to a domain error MUST carry `error_code=UZ-XXX-NNN` where `UZ-XXX-NNN` is declared in `rustd/crates/afd_core/src/error_code.rs`.
+Every `err` or `warn` record for a domain error carries its code from the
+repository's declared error registry. Validate new references through its
+configured checker; installing this pack does not select a code prefix.
 
+<!-- oracle-packs:start product.agentsfleet -->
 - **Used-but-undeclared** (`UZ-FAKE-999` appearing in code, no entry in registry): **blocking** in `make lint`.
 - **Declared-but-unreferenced** (registry has `UZ-LEGACY-007`, no code references it): **informational**. Deletion may be deferred to a sweep milestone.
 
 Embed the code as a struct field on the logger call: `log.err("event_name", .{ .error_code = error_codes.ERR_X, .err = @errorName(err) })`. The encoding helpers in `src/lib/logging/mod.zig` serialize it as `error_code=UZ-XXX-NNN` per §3. CLI (`agentsfleet`) renders the code in human format and as `code: "UZ-XXX-NNN"` in `--json` output (see §8).
+<!-- oracle-packs:end -->
 
 System-level failures with no domain meaning (e.g. raw `EACCES` from a syscall before we attribute it to a tenant operation) emit without `error_code`. The follow-up rule: if a syscall failure surfaces to a user, it gets attributed to a registry code at the boundary.
 
@@ -181,20 +188,30 @@ System-level failures with no domain meaning (e.g. raw `EACCES` from a syscall b
 
 > [UNENFORCED → broad principle; no scan covers every log call site in the codebase for credential-shaped values]
 
-Inherits the redaction list from M42_002 (`src/runner/engine/runner_progress.zig`). Same secret values must not appear anywhere in log records.
+Secrets must not appear in log records at any level. Read the repository's
+redactor and verify coverage of every stream used by the changed operation.
 
 > [JUDGMENT → REDACT]
 
 - **Allocator outputs** (Postgres connection strings, Redis URLs, OAuth tokens, OpenAI keys) — never log. If a record needs to identify a config source, log the *source* (`source=env:OPENAI_API_KEY`), not the *value*.
-- **Tenant-supplied secrets** (workspace API keys, BYOK credentials) — redaction harness covers stdout/stderr from executor children. Log emit sites in this codebase MUST NOT bypass the harness.
-- **Stderr coverage gap** — today's redactor covers child stdout only. Closing this gap (extending to stderr) is part of M62_001's fix-pass, not a separate milestone.
+- **Tenant-supplied secrets** — log emit sites must preserve the repository's
+  redaction boundary. Check both stdout and stderr; never assume a stream is
+  covered merely because another product's harness covers it.
 
 > [JUDGMENT → MSG-REVIEW]
 
-- **`msg=` fields** — values copy-pasted into `msg=` are the most common leak source. Audit script flags long `msg=` values; reviewer must verify they don't carry credentials.
+- **`msg=` fields** — reviewers inspect copied values for credentials and test
+  renderer bounds. The source leaf does not detect long messages.
 
 When in doubt, omit. A missing field is recoverable; a leaked secret is not.
 
+## Repository logger binding
+
+Use the consuming repository's structured logger and error registry.
+Read its exports and test actual rendered records for the fields, bounds and
+escaping above; installing a pack does not create a logging module.
+
+<!-- oracle-packs:start product.agentsfleet -->
 ## §7 · Per-language binding — Zig
 
 The wire format above is produced by helpers in `src/lib/logging/mod.zig`, exposed as the named module `log` so any layer-isolated tree (auth/, executor/) can import it without violating layer rules. Call sites use:
@@ -279,11 +296,11 @@ Schema mirrors Bun's `SystemError` extern struct (`bun:src/bun.js/bindings/Syste
 
 > [DETERMINISTIC → LOG]
 
-**Logging emit sites** in `cli/src/**` use a thin Bun-runtime logger that produces logfmt records to `stderr`. `console.log` / `console.error` are forbidden in source per `dispatch/write_ts_adhere_bun.md` §10 — `logging.sh` enforces this for TS/JS.
+**Logging emit sites** in `cli/src/**` use a thin Bun-runtime logger that produces logfmt records to `stderr`. `console.log` / `console.error` are forbidden in source per `dispatch/write_ts_adhere_bun.md` §10 — `logging.sh` enforces this for TS/JS. <!-- oracle-packs:language.typescript,language.javascript -->
 
 > [JUDGMENT → TS-STYLE]
 
-**Module-level error style** is governed by `dispatch/write_ts_adhere_bun.md` §9 (one style per module — throw OR Result, never both). The error type itself is the same:
+**Module-level error style** is governed by the selected language's error discipline. The error type itself is the same:
 
 ```ts
 class AgentError extends Error {
@@ -295,6 +312,7 @@ class AgentError extends Error {
 
 Throw-style modules `throw new AgentError({...})`. Result-style modules return `{ ok: false, error: new AgentError({...}) }`. Render path picks human or JSON based on the runtime mode.
 
+<!-- oracle-packs:end -->
 ## §8A · Per-language binding — Rust
 
 > [DETERMINISTIC → LOG]
@@ -390,16 +408,18 @@ Failure modes the audit script and reviewer must close. These are **not aspirati
 | # | Rationalization | Closure |
 |---|---|---|
 | L1 | "Temporary debug print, I'll remove later" | `logging.sh` rejects `std.debug.print`, Rust `println!` / `eprintln!` / `dbg!`, and `console.log` / `console.debug` / `console.info` in runtime source. Direct Zig or Rust stream output needs `// logging: <reason>` on or immediately above the emit. The reason must be non-empty and explain why the stream is the program interface. |
-| L2 | "`std.log.scoped` is fine, `obs.scoped` is just a wrapper" | `std.log.scoped` is **forbidden** in `src/**/*.zig` outside `src/lib/logging/`. Only `obs.scoped` is callable. Audit flags every `std.log.` call site. |
+| L2 | "The standard logger already has a scope" | Use the repository's structured logger and prove the §3 record shape. For `agentsfleet`, this is the named `log` module's `logging.scoped`, as §7 specifies. The leaf does not enforce logger imports or reject every `std.log` call; the reviewer checks this binding. |
 | L3 | "I added `error_code=UZ-NEW-001` — registry entry coming next commit" | The registry entry **must land in the same commit** as the first reference. `error-codes.sh` runs against the staged diff; missing entry = blocking. |
 | L4 | "This per-iteration event matters for debugging — `info`-level" | Per-iteration and per-row paths are `debug`, including mandatory boundary pairs on hot polls. `debug` is the level with a volume switch. This closes the ONLY `info` prohibition — there is no allow-list of event names and none may be reintroduced (§4). The inverse rationalization is closed too: "this operation is obviously fine, no need to log it" does not survive §4 rule 1, which requires a `_started`/`_completed`\|`_failed` pair on every boundary-crossing operation. Reviewer checks the pair and the loop, never the spelling. |
-| L5 | "Operator needs the full stack trace in `msg=`" | `msg=` capped at 300 chars; total fields per record capped at 15. Stack traces emit as a separate `event=stack_trace` record at `debug` level, correlated by `correlation_id`, not stuffed into `msg`. |
-| L6 | "Embedded newlines because I copy-pasted output" | Audit greps for raw newline byte inside quoted logfmt values. Must be `\n` literal (two chars). |
+| L5 | "Operator needs the full stack trace in `msg=`" | `msg=` stays capped at 300 characters and each record at 15 fields. Emit correlated stack traces separately at `debug`. These are renderer and reviewer checks; the leaf emits no message-size or field-count verdict. |
+| L6 | "Embedded newlines because I copy-pasted output" | Encode newline characters as `\n` within values. Verify the actual rendered record in tests and review; the leaf cannot inspect runtime output. |
 | L7 | "Auto-mode is on, the gate block is ceremony" | **Auto-mode does NOT cover gate skips.** Skip without an explicit user-given override = automatic violation. No size threshold lets an edit bypass the gate. |
 | L8 | "I read this doc at session start; subsequent edits don't need re-print" | Gate fires **per-edit**. The printed `🔴 LOGGING GATE` block is required before every triggered Edit/Write, not once per session. |
 | L9 | "Fix-pass touches every line; printing per-line is noise" | Fix-pass produces **one combined gate block per file**, not per-line. The block lists all violations addressed in that file. Still required, just consolidated. |
 
-These are enforced by `logging.sh` (mechanical) and the dispatch façade (`dispatch/write_any.md`, Logging Gate — output discipline). When in conflict, the façade wins — it is the enforcement layer.
+The leaf checks source emit forms; reviewers and renderer tests check the
+record shape, logger binding, bounds and escaping named above.
+The dispatch façade requires both kinds of evidence.
 
 ## §11 · Anti-patterns (named, banned)
 
@@ -410,7 +430,7 @@ These are enforced by `logging.sh` (mechanical) and the dispatch façade (`dispa
 | Rust `println!`, `eprintln!`, or `dbg!` outside tests | No level, event, or structured fields — dev diagnostics that escaped to main. |
 | Rust `tracing` emit without `event` | Drops the stable event key required by §3. |
 | Positional formatting in a Rust `tracing` emit | Values become opaque message text instead of queryable fields. |
-| `console.log` in `agentsfleet` source | Bypasses logger, breaks `--json` mode, violates `dispatch/write_ts_adhere_bun.md` §10. |
+| `console.log` in `agentsfleet` source | Bypasses logger, breaks `--json` mode, violates the selected language's error discipline. |
 | Logging on hot per-iteration paths at `info` | Floods collectors. Use `debug` (gated off by default). |
 | `error_code=` missing on `err`/`warn` mapping to registry codes | Breaks traceability; future operator can't link log to docs. |
 | Logging credentials, tokens, or BYOK keys | Severe leak surface. Redaction harness mandatory. |
@@ -430,10 +450,10 @@ immediately preceding the edit. Generic "scope creep" is not a valid reason —
 
 ## §13 · Family
 
-- `dispatch/write_ts_adhere_bun.md` §10 — banned `console.log` in TS/JS source. Cross-referenced by `logging.sh`.
-- `dispatch/write_ts_adhere_bun.md` §9 — module-level error style (throw vs Result) for `agentsfleet`.
-- `dispatch/write_zig.md` — Zig discipline umbrella; this doc's §7 is the logging-specific layer.
-- `dispatch/write_rust.md` — Rust discipline umbrella; this doc's §8A is the logging-specific layer.
+- `dispatch/write_ts_adhere_bun.md` §10 — banned `console.log` in runtime source. <!-- oracle-packs:language.typescript,language.javascript -->
+- `dispatch/write_ts_adhere_bun.md` §9 — module-level error style. <!-- oracle-packs:language.typescript,language.javascript -->
+- `dispatch/write_zig.md` — Zig authoring discipline. <!-- oracle-packs:language.zig -->
+- `dispatch/write_rust.md` — Rust authoring discipline. <!-- oracle-packs:language.rust -->
 - `LIFECYCLE_PATTERNS.md` — orthogonal: ownership/cleanup of structs, including allocator wiring for the thread-local log buffer.
 - M42_002 redaction harness (`src/runner/engine/runner_progress.zig`) — secret-redaction precondition; this doc's §6 inherits.
 - Universal rules (RULE UFS, RULE TGU, RULE PRI, RULE FLL, RULE ORP, RULE TST-NAM) live in `docs/greptile-learnings/RULES.md`.
@@ -455,7 +475,7 @@ its line covers the clauses under it until the next heading.
 | `[JUDGMENT → BOUNDARY]` | is this operation boundary-crossing, and is its `_started`/`_completed`\|`_failed` pair complete | the agent at write time; the reviewer at `/review` |
 | `[JUDGMENT → REDACT]` | is this value a secret, or the label of one | the agent at write time; the M42_002 harness covers only executor-child output |
 | `[JUDGMENT → MSG-REVIEW]` | does this `msg=` carry a credential | the reviewer; no length or content check runs today |
-| `[JUDGMENT → TS-STYLE]` | throw-style or Result-style for this module | `dispatch/write_ts_adhere_bun.md` §9, agent-decided |
+| `[JUDGMENT → TS-STYLE]` | throw-style or Result-style for this module | the selected language façade, reviewer-decided |
 | `[JUDGMENT → RUST-STYLE]` | does a Rust failure map to a registry code, and are field expressions safely hoisted | the agent at write time; the reviewer at `/review` |
 | `[JUDGMENT → EVENT-COMPAT]` | does a language port preserve the event bytes consumed by existing dashboards | the agent compares old and new event constants; the reviewer confirms intentional renames |
 | `[JUDGMENT → SECTION-SCAN]` | which sections of this file the current sub-task needs | the agent; `audits/doc-read.sh` records façade reads, not delegated-doc reads |

package/docs/ORLY_ARCHITECTURE.md

@@ -31,7 +31,7 @@ unaffected by anything below.
 Every other repository gets its rules a different way: `orly init` materialises
 the packs its own sources select — rendered `AGENTS.md`, the rule docs, the gate
 scripts, the hooks that run them — into that repository, and writes
-`.oracle/orly.json` recording the engine version and every file it wrote,
+`.orly/orly.json` recording the engine version and every file it wrote,
 alongside the repository's own packs, commands, and surfaces. `orly update` re-materialises against the currently installed engine
 version; `orly doctor` reports drift between the lock and disk instead of
 silently tolerating it. A materialised repository needs no checkout of this
@@ -55,7 +55,7 @@ restores storage, but not the failure mode that got it removed: `orly update`
 turns a rule change into one command per repository instead of the manual
 sync M01 rejected, and the lock makes staleness a reported condition —
 `orly doctor` — instead of a silent one. cache-kit.rs is the evidence for both
-failure modes in the same repository: its `.oracle/` snapshot from the
+failure modes in the same repository: its `.orly/` snapshot from the
 pre-thin model sat frozen for four weeks with no update path, and its
 generated `AGENTS.md` told a Rust crate its project name was `agentsfleet` —
 a persona/product leak M03 also closes, by fencing both behind opt-in packs a
@@ -90,8 +90,11 @@ Four behaviours worth knowing:
   with a printed reason, so an ad-hoc bug fix meets the quality gates without
   being told to write a spec. A spec moved to `done/` on the branch is still
   discovered through its `Branch:` header and gates the PR — CHORE(close)
-  never skip-passes the criteria it exists to satisfy. Two active specs is an
-  error — one stream per worktree.
+  never skip-passes the criteria it exists to satisfy. Headers accept a plain
+  token or an inline-code token. Active specs explicitly owned by other branches
+  do not displace this branch's spec; active specs without a branch remain gated.
+  Multiple specs may fold into one owner through `Folded-into`; two independent
+  owners on the current branch remain an error.
 - **A worktree is its repository.** `repositories.json` registers primary
   checkouts only; a linked worktree resolves through the set of checkouts git
   reports for the shared object store. Streams stay ephemeral and unregistered,
@@ -113,13 +116,15 @@ malformed trailer is not an override; the gate stays red.
 
 ## Profiles
 
-`.oracle/orly.json` names any opt-in packs, the command surface, and optionally the diff
+`.orly/orly.json` names any opt-in packs, the command surface, and optionally the diff
 surfaces:
 
 ```json
 {
+  "schema_version": 1,
   "commands": { "conform": [["make", "harness-verify"]],
                 "verify.unit": [["make", "test-unit-all"]] },
+  "limits": { "verify.unit": { "timeout_ms": 1800000, "output_bytes": 67108864 } },
   "surfaces": { "user": ["src/http/", "cli/src/"],
                 "docs": ["docs/"] }
 }
@@ -132,6 +137,14 @@ checks without declaring application test suites. `init` reports missing
 commands; `doctor` rejects incomplete setup without running those commands.
 The final tree check includes the spec, so its evidence must be committed.
 
+`schemas/profile.schema.json` describes the repository file, including ownership records and disabled execution settings.
+Both configuration readers refuse unknown settings, malformed types and unsupported execution modes before selecting commands.
+Each invocation defaults to 30 minutes and 64 mebibytes of combined output; `limits` supplies per-command overrides.
+
+The synchronous gate calls a Bun supervisor that reads both streams and stops the owned process group on either limit.
+Limited commands return a failure with measured duration, byte count and a private receipt directory containing all captured bytes.
+Normal commands remove their temporary files after the gate reads the complete output; limit receipts remain until the caller removes them.
+
 ## Usage telemetry
 
 Orly keeps usage telemetry off until a person enables anonymous collection in
@@ -154,5 +167,63 @@ the Fleet is an analysis consumer and never the public ingestion boundary.
 ## Evidence
 
 `orly verify --all --write-evidence` records the source commit and every check
-into `.oracle/evidence.json` (git-ignored). Pre-push writes it when the pushed
+into `.orly/evidence.json` (git-ignored). Pre-push writes it when the pushed
 range touches governance paths.
+
+## TypeScript judgment experiment
+
+The 0.11.0 experiment keeps the Bun command line and installed `.orly/`
+layout. `orly judge` accompanies the deterministic gates with explicit advice.
+Indy canceled the native rewrite and its Milestone 07 plans on Oct 04, 2026.
+
+### Timing and authority
+
+| Stage | Input | Bounded decision | Follow-up |
+|---|---|---|---|
+| PLAN | One spec requirement and its selected section | Are prerequisites explicit? Is the result observable? | Clarify setup or expected results before implementation |
+| VERIFY | Required behavior, complete implementation and linked test | Does the assertion discriminate correct behavior from the supplied incorrect behavior? | Add an exact assertion before accepting test evidence |
+| REVIEW | One failure path or one rule with selected code | Is the failure handled? Does this rule apply? | Inspect the named path or rule before disposing of the finding |
+| DOCUMENT | One claim and selected implementation or measured output | Does supplied evidence support this claim? | Narrow the claim or gather the missing proof |
+| Commit, push and PR | Existing deterministic facts and command results | Existing checks only | Model advice cannot change gate outcomes |
+
+Questions and possible next actions live in a fixed catalog. Noul supplies a
+probability for one property. Choice selects an assertion category. There is
+no overall quality score, model-written command or automatic owner decision.
+The agent invokes advice explicitly. Skill instructions explain optional timing;
+hooks never upload source and never request a model answer.
+
+### Evidence and upload
+
+A stage-specific manifest names the required behavior and role-labeled source
+references. Each reference selects a complete file, TypeScript function, named
+test, or Markdown section. Missing, ambiguous, escaping and oversized inputs
+are refused before inference. Evidence remains data even when it contains
+instructions. Necessary unchanged context must be named by the manifest.
+
+The shipped command uses the official TypeSafe System One API and pins
+`jev-1.13.0`. Only `--refresh` permits a live request. The provider key comes
+from `TYPESAFE_API_KEY` at runtime. A passing secret scan is required for the
+entire selected state before any request. Source and credentials stay out of
+reports and error messages. Limits cover source, state, request and response
+bytes, item count, subprocess duration, fetch and body-reading duration.
+Requests are sequential and receive no automatic retries.
+
+Evidence selection uses Babel's JavaScript parser in a bounded Bun worker.
+The installed command runs TypeScript source through Bun, with the same `bunx`
+installation as 0.10.x. TypeScript 7 supplies development checks. The shipped
+runtime has no native compiler dependency or compiler installation step.
+
+### Replay and proof
+
+Default mode reads a local exact-input replay. Identity binds project root,
+model, catalog definitions, requirements, selectors and selected source bytes.
+A changed input or invalid record is incomplete. Replay files include typed
+answers and integrity metadata, without source text. Local replay is editable
+by the repository owner and is advisory evidence, never approval or a gate.
+
+A consumer experiment uses a new `agentsfleet` worktree and the locally packed,
+unpublished 0.11.0 package. The controls compare the same incorrect locale code
+with a weak assertion and an exact assertion, plus healthy exact behavior.
+Repeated live observations report successes, misses, uncertainty, latency and
+token usage. The trial proves bounded usefulness only; broader accuracy and
+runtime superiority require different evidence.

package/docs/RELEASE_TEMPLATE.md

@@ -1,6 +1,20 @@
-# Release doc template — `changelog.mdx` `<Update>` block
+# Release documentation template
 
-Source of truth: `~/Projects/docs/changelog.mdx`. New `<Update>` blocks go at the top, after the leading `<Tip>`/`<Note>`. Labels are date-only — never a semver prefix. `VERSION` is the single source of truth for binary version (binaries via `make sync-version` propagate to `build.zig.zon`, `agentsfleet/package.json`, `agentsfleet/src/cli.js`); changelog stays chronological. Decoupled by design — avoids parallel-branch collisions.
+Use the consuming repository's declared changelog and version source.
+Preserve its selected format; a Markdown changelog does not acquire a Mintlify
+site, sibling checkout or `VERSION` file by installing this pack.
+Use its declared synchronization command when it maintains generated versions.
+
+<!-- oracle-packs:start product.agentsfleet -->
+For `agentsfleet`, the changelog is `~/Projects/docs/changelog.mdx` and `VERSION`
+is the binary version source. `make sync-version` updates `build.zig.zon`,
+`agentsfleet/package.json` and `agentsfleet/src/cli.js`.
+New `<Update>` blocks go after the leading `<Tip>` or `<Note>`.
+<!-- oracle-packs:end -->
+
+For a repository already using Mintlify, use the block and label rules below.
+Other formats carry the same applicable upgrading, behavior and API information
+in their existing entry structure.
 
 ## Block template
 
@@ -23,7 +37,7 @@ Source of truth: `~/Projects/docs/changelog.mdx`. New `<Update>` blocks go at th
   {User-visible bugs fixed — observed behavior before/after. Omit if none.}
 
   ## CLI
-  {`agentsfleet` additions or shape changes. Omit if none.}
+  {Command additions or shape changes. Omit if none.}
 </Update>
 ```
 
@@ -36,11 +50,13 @@ Source of truth: `~/Projects/docs/changelog.mdx`. New `<Update>` blocks go at th
 - Every breaking change appears under `Upgrading` with a migration step, even if also mentioned elsewhere.
 - Body copy may reference a past entry by date (`"…that shipped on Apr 22, 2026"`); do not reference past releases by semver (`"shipped in v0.27.0"`) — that drags the two timelines back together.
 
-## Version bumps (`VERSION`, not the changelog label)
+## Version bumps (the repository's version source)
 
 - Feature milestone → minor (`0.7.0` → `0.8.0`).
 - Bug fix → patch.
 - Pre-v1.0 breaking → minor (semver 0.x carve-out); call out under Upgrading.
 - Post-v1.0 breaking → major.
 - Internal-only refactor: terse `<Update>` with `tags={["Internal", ...]}`, one-paragraph summary, skip section structure. Prefer folding into the next user-visible release.
-- Parallel branches bumping `VERSION` do not coordinate through the changelog — whichever lands second rebases `VERSION` and re-runs `make sync-version`.
+- Parallel branches reconcile their version source against the current default
+  branch and run the repository's declared synchronization check. This never
+  authorizes rebasing or force-pushing a published branch.

package/docs/REST_API_DESIGN_GUIDELINES.md

@@ -1,4 +1,4 @@
-# REST API Design Guidelines — `agentsfleet/agentsfleetd`
+# REST API Design Guidelines
 
 **Status:** Canonical instruction set. Read this before adding, modifying, or removing any HTTP endpoint.
 **Trigger:** the global instruction `HTTP handler or OpenAPI changes → read docs/REST_API_DESIGN_GUIDELINES.md first` fires when the diff touches a handler, `public/openapi.json`, or any `route_*` file. If you're an agent reading this — you got here because that trigger fired. Follow this doc as a checklist, not as background reading.
@@ -9,10 +9,11 @@ This is a goal-oriented instruction set. Each rule states the goal it serves so
 
 ## Audience — who this binds
 
-This doc binds **whoever ships the change** — Kishore directly, OR an agent acting on Kishore's behalf in auto mode under a start-instruction (per `~/.claude/CLAUDE.md` autonomy rules). Concretely:
+This guide binds the author and reviewer in the consuming repository.
+Publishing and merge authorization come from that repository's operating model.
 
 - **The agent** runs the Quick checklist below as part of `CHORE(close)` and the §10 pre-PR gate, opens the PR via `gh pr create`, and answers `orly-babysit-prs` review feedback. The agent is the primary enforcer.
-- **Kishore** opens the PR directly when working without an agent. Same checklist applies.
+- **The human author** follows the same checklist when working without an agent.
 - **A reviewer** (human or `/review`) checks the PR against this doc adversarially. A red box on the checklist that's not justified in the PR description is grounds to block merge.
 
 When this doc says "you" it means the agent or the human author — same rules either way. When it says "MUST" it means a missing or wrong implementation blocks merge; "SHOULD" means deviate only with a one-line rationale in the PR description.
@@ -21,14 +22,16 @@ When this doc says "you" it means the agent or the human author — same rules e
 
 ## Quick checklist — adding an endpoint
 
-Run this checklist as part of `CHORE(close)` (per `~/.claude/CLAUDE.md` lifecycle), before `gh pr create`. Every box must be checked, OR the PR description must call out the deviation with a reason. An unchecked box that the description ignores blocks merge.
+Run this checklist at the repository's review boundary before creating a Pull
+Request (PR). Every applicable item needs evidence or an owner-approved
+exception; an unchecked item cannot silently become a pass.
 
 - [ ] **URL design** — plural noun resource, hierarchical path, no verbs (§1); operation-style `:verb` declared as one of the three allowed categories (§1)
 - [ ] **Path params + trailing slash** — `{resource_id}` matches body field name; no trailing slash (§1)
 - [ ] **HTTP method** chosen by semantics; PATCH idempotency guarantee stated; `Idempotency-Key` honored if applicable (§2)
 - [ ] **Long-running ops** use the canonical `202 + /v1/operations/{id}` shape (§2)
 - [ ] **Request body shape** matches the path (no path-param IDs in body) (§3)
-- [ ] **Pagination** uses Stripe-style `?starting_after=&limit=` with `next_cursor` response field; default 50, max 100 (§3)
+- [ ] **Pagination** uses keyset cursors with shared, declared default and maximum bounds (§3)
 - [ ] **List envelope** is exactly `{items, total: int|null, next_cursor: string|null}` — no synonyms (§3)
 - [ ] **Bulk endpoints** use `207` with the canonical per-item shape (§3)
 - [ ] **Null vs omit** — absent optionals omitted, `null` reserved for "explicitly cleared" (§3)
@@ -37,10 +40,10 @@ Run this checklist as part of `CHORE(close)` (per `~/.claude/CLAUDE.md` lifecycl
 - [ ] **Status codes** — 409 includes `current_state`; 412 includes `etag`; 429 includes `Retry-After` + `X-RateLimit-*` (§4)
 - [ ] **ETag/`If-Match`** wired for any resource with realistic concurrent edits (§4)
 - [ ] **Error responses** use the registry; `detail` follows hygiene rules (no IDs, no SQL, no paths, ≤200 chars) (§5)
-- [ ] **OpenAPI document** regenerated from the build, not hand-edited; the coverage gate is green (§6)
-- [ ] **Route registered** in all six places (§7)
-- [ ] **Handler signature** takes only the extractors it reads and returns `Result<Response, Refusal>` (§8)
-- [ ] **Middleware policy** picked from the table; raw handlers carry first-10-lines comment (§7)
+- [ ] **OpenAPI document** matches the repository's canonical source and declared generation or validation checks (§6)
+- [ ] **Route registered** in the repository's actual router and discovery graph (§7)
+- [ ] **Handler signature** follows its framework and uses the inputs it reads (§8)
+- [ ] **Authentication and ownership** are proved on the served route before data access (§7–§8)
 - [ ] **Versioning** — added/renamed/removed surface listed in PR description; deprecation uses `Deprecation` + `Sunset` headers; new response fields declare `x-stability` (§9)
 - [ ] **Tests** — happy path + one error per refusal + idempotency double-PATCH + `Idempotency-Key` replay (where applicable) + ETag mismatch (§10)
 - [ ] **Logging** — sensitive ID values are DEBUG-only or carry `// log-id-allowed:` comment; secret-shaped fields are write-only or one-time-read (§11)
@@ -215,7 +218,15 @@ GET /products?status=active&sort=-created_at&starting_after=01HZQ...&limit=50
   - **Time ranges:** `?created_after=<ts_ms>&created_before=<ts_ms>`. Bracket grammar (`?created_at[gte]=...`) is forbidden.
   - **No boolean explosions.** Don't add `?include_x=true&include_y=true` — use `?include=x,y` with a documented enum of legal values, OR don't expose a knob.
 - **Sorting:** `sort=field` ascending; `sort=-field` descending. Single sort key per request — no multi-key.
-- **Pagination — Stripe-style keyset only.** Request: `?starting_after=<resource_id>&limit=<int>`. Response: `next_cursor: <resource_id> | null` (the field is named `next_cursor` even though the request param is `starting_after`). Cursor encode/decode goes through `afd_core::paging::cursor`, and both the parameter name and the bounds are constants there: `QUERY_STARTING_AFTER`, `DEFAULT_LIMIT` (50) and `MAX_LIMIT` (100). Read the limit through that module rather than parsing the query string in a handler. To page forward, send the response's `next_cursor` value back as the next request's `starting_after`. **Forbidden:** page-based `?page=&page_size=`, and custom request-side `?cursor=` names. Both spellings predate this rule where they survive; do not copy either into a new endpoint.
+- **Pagination — keyset.** Request: `?starting_after=<resource_id>&limit=<int>`;
+  response: `next_cursor: <resource_id> | null`. Send `next_cursor` back as the
+  next request's `starting_after`; use shared repository parsing and constants
+  for the default and maximum, with bounds tested at the served endpoint.
+<!-- oracle-packs:start product.agentsfleet -->
+- For `agentsfleet`, use `afd_core::paging::cursor`, `Page::parse` and its route
+  `Ceiling`, or `afd_validate::Limit::parse`. `DEFAULT_LIMIT` is 50 and
+  `MAX_LIMIT` is 100; an empty limit uses the route default.
+<!-- oracle-packs:end -->
 - **Sparse fieldsets / `?include=` / `?fields=`:** not supported in v1. If you need to slim a payload, design a smaller endpoint. Don't invent.
 
 ### Bulk operations
@@ -242,7 +253,9 @@ This rule is binding on responses AND requests. SDK consumers branch on `field =
 
 ### IDs
 
-- Use **UUIDv7** for all externally-exposed IDs (sortable, time-encoded). See [uuid7.com](https://uuid7.com).
+- Preserve the repository's documented public identifier format and test its
+  parsing at the endpoint boundary. Do not substitute another product's format.
+- `agentsfleet` uses Universally Unique Identifier version 7 (UUIDv7) for public identifiers. <!-- oracle-packs:product.agentsfleet -->
 - Do not expose database serial integers.
 - Sensitive IDs (workspace_id, agent_id) live in the path, not the body. Never log their values at INFO level (§11).
 
@@ -252,6 +265,11 @@ This rule is binding on responses AND requests. SDK consumers branch on `field =
 
 ### Success — return the wire type
 
+Return the repository's typed response through its framework's response
+renderer. Share the public response shape with its schema source so field names,
+status and content type stay consistent.
+
+<!-- oracle-packs:start product.agentsfleet -->
 ```rust
 Ok(Json(FleetDetailResponse::from(&detail)).into_response())
 Ok((StatusCode::CREATED, Json(CreatedResponse { id, key })).into_response())
@@ -262,6 +280,7 @@ The wire type owns the field names and `IntoResponse` writes the status and
 content-type. A response shape belongs in `afd_wire`, not spelled inline in a
 handler, so the same struct is what the OpenAPI document is generated from.
 Build a response by hand only for a Server-Sent Events stream.
+<!-- oracle-packs:end -->
 
 ### Status codes
 
@@ -323,13 +342,20 @@ For any resource where concurrent edits are realistic (anything mutable that two
 
 ### Use the error registry
 
-The error-code registry (`rustd/crates/afd_core/src/error_code.rs` and the family modules beside it) owns the HTTP status, RFC 7807 `title`, and `docs_uri`. Your handler supplies only the code and a human-readable `detail`:
+Use the repository's error registry and renderer for status, title and public
+documentation links. Handlers supply the code and a safe human-readable detail;
+they do not duplicate the registry's response shape.
+
+<!-- oracle-packs:start product.agentsfleet -->
+The `agentsfleet` registry is `rustd/crates/afd_core/src/error_code.rs` and its
+family modules. Its handlers use these refusal constructors:
 
 ```rust
 Refusal::malformed(DETAIL_WORKSPACE_ID)          // the sentence is a constant
 Refusal::coded(FLEET_NOT_FOUND, DETAIL_NOT_FOUND)
 Refusal::preconditioned(error.code(), error.detail(), current)
 ```
+<!-- oracle-packs:end -->
 
 Never assemble a `Problem` by hand and never write a status and body directly:
 the status, title and documentation link come from the registry entry, and a
@@ -371,16 +397,20 @@ The title must be safe to render verbatim in a UI toast — think "what would I
    - State: `"<noun> already exists"` / `"<noun> not found"` / `"<noun> expired"` — `Agent name already exists`, `token expired`.
    - Format help: `"<param>: use <format>"` — `invalid_since_format: use Go-style duration (15s, 30m, 2h, 7d) or RFC 3339 (YYYY-MM-DDTHH:MM:SSZ)`.
 
-When you write a new refusal, find the closest existing call site under `rustd/crates/afd_api_*/src/handler/**` and copy its shape. Don't freelance.
+When writing a refusal, read the closest existing handler and the repository's
+canonical renderer before choosing the shape.
 
 ### Internal 500s — direct calls
 
-A datastore or service failure is not a sentence a handler writes. Lift it with
-`Refusal::at`, naming the operation that failed:
+A datastore or service failure uses the repository's canonical refusal renderer.
+Name the failed operation in internal diagnostics without exposing its details
+to the caller.
 
+<!-- oracle-packs:start product.agentsfleet -->
 ```rust
 services.fleet_detail(&context, fleet_id).await.map_err(Refusal::at(FLEET_READ))?
 ```
+<!-- oracle-packs:end -->
 
 The operation constant is what identifies the failure in logs and telemetry;
 the caller gets the registry's 500 and no internal detail.
@@ -410,6 +440,11 @@ Don't invent other extensions without amending this doc.
 
 ## §6 — OpenAPI editing
 
+Locate the repository's canonical OpenAPI source. Update that source and run
+its declared generation or validation command; do not assume a Rust daemon,
+generated artifact or build target from another product.
+
+<!-- oracle-packs:start product.agentsfleet -->
 **The document is generated. There is nothing to hand-edit.**
 
 `public/openapi.json` is emitted from the daemon's own handlers — the route
@@ -449,8 +484,15 @@ generated document, so a description that breaks the wording rules fails
 for maintainers rather than for API consumers belongs in a `//` comment beside
 it, which the document does not carry.
 
+<!-- oracle-packs:end -->
 ## §7 — Registering a route
 
+Register the served method and path in the repository's router and discovery
+graph. Prove authentication and resource ownership are enforced before access;
+a helper that no served route mounts is not evidence of authorization.
+
+<!-- oracle-packs:start product.agentsfleet -->
+
 **The router is built FROM the route table, not beside it.** `Route::all()` is
 walked once at startup and every template it yields is mounted, so a path
 cannot be served under a spelling the table does not carry, and it cannot be
@@ -582,8 +624,16 @@ When in doubt, mirror an existing handler:
 | Signature-proven ingress | `rustd/crates/afd_api_ingress/src/handler/webhook/receive_route.rs` |
 | A runner speaking for itself | `rustd/crates/afd_api_runner/src/handler/runner/lease.rs` |
 
+<!-- oracle-packs:end -->
 ## §8 — Handler signature rule
 
+Follow the repository's framework and read its canonical handler first.
+Use validated inputs and the shared response and error renderers.
+Enforce authentication and ownership through its canonical mechanism, with tests
+against the actual served route; do not duplicate mounted checks by habit.
+
+<!-- oracle-packs:start product.agentsfleet -->
+
 A handler is an axum handler. The router built it into a stack that has already
 admitted the request, proven the caller, checked the capability and confirmed
 ownership, so a handler receives what it needs as extractors and constructs
@@ -612,7 +662,14 @@ pub async fn my_endpoint<D: Services>(
   envelope is built for you.
 - **Bounds are declared on the request type**, with `garde`, not re-spelled per
   handler. The refusal sentence a field earns is mapped from the path `garde`
-  reports.
+  reports, through a `const` `afd_validate::Sentences` table beside the
+  handler (`PathTable<Variant>` when a crate answers with its own error
+  variant). A rule garde lacks — `finite`, `nul_free`, `ascii_digits`,
+  `charset` — comes from `afd_validate`, never a one-off check.
+- **A parser a bound protects takes `&garde::Valid<T>`.** garde runs every
+  rule on a field with no short-circuit, so a bound and a parser on one field
+  would still hand the parser oversized input; the bound goes on a struct and
+  the parser accepts only the proved value.
 - **Never authenticate inside a handler.** The guard on the route's row did it.
   Never call an ownership check by hand either; the template mounted it.
 - **Refusal sentences live beside the parser that produces them**, as
@@ -621,12 +678,15 @@ pub async fn my_endpoint<D: Services>(
 ### What NOT to do
 
 - ❌ Reading a query string directly for `limit` or `starting_after` — use
-  `afd_core::paging`.
+  `afd_core::paging`, or `afd_validate::Limit` with the route's `Ceiling`.
+- ❌ A hand-written function from a `garde::Report` to a sentence — declare a
+  `Sentences` table.
 - ❌ Building a `Problem` by hand — construct it from the declared error code so
   the status, title and documentation link come from the registry (§5).
 - ❌ A second unique spelling of a capability check inside the handler body.
 - ❌ Re-parsing a path parameter the extractor already typed.
 
+<!-- oracle-packs:end -->
 ## §9 — Versioning
 
 URI-based: `/v1/...`. All current endpoints sit under `/v1`. Bump to `/v2` only when a breaking change is unavoidable; default to additive evolution within `/v1`.
@@ -697,11 +757,10 @@ Every PR that changes the HTTP surface MUST open its description with a "Surface
 
 Before opening a PR touching any handler:
 
-- [ ] `zig build` clean
-- [ ] `zig build test` passes
+- [ ] Declared build and unit commands have observed successful results
 - [ ] the declared `verify.unit` command passes — the route-scope match and its tests cover the auth gate matrix
 - [ ] the repository's integration suite passes end to end against real datastores, where it declares one
-- [ ] Cross-compile: `zig build -Dtarget=x86_64-linux && zig build -Dtarget=aarch64-linux`
+- [ ] Applicable platform targets and test graphs match the repository's declared matrix
 - [ ] the declared `verify.lint` command passes — every language gate the repository declares
 - [ ] Handler file ≤ 350 lines; split if it grows
 - [ ] Integration test covers the happy path AND at least one error path per refusal the handler can return
@@ -729,12 +788,18 @@ Before opening a PR touching any handler:
 
 ## §12 — Performance
 
-Targets (measured in CI bench under `make bench`):
+Use the consuming repository's declared performance budgets and benchmark lane.
+Measure applicable latency percentiles, memory and query bounds under the load
+profile the endpoint is expected to serve.
+
+<!-- oracle-packs:start product.agentsfleet -->
+`agentsfleet` targets (measured by its declared benchmark lane):
 
 - p99 latency < 200 ms
 - p95 latency < 150 ms
 - Zero allocator leaks (`std.testing.allocator` integration tests pass)
 - No unbounded query loops. Pagination caps live in §3 (default `limit=50`, max `limit=100`).
+<!-- oracle-packs:end -->
 
 If your endpoint can't meet these in a normal load profile, the spec's "Performance Considerations" section MUST contain ALL of:
 

package/docs/RULE_ENFORCEMENT.md

@@ -6,15 +6,15 @@ regenerates this file and fails on any difference. To update it, run
 
 | Rule document | enforced by | judged | acknowledged | classified | trigger |
 |---|---|--:|--:|--:|---|
-| `docs/LOGGING_STANDARD.md` | `LOG` → `logging.sh` | 11 | 13 | 30/30 | mechanical |
-| `docs/REST_API_DESIGN_GUIDELINES.md` | — | 0 | 0 | 0/65 | mechanical |
-| `docs/SCHEMA_CONVENTIONS.md` | — | 0 | 0 | 0/16 | mechanical |
+| `docs/LOGGING_STANDARD.md` | `LOG` → `logging.sh` | 10 | 13 | 28/28 | mechanical |
+| `docs/REST_API_DESIGN_GUIDELINES.md` | — | 0 | 0 | 0/67 | mechanical |
+| `docs/SCHEMA_CONVENTIONS.md` | — | 0 | 0 | 0/17 | mechanical |
 | `docs/DOCUMENTATION_RULES.md` | — | 0 | 0 | 0/22 | latent |
 | `docs/LIFECYCLE_PATTERNS.md` | — | 0 | 0 | 0/22 | mechanical |
-| `docs/CHANGELOG_VOICE.md` | — | 0 | 0 | 0/4 | latent |
+| `docs/CHANGELOG_VOICE.md` | — | 0 | 0 | 0/3 | latent |
 | `docs/VERIFY_TIERS.md` | — | 0 | 0 | 0/4 | uncited |
-| `docs/greptile-learnings/RULES.md` | — | 0 | 0 | 0/114 | mechanical |
-| **corpus** | | | | **30/277** | |
+| `docs/greptile-learnings/RULES.md` | — | 0 | 0 | 0/115 | mechanical |
+| **corpus** | | | | **28/278** | |
 
 ## How to read this