Skip to content

docs(so): plan for an audit of the SO agent infrastructure - #643

Open
privatejoel wants to merge 2 commits into
mainfrom
docs/so-agent-infra-audit-plan
Open

privatejoel wants to merge 2 commits into
mainfrom
docs/so-agent-infra-audit-plan

Conversation

@privatejoel

Copy link
Copy Markdown
Collaborator

Summary

This PR adds docs/SO_AGENT_INFRA_AUDIT_PLAN.md. It is the plan for an audit, not the audit. The owner thinks that the infrastructure that SO "agent" work runs on is spread over many separate mechanisms. The audit will find out which parts to keep, merge or retire.

  • Scope (section 2). Every mechanism that SO agent work runs on, on main at 931eb143, plus an overlay for the open PRs.
  • Inventory (section 4). 49 mechanisms in five layers: the clock and its drains, the actors, the SO record path, attention and messages, and the trail. Each row has a path:line that was checked on main. The open PRs add about 10 more (section 4.6).
  • Questions (section 5). A card of 18 questions for every mechanism, plus questions for each layer.
  • Method (section 6). Read only. One base commit. Every claim has path:line. Live facts come only from SELECT queries that the owner runs (section 6.4). A verifier checks every row. The order of inspection: the clock first, then the SO record path, then the actors, then attention, then the trail.
  • Outputs (section 7). An inventory, an overlap and conflict matrix, a target unified model with 9 constraints, a migration path in small PRs, the decisions the audit hands back, and a list of defects found and not fixed.
  • Signals to test (section 8). 15 signals. Examples:
    • No code calls /api/cron/tick (H-1).
    • No automated writer passes the order gate (H-5).
    • Two designs claim work_items (H-6).
    • There are six queue shapes (H-7).
    • When a Tally push gives up, nobody is told (H-9).
    • Eight paths create an order (H-11).
  • Defects already seen (section 8.1). D-1 crosses tenants. A manual drain run by an approver in one tenant processes the rows of every tenant (agents/handle_replies.js:181, voice/process_actions.js:152). Fix it in its own PR now. Do not wait for the audit.
  • Decisions before the audit starts (section 9). AD-1 to AD-8, each with a default. The most important is AD-5: does EA-3 (feat(email): rules turn inbound mail into owned actions (EA-3) #637, work_items, migration 252) wait for the audit's target model?

This plan reuses SO_EXECUTION_COHESION.md (#611), WORK_MANAGEMENT_SCOPE.md, AGENT_READY_SO_FLOW.md, ANVIL_MCP_SO_TOOLS_DESIGN.md, OPERATOR_ACTIONS_DESIGN.md, CRONS.md, GENAI_FOR_MANUFACTURING.md, EMAIL_ACCOUNTABILITY_SCOPE.md (#634), and the body of #566.

Deploy notes

None. This PR changes docs only. It has no migration and no env change. The next free migration number stays 271.

Tests

None needed, because no code changed. Each path:line in sections 4 and 8 was checked by hand against origin/main at 931eb143. Each claim from a search subagent was checked again before it went into the plan. Two subagent claims were wrong and were corrected: the Tally retry queue does not use erp-runner.js, and a Tally give-up writes no bell row. The document has no em or en dashes and no customer, person or part names.

Not covered

🤖 Generated with Claude Code

The plan says what the audit inspects, in which order, which questions it
answers, what evidence it collects, and what it delivers. It verifies 49
mechanisms on main in five layers, lists 15 signals to test and 7 defects
already seen, and names 8 decisions the owner makes before the audit starts.
Docs only. Nothing is audited or changed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@vercel

vercel Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
anvil Ready Ready Preview Oct 28, 2026 2:34am UTC

Only orders/[id].js imports the order write gate and the approval
evaluator. The other three files name them in comments only.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

This branch was successfully deployed

1 active deployment
Preview — 4b19a693 Deployed Oct 28, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant