diff --git a/.codex/agents/implementation.toml b/.codex/agents/implementation.toml index ce5b776..3bd2c6c 100644 --- a/.codex/agents/implementation.toml +++ b/.codex/agents/implementation.toml @@ -1,12 +1,14 @@ name = "implementation" -description = "Default executor for a bounded Sauci product or harness change after scope and acceptance criteria are known." +description = "Terra executor for one continuous bounded Sauci product or harness change after scope and acceptance criteria are known." model = "gpt-5.6-terra" developer_instructions = """ Read the root and nearest scoped AGENTS.md files plus the applicable repository -skill. Implement only the delegated objective and preserve unrelated work. Update -maintained contract documentation and add focused tests when the contract changes. -Run the required focused checks and return changed files, exact results, -assumptions, and blockers. Stop for missing authority or a materially ambiguous -product choice. Do not expand scope or perform external, destructive, production, -release, or provider writes unless the task explicitly authorizes that action. +skill. Own the continuous execution unit: perform scoped discovery, +implementation, focused tests, and iteration in this handoff. Implement only the +delegated objective and preserve unrelated work. Update maintained contract +documentation and add focused tests when the contract changes. Run the required +focused checks and return changed files, exact results, assumptions, and blockers. +Stop for missing authority or a materially ambiguous product choice. Do not expand +scope or perform external, destructive, production, release, or provider writes +unless the task explicitly authorizes that action. """ diff --git a/.codex/skills/verify/SKILL.md b/.codex/skills/verify/SKILL.md index f52d3f2..ad30da9 100644 --- a/.codex/skills/verify/SKILL.md +++ b/.codex/skills/verify/SKILL.md @@ -5,25 +5,34 @@ description: Prove a completed Sauci engineering task works before a PR. Use whe # Verify Sauci work -Run locally on a non-default branch with the implementation committed. +Run locally on a non-default branch with the implementation committed. Use an +independent verifier for user-facing, cross-boundary, or high-risk runtime +changes. Documentation, mechanical configuration, isolated tests, and low-risk +package-local changes may use focused deterministic checks without a verifier. -1. Start the stack once with `scripts/dev-local.sh up`; reset fixtures first when - the task changes durable state. Web is `http://127.0.0.1:3000`, admin is - `http://127.0.0.1:3001`, and MCP health is `http://127.0.0.1:3002/health`. -2. Give a fresh read-only verifier the acceptance criteria. It drives browser +1. Package-local deterministic checks do not need a running stack. For runtime + verification, reuse a compatible running local stack when available; otherwise + start the documented full stack with `scripts/dev-local.sh up`. Reset fixtures + first when the task changes durable state. Web is `http://127.0.0.1:3000`, + admin is `http://127.0.0.1:3001`, and MCP health is + `http://127.0.0.1:3002/health`. +2. When independent runtime verification is required, give a fresh read-only + verifier the acceptance criteria. It drives browser surfaces with the repository browser capability, native surfaces with Maestro or the iOS simulator skill, and APIs with `curl`. Authentication fixtures are described by `e2e/.auth/fixtures.json` after `dev-local.sh reset`. 3. The verifier writes screenshots, traces, video, or response evidence under `evidence/` and returns only expected, observed, evidence paths, and `works|broken`. It never edits code. -4. If broken, fix and use a fresh verifier. Stop after three failed rounds and - report the unresolved evidence. -5. After the task works, run `npm run verify:fast`, affected E2E, and - `npm run verify:full` when local Supabase/Deno are available. Never weaken an - assertion just to pass. +4. If independent verification is broken, fix and use a fresh verifier. Stop + after three failed rounds and report the unresolved evidence. +5. Run focused checks for the affected change. Run affected E2E when the runtime + path requires it. Run `npm run verify:full` when its prerequisites are + available; it already runs `npm run verify:fast`, so do not run both in + sequence. Never weaken an assertion just to pass. 6. Open a PR only after both task verification and regression checks pass. Upload evidence to the established CI artifact or `pr-evidence` prerelease and embed the screenshot plus a video/trace link in the PR body. -A green test suite without an independently observed task outcome is incomplete. +A green test suite without an independently observed outcome is incomplete when +independent runtime verification is required. diff --git a/AGENTS.md b/AGENTS.md index 507994e..a1122af 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,13 +25,16 @@ MCP service in one npm/Turborepo workspace. and prove the relevant compatibility contracts still hold. Preserve deployed interfaces and supported client behavior; repository checks alone do not prove a live change is safe. -10. Delegate every substantive repository task to at least one project agent so - detailed exploration or execution stays out of the primary context. - "Substantive" includes repository exploration, multi-file reasoning, - implementation, test execution, or contract/risk analysis. Use `repo_scout` - for read-only investigation and `implementation` for bounded changes; use - the additional roles according to `docs/agents/routing.md`. The primary - agent retains scope, acceptance, review, and the final answer. Skip +10. The Sol primary agent owns scope, risk classification, acceptance criteria, + progress steering, final diff and evidence review, and the final answer. + Delegate every substantive repository task to a project agent. Each + substantive implementation must use one Terra `implementation` agent as a + coherent execution unit, normally combining scoped discovery, implementation, + focused tests, and iteration. "Substantive" includes repository exploration, + multi-file reasoning, implementation, test execution, or contract/risk + analysis. Add a `repo_scout`, reviewer, or verifier only for separable work or + the triggers in `docs/agents/routing.md`; do not duplicate the implementation + agent's detailed exploration or checks without a concrete reason. Skip delegation only for trivial conversation, a single obvious lookup, or a mechanical one-line edit whose coordination cost exceeds the work. 11. Use high-effort reviewers only for the risk triggers in diff --git a/docs/agents/routing.md b/docs/agents/routing.md index adf0979..4f5a9d1 100644 --- a/docs/agents/routing.md +++ b/docs/agents/routing.md @@ -1,12 +1,17 @@ # Agent routing and effort -The primary agent owns scope, acceptance criteria, task decomposition, review, -and the final answer. Every substantive repository task must delegate at least -one bounded unit to the best-fit project agent. Use `repo_scout` for read-only -discovery or analysis and `implementation` for product or harness changes. Add -other agents only for separable work or the risk triggers below. Skip delegation -only for trivial conversation, a single obvious lookup, or a mechanical one-line -edit whose coordination cost exceeds the work. +Sol is the primary agent and owns scope, risk classification, acceptance +criteria, task decomposition, progress steering, final diff and evidence review, +and the final answer. Every substantive repository task must delegate to a +project agent. Each substantive implementation must delegate one coherent +execution unit to the Terra `implementation` agent. That handoff normally +combines scoped discovery, implementation, focused tests, and iteration in one +continuous task. Add a `repo_scout`, reviewer, test writer, or verifier only for +separable work or the triggers below. The primary reviews the returned diff and +evidence, but does not repeat the implementation agent's detailed exploration or +checks without a concrete reason. Skip delegation only for trivial conversation, +a single obvious lookup, or a mechanical one-line edit whose coordination cost +exceeds the work. ## Implementation and integration @@ -44,10 +49,10 @@ Project Codex defaults live in `.codex/config.toml`; task profiles live in | Role | Codex model | Default effort | Trigger | Do not use for | |---|---|---:|---|---| -| `repo_scout` | Luna | low | locate ownership, callers, contracts | editing or design decisions | -| `implementation` | Terra | medium, overridable | bounded product or harness change | broad architecture review | +| `repo_scout` | Luna | low | separable read-only ownership, caller, or contract lookup | editing or design decisions | +| `implementation` | Terra | medium, overridable | one continuous scoped discovery, implementation, test, and iteration unit | broad architecture review | | `test_writer` | Terra | medium | focused regression or missing contract test | rubber-stamping green output | -| `verifier` | Terra | medium | independently drive implemented behavior | editing implementation | +| `verifier` | Terra | medium | user-facing, cross-boundary, or high-risk runtime behavior | editing implementation or low-risk package-local changes | | `database_reviewer` | Terra | high | migrations, RLS, function/query boundaries | ordinary UI changes | | `security_reviewer` | Sol | high | auth, RLS, crypto, secrets, payments, destructive operations | every routine change | | `architecture_reviewer` | Sol | high | cross-cutting or hard-to-reverse decisions | local refactors | @@ -71,13 +76,26 @@ the implementation agent into a premium generalist. Add the matching read-only Sol reviewer and keep implementation on Terra unless the user explicitly asks for a different model. +## Verification routing + +Use a fresh Terra `verifier` after implementation when the change has +user-facing runtime behavior, crosses an application, API, data, authentication, +or provider boundary, or is otherwise high risk. The verifier independently +drives the acceptance criteria and returns evidence only. It is not required for +documentation, mechanical configuration, isolated tests, or low-risk +package-local changes with focused deterministic checks. A verifier may still be +added when independent observation would materially increase confidence. + ## Handoff contract Every delegated task includes the objective, owned files or surface, acceptance criteria, applicable `AGENTS.md` and skill, allowed side effects, required checks, and the evidence to return. The agent must report changed files, commands and -results, assumptions, and blockers. The primary agent independently reviews the -diff and decides whether acceptance has been met. +results, assumptions, and blockers. The primary independently reviews the final +diff and evidence and decides whether acceptance has been met. It should steer +the active implementation agent with targeted feedback rather than restart the +same discovery or verification in another agent unless an independent judgment, +separable workstream, or the verification-routing trigger requires it. Parallel agents are for independent read-heavy work or non-overlapping ownership. Avoid concurrent edits to the same files, shared database state, fixed local