docs(tier2): apply user feedback - 6 workflow conventions

User feedback from the first sandbox run (send_result_to_send_20260616,
2026-06-17) identified 6 conventions Tier 2 must follow. Update the agent
prompt template, slash command template, user guide, and workflow doc:

1. Test runner: ALWAYS use 'uv run python scripts/run_tests_batched.py'
   (NOT 'uv run pytest'). The batched runner provides tier filtering,
   parallelization (xdist), and a summary table that direct pytest lacks.

2. Default branch: this repo uses 'master', not 'main'. The Tier 2 slash
   command now does 'git fetch origin master' (was 'origin main').

3. Line endings: preserve existing. This repo has a mix of CRLF and LF;
   a repo-wide LF standardization is a future track.

4. Throw-away scripts: write to 'scripts/tier2/artifacts/<track>/', NOT
   the base 'scripts/tier2/' directory. The base is reserved for
   production code; throw-away scripts are kept for archival but
   isolated per-track.

5. End-of-track report: write 'docs/reports/TRACK_COMPLETION_<track>.md'
   and update 'state.toml' to 'status=completed'. The user reads this
   to decide merge. Previously this was implicit; now it's explicit.

6. Run-time expectation: tracks are 1-4 hours. If context runs out, Tier
   2 notes progress to disk and continues. The --resume flag picks up
   from the last completed task.

Also updated the user guide with a 'Conventions' section and a
troubleshooting entry for the resume flow. The verify-the-sandbox
checklist now uses 'origin master' instead of 'origin main'.
This commit is contained in:
ed
2026-06-17 02:13:29 -04:00
parent 1fc4a6026b
commit 07a0e66a19
4 changed files with 80 additions and 11 deletions
@@ -20,19 +20,29 @@ Optional flags: `--resume` (continue from last completed task), `--toast` (Windo
## Protocol
1. `git fetch origin main`
2. `git switch -c tier2/<track-name> origin/main` (NOT `git checkout` - it is banned)
1. `git fetch origin master` (NOTE: this repo uses `master`, not `main`; added 2026-06-17)
2. `git switch -c tier2/<track-name> origin/master` (NOT `git checkout` - it is banned)
3. Initialize failcount state at `<app-data>/tier2/<track-name>/state.json` (use `load_state` or fresh state)
4. For each task in `plan.md`:
a. Red: delegate test creation to @tier3-worker
b. Run tests; if pass unexpectedly, call `record_red_failure` and check `should_give_up`
c. Green: delegate implementation to @tier3-worker
d. Run tests; if fail, call `record_green_failure` and check `should_give_up`
e. On green: `record_commit` and `record_green_success` (resets counters)
f. Commit per task with `git add . && git commit -m "..."` and attach git note
g. Update `plan.md` with commit SHA
5. After all tasks complete, print success summary.
b. Run tests via `uv run python scripts/run_tests_batched.py` (NEVER `uv run pytest` directly; the batched runner provides tier filtering, parallelization, and the summary table — added 2026-06-17)
c. If pass unexpectedly, call `record_red_failure` and check `should_give_up`
d. Green: delegate implementation to @tier3-worker
e. Run tests via `scripts/run_tests_batched.py`; if fail, call `record_green_failure` and check `should_give_up`
f. On green: `record_commit` and `record_green_success` (resets counters)
g. Commit per task with `git add <specific files> && git commit -m "..."` and attach git note
h. Update `plan.md` with commit SHA
5. After all tasks complete, write the end-of-track report (see step 7) and print success summary.
6. On give-up: call `write_failure_report` from `scripts.tier2.write_report`, print "TRACK ABORTED, see report at <path>".
7. **End-of-track report** (added 2026-06-17): on success, write `docs/reports/TRACK_COMPLETION_<track-name>.md` following the precedent set by `TRACK_COMPLETION_tier2_autonomous_sandbox_20260616.md`. Update `conductor/tracks/<track-name>/state.toml` to `status = "completed"`. The user reads this report to decide merge.
## Conventions (MUST follow - added 2026-06-17)
- **Test runner:** use `uv run python scripts/run_tests_batched.py` (NOT `uv run pytest`)
- **Default branch:** `master` (this repo never had `main`)
- **Line endings:** preserve existing (CRLF stays CRLF, LF stays LF)
- **Throw-away scripts:** write to `scripts/tier2/artifacts/<track-name>/`, NOT the base directory
- **Run-time expectation:** tracks are 1-4 hours. If context runs out, note progress to disk and continue.
## Hard Bans (enforced by 3 layers)