ai-agent-platform

Imported from dshorter/ai-agent-platform (AGENTS.md). Install upstream with npx skills add dshorter/ai-agent-platform. Copyright stays with the author.

AGENTS.md — how to find out before you change something

This file is a router, not a reference. It is deliberately thin. Nothing here is the authority on anything; every row points at the document that is. If this file and a linked document disagree, the document wins and this file is stale — fix it.

It exists because of a specific failure on 2026-08-31. A request for "spend in the Director's report" was answered by writing 445 aggregate rows into agent_decisions, a table whose every other row is a single agent invocation. Nothing was broken by it and the code worked — which is exactly the problem. A locally-efficient fix had quietly re-decided a boundary the estate had already decided on purpose. The knowledge was written down; it just wasn't reachable in the moment it was needed.

The rule this file exists to serve: when a change would cross a boundary between two components — a new writer to a shared table, a new dependency between repos, a new consumer of someone else's data — stop and read the row below before writing code. Either of us can call it: "check the map."

Shared surfaces — read the authority before you write to one

Basis matters more than the claim. spec means a document states this and the link is the authority. observed means it is true of the system today and you can verify it by looking, but it is written down nowhere — so treat it as a description, not a rule, and never read its silence as permission. An observed row that turns out to matter is a design doc waiting to be written.

Where design lives

Neighbours

• /opt/predictor_ingest is a separate repo with its own charter — "plain Python + SQLite + JSONL", no complex infra. spec: /opt/predictor_ingest/AGENTS.md §Keep it simple.
• The predictor is outside agent_decisions today. observed — that it is deliberate is an inference, not a recorded decision. See the open question below rather than treating this as settled.
• /opt/_host is the cross-project truth map and has no remote. spec: /opt/_host/redaction-gate/README.md — it holds the redaction vocabulary, and a list of employer identifiers in a public repo is the disclosure it exists to prevent.

Open questions — where drift happens

Settled boundaries are safe; open ones are where a locally-sensible change casts a vote without anyone noticing. These are open:

• Should pipelines that spend money unattended be in agent_decisions? Today they are not, on the grounds that they are not agents. ADR-011 D4 argues the test should be "calls a paid API unattended," not "is an agent" — which would pull the predictor in. Do not add a pipeline to that table without settling this first, and if it is settled, it wants one row per run with a real run_id, not backfilled aggregates. Weigh against it: the predictor's charter keeps it free of infra dependencies, and a Postgres outage should not be able to fail or truncate a run — which argues for unifying at the reporting layer instead. (That argument is reasoning from 2026-08-31, not a decision.)

• Should the visitor-facing agents be in the trace? agent-roster.html records the finding and the fix ("what's missing is an INSERT and a grant").

• What is one agent_decisions row, and what is one sequence? Measured 2026-09-06: step_number is 1 on all 1,644 rows, one workflow_sequence_id held six repetitions of the same chain, and 50% of rows carry dotted names that inflate agent_span (a COUNT(DISTINCT agent_name) over free text). Settle the unit before building the agent_decisions reader ADR-002 specifies — it addresses "a sequence". → docs/uzelhub-crew/agent-span-counts-strings-2026-09-06.md

• Which repos may the Scout mine, and which may it read? The two lists disagree and neither document says they should. SCOUT_GIT_REPOS walks five repos for git ore (ai-agent-platform, predictor_ingest, uzelhub-web, server-maintenance, _host); the roam's registered roots are three, and _host and server-maintenance are excluded on purpose because the employer vocabulary lives in _host. Measured 2026-09-06: 35 of the 2,630 jewels are anchored to repos the roam cannot open — 21 server-maintenance, 14 _host — so run_git refuses the very ref the jewel cites. Two consequences, and only the first is cosmetic: the anchor is a dead end, and source_ref is publishable text that travels to a lead's sources field, so _host@<sha> names a gated repo in publishable output. Settle which list moves before the next walk: narrow the ore to the roam's three, or register the other two and accept what that opens. Do not split the difference silently. Related: the gated-source_ref question below, which is the same leak from the other end.

• Opened 2026-09-03, all from ADR-002 — none of these is settled:

  • What is a source_ref for gated material? It must be opaque, because the reference travels outward on a lead even when the content was scrubbed. The redaction gate guards tracked prose and cannot see the Postgres path this runs through. Settle before the gated import, not after — once written, those refs are in every jewel mined from that material.
  • Does scout_coverage get a second writer? The proposed coverage ledger should be Scout-owned and Scout-written. That boundary wants stating when it is built, not inferred later. Same shape as the agent_decisions question below.
  • Is Fable worth 5× on synthesis? The cost half is settled (187× the walk per call, and rising); the quality half has never been measured, and the A/B NEWSROOM.md specifies has been open since 2026-07-26. The default moved to Sonnet 5 to invert the burden, not because the quality argument was refuted.
  • Do a cursor and free roam conflict? Closed 2026-09-06 by deletion, not by an amendment. ADR-002 argued no — a cursor is a return address, not a leash — against NEWSROOM.md §The Scout's sources, which said "scope the cursor to the logs, and nowhere else". That section was cut to a spec pointer when NEWSROOM became reasoning-only, so the contradicted claim is no longer asserted anywhere. spec-scout.md §The walk is the only statement of cursor behaviour now. The reasoning both sides shared — coverage is linear, investigation is not — survives in the pointer.

• Should redaction dismissals be path-scoped? Settled 2026-09-01, and not by scoping them. The blocked commits were never introducing the findings — the content was already in HEAD, so the gate was re-litigating published material every time a rule was added. The hook path now compares against HEAD's copy of the same file and suppresses only what is already there (9a5ce31). Dismissals stay global and rare, which keeps a dismissal the deliberate act it was designed to be; the per-file judgment lives in the baseline instead. New findings still block everywhere, new files included.

Conventions

• A document marked read: full is read whole before acting on it. Never conclude from a range-read. (Convention defined in /opt/_host/README.md.)
• Docs are never silently rewritten. Corrections carry a date and keep the original claim visible. Exception (2026-09-06): GLOSSARY.md and the four spec-*.md files are rewritable — edit in place, date the commit, no correction strata. They hold the current rule; history lives everywhere else.
• Operator-requested consolidation (2026-09-10): NEWSROOM-SPEC.md is the rewritable system specification. It replaces the four desk specs and UI spec as current requirements; retain their historical bodies. The earlier per-desk rewrite convention now applies to the consolidated spec. Date requirement changes with their decision basis; update work-plan scope and acceptance records where affected. Consolidation does not finalize NR-00.
• Operator-requested exception (2026-09-09): NEWSROOM-WORKPLAN.md is a working, updatable document. Update its current state in place; preserve scope, order, dependency and acceptance changes in its dated change record. Read it at session start, identify the active task ID, and update its evidence and next action before handing off. The verbatim critique and dated planning history are not rewritten as substitutes for maintaining this board.
• Operator/sudo work ships as a runnable script — backup, validate, self-verify, restore on failure — never as a config paste.
• Operator clarification (2026-09-10): replaced documents may be marked superseded. Name the replacement, date and scope of supersession at the top; preserve the historical body. A completed runbook is not a new-session instruction. The verbatim critique remains an unchanged historical artifact.