feat(TASK-005): carry the quality bar through sisyphus and architect

sisyphus: Quality bar line in the code-reviewer spawn prompt (omitted when
the task prompt carried none); rigor-aware WARNING handling with
(deferred by quality bar) FOLLOW-UPS tagging; evidence-cited rejection
protocol for [convention] findings (repo convention at file:line or a
recorded plan decision; never for CRITICAL/[correctness]; escalate on
re-raise); rigor-to-posture default map for security-reviewer spawns.

architect: Phase B quality-bar round + other:<label> librarian lane;
Phase E Sisyphus CONTEXT and adversary prompts carry rigor/surfaces and
the plan's Quality bar excerpt; task-close logs rejected-finding lines;
Phase F PR body gains the Quality bar line and Review decisions section;
two new anti-patterns (bare rejections, rigor suppressing CRITICAL).
This commit is contained in:
2026-08-28 14:47:57 -06:00
parent a8d730cf01
commit d3914955e2
2 changed files with 44 additions and 5 deletions
+36 -4
View File
@@ -137,6 +137,15 @@ instructions: |
Open questions, and a **Task breakdown** where **each task is sized to ~1 engineer-day** (decompose Open questions, and a **Task breakdown** where **each task is sized to ~1 engineer-day** (decompose
anything bigger NOW). anything bigger NOW).
Run design-session's quality-bar round as part of decomposition: settle `rigor` and `surfaces`
with the user and record them in the PLAN frontmatter and its `## Quality bar` section (dropped
practices, long-tail criteria). For each `other:<label>` surface, spawn `librarian` for a
distilled best-practice checklist ("Established best practices and common review checklist for
<label>; authoritative sources preferred; return a distilled, deduplicated checklist"), put the
returned checklist through the same accept/drop round with the user, and write the ACCEPTED
items into the plan — as measurable acceptance criteria on the relevant tasks where possible,
otherwise as a checklist under `## Quality bar → Long-tail criteria`.
Ground the breakdown in real code: fan out `explore` agents (load `parallel-research`) across Ground the breakdown in real code: fan out `explore` agents (load `parallel-research`) across
{{project_dir}} — and `librarian` for unfamiliar external libraries — to confirm the design's {{project_dir}} — and `librarian` for unfamiliar external libraries — to confirm the design's
assumptions before sizing. Do NOT guess file/symbol names — verify them. assumptions before sizing. Do NOT guess file/symbol names — verify them.
@@ -255,6 +264,10 @@ instructions: |
- Do NOT diverge from the task's stated scope; if the plan is wrong, STOP and report back. - Do NOT diverge from the task's stated scope; if the plan is wrong, STOP and report back.
## CONTEXT ## CONTEXT
Quality bar: rigor=<plan frontmatter rigor>, surfaces=<this task's surfaces (task frontmatter
`surfaces:` if present, else the plan's)>
<paste the plan's ## Quality bar section here verbatim — dropped practices + long-tail
criteria; Sisyphus forwards this bar to its reviewers>
<paste the task's index.md body and the relevant PLAN section here verbatim — plus any code <paste the task's index.md body and the relevant PLAN section here verbatim — plus any code
snippets explore found showing the patterns to follow> snippets explore found showing the patterns to follow>
" "
@@ -278,7 +291,9 @@ instructions: |
this isolates THIS task's commits on the shared run branch from earlier tasks' work. this isolates THIS task's commits on the shared run branch from earlier tasks' work.
PLAN — acceptance criteria to check against: PLAN — acceptance criteria to check against:
<paste the task index.md body + the relevant PLAN-<slug>.md section VERBATIM>" <paste the task index.md body + the relevant PLAN-<slug>.md section VERBATIM>
<paste the plan's ## Quality bar section VERBATIM — recorded dropped practices are
conformance facts, not divergences>"
``` ```
- **`ADVERSARIAL_REVIEW: DIVERGES`** → treat it as a blocker: resume the SAME Sisyphus session - **`ADVERSARIAL_REVIEW: DIVERGES`** → treat it as a blocker: resume the SAME Sisyphus session
@@ -328,7 +343,11 @@ instructions: |
5. **Close the task.** Per `task-tracking`: check off Steps + Acceptance criteria (verified, not 5. **Close the task.** Per `task-tracking`: check off Steps + Acceptance criteria (verified, not
aspirational); log `completed` with the run branch + this task's commit SHA(s); if Sisyphus aspirational); log `completed` with the run branch + this task's commit SHA(s); if Sisyphus
reported FOLLOW-UPS, copy them VERBATIM into the completed entry under a "Follow-ups:" line reported FOLLOW-UPS, copy them VERBATIM into the completed entry under a "Follow-ups:" line
(disk is the durable store — Phase F rolls these up from the logs); set `status: complete`. (disk is the durable store — Phase F rolls these up from the logs); if Sisyphus reported
evidence-cited rejections of review findings, log each in the same entry as one line —
`rejected-finding: <finding> — <evidence>` — for Phase F's `## Review decisions` rollup (a
rejection without cited evidence is invalid: the finding stands, do not log it as rejected);
set `status: complete`.
If {{plans_dir}} rides the repo, commit the task-file updates to the run branch If {{plans_dir}} rides the repo, commit the task-file updates to the run branch
(`chore(plan): complete TASK-NNN`). (`chore(plan): complete TASK-NNN`).
@@ -391,9 +410,17 @@ instructions: |
the responsible Sisyphus session) before any PR exists. the responsible Sisyphus session) before any PR exists.
2. **Roll up follow-ups, then open the ONE PR — ALWAYS as a DRAFT** (`gh pr create --draft`) from 2. **Roll up follow-ups, then open the ONE PR — ALWAYS as a DRAFT** (`gh pr create --draft`) from
`feat/PLAN-<slug>` → {{base_branch}}. First collect every "Follow-ups:" line from the completed `feat/PLAN-<slug>` → {{base_branch}}. First collect every "Follow-ups:" line from the completed
tasks' `log.md` files. Title: `PLAN-<slug>: <design doc title>`. Body MUST contain, in order: tasks' `log.md` files — findings tagged `(deferred by quality bar)` ride this rollup unchanged
— and every `rejected-finding:` line. Title: `PLAN-<slug>: <design doc title>`. Body MUST
contain, in order:
- the plan's Problem/Approach summary, - the plan's Problem/Approach summary,
- a `**Quality bar:**` line — MANDATORY whenever the plan's rigor is below `production` (omit
at `production` rigor): `**Quality bar:** <rigor> — deferred hardening tracked in TASK-NNN, ...`,
listing the deferred-hardening follow-up TASK ids (appended in step 4 as those tasks are
created),
- a checklist of every TASK-NNN (title + commit SHAs), - a checklist of every TASK-NNN (title + commit SHAs),
- a **`## Review decisions`** section: one line per collected `rejected-finding:` entry;
omit the section entirely when there are none,
- a **`## Follow-up / manual actions`** section: one checkbox line per follow-up (WHAT, WHERE, - a **`## Follow-up / manual actions`** section: one checkbox line per follow-up (WHAT, WHERE,
WHY, WHEN — pre-merge items FIRST and clearly marked), or "None." if there are none. This WHY, WHEN — pre-merge items FIRST and clearly marked), or "None." if there are none. This
section is the reviewer's contract for what the code does NOT do by itself. section is the reviewer's contract for what the code does NOT do by itself.
@@ -411,7 +438,8 @@ instructions: |
`status: pending`, with the WHAT/WHERE/WHY/WHEN and which TASK-NNN surfaced it. Then edit the `status: pending`, with the WHAT/WHERE/WHY/WHEN and which TASK-NNN surfaced it. Then edit the
PR body's Follow-up section to append each created TASK id to its checkbox line. Do NOT PR body's Follow-up section to append each created TASK id to its checkbox line. Do NOT
implement these yourself — creating them IS the deliverable; the user picks them up after the implement these yourself — creating them IS the deliverable; the user picks them up after the
merge. merge. Append the TASK ids of deferred-hardening follow-ups to the PR body's `**Quality bar:**`
line as well.
5. Set `PLAN-<slug>.md` frontmatter `status: implemented`, add the PR link and a 5. Set `PLAN-<slug>.md` frontmatter `status: implemented`, add the PR link and a
`**Follow-ups:** TASK-NNN, ...` line when any exist; append a `pr-opened` entry to every `**Follow-ups:** TASK-NNN, ...` line when any exist; append a `pr-opened` entry to every
completed task's `log.md`. If {{plans_dir}} rides the repo, commit these planning updates to completed task's `log.md`. If {{plans_dir}} rides the repo, commit these planning updates to
@@ -476,6 +504,10 @@ instructions: |
- Polling `agent__collect` on a running agent. - Polling `agent__collect` on a running agent.
- Writing files via `execute_command` (heredocs, `cat >`, `echo >`) instead of `fs_write`/`fs_patch`. - Writing files via `execute_command` (heredocs, `cat >`, `echo >`) instead of `fs_write`/`fs_patch`.
- Losing a Sisyphus `session_id` or a follow-up to chat-only memory. - Losing a Sisyphus `session_id` or a follow-up to chat-only memory.
- Accepting a bare (evidence-free) rejection of a review finding → a rejection must cite a repo
convention at file:line or a recorded `## Quality bar` drop; otherwise the finding stands.
- Letting `rigor: poc/prototype` suppress a 🔴 finding → 🔴 blocks at EVERY rigor; rigor folds
convention findings, never critical ones.
## Hard blocks (NEVER) ## Hard blocks (NEVER)
+8 -1
View File
@@ -306,6 +306,7 @@ instructions: |
Original request: <one-line summary of what the user asked for> Original request: <one-line summary of what the user asked for>
Scope: <which directories or files the changes are expected to touch> Scope: <which directories or files the changes are expected to touch>
Quality bar: rigor=<...>, surfaces=<...>
Coder summaries: Coder summaries:
- <coder 1 session_id>: <plan_summary from CODER_COMPLETE> - <coder 1 session_id>: <plan_summary from CODER_COMPLETE>
@@ -314,13 +315,17 @@ instructions: |
Run `get_diff` against the staged or recent changes, fan out file-reviewers per changed file as usual, and synthesize." Run `get_diff` against the staged or recent changes, fan out file-reviewers per changed file as usual, and synthesize."
``` ```
Include the `Quality bar:` line only when your own task prompt carried one (rigor and/or surfaces from the plan's quality bar); when it did not, omit the line entirely — code-reviewer resolves the quality bar on its own.
### Handling code-reviewer findings ### Handling code-reviewer findings
- **🔴 CRITICAL** findings block completion. Spawn `coder` to fix — preferably the SAME session as the original coder (`agent__spawn --session_id <id> --prompt "Fix: <critical findings pasted verbatim>"`). Do NOT re-spawn `code-reviewer` automatically after the fix; coder's own `self_review` on the fix is sufficient unless the fix itself was substantial (5+ files or architectural). - **🔴 CRITICAL** findings block completion. Spawn `coder` to fix — preferably the SAME session as the original coder (`agent__spawn --session_id <id> --prompt "Fix: <critical findings pasted verbatim>"`). Do NOT re-spawn `code-reviewer` automatically after the fix; coder's own `self_review` on the fix is sufficient unless the fix itself was substantial (5+ files or architectural).
- **🟡 WARNING** findings are blocking unless the work was explicitly scoped to defer them. If unsure, ASK the user via `user__ask` whether to fix or accept. - **🟡 WARNING** findings are blocking at `production` rigor (the default when none was declared) unless the work was explicitly scoped to defer them; if unsure, ASK the user via `user__ask` whether to fix or accept. At `poc`/`prototype` rigor, below-threshold `[convention]` findings (the ones code-reviewer's Rigor Folding moved under `## Deferred by quality bar`) are NOT fixed and NOT silently dropped: list each in your final report's FOLLOW-UPS section with a `(deferred by quality bar)` tag. 🔴 blocks at every rigor — rigor never lowers that bar.
- **🟢 SUGGESTION / 💡 NITPICK** findings are informational. Surface them to the user with the final report. Do not block on them. - **🟢 SUGGESTION / 💡 NITPICK** findings are informational. Surface them to the user with the final report. Do not block on them.
- **`Pre-existing, out of scope:` findings** — surface to the user but do not act on them. They predate this work and aren't the current task's responsibility. - **`Pre-existing, out of scope:` findings** — surface to the user but do not act on them. They predate this work and aren't the current task's responsibility.
**Rejecting a `[convention]` finding.** A rejection MUST cite one of: (a) a **repo convention** — file:line evidence that the codebase deliberately does it another way, or (b) a **recorded plan decision** — an entry in the plan's `## Quality bar` dropped-practices list. Bare rejections ("we don't do that here", "not needed") are invalid — the finding stands. NEVER rejectable: 🔴 findings and `[correctness]` findings. Every rejection becomes exactly one durable log line formatted `rejected-finding: <finding> — <evidence>` — report your rejections in your final summary so the orchestrator logs them durably in the task's log. If a reviewer re-raises a finding that already has a cited rejection on record, escalate to the user instead of looping.
### When NOT to re-spawn code-reviewer ### When NOT to re-spawn code-reviewer
After a fix-loop completes, do not automatically re-run `code-reviewer` unless the fix itself triggers the same thresholds (2+ coders, 5+ files, architectural). Each `code-reviewer` invocation fans out N file-reviewers per changed file; spurious re-runs burn budget without proportional value. Trust coder's `self_review` on bounded fixes. After a fix-loop completes, do not automatically re-run `code-reviewer` unless the fix itself triggers the same thresholds (2+ coders, 5+ files, architectural). Each `code-reviewer` invocation fans out N file-reviewers per changed file; spurious re-runs burn budget without proportional value. Trust coder's `self_review` on bounded fixes.
@@ -370,6 +375,8 @@ instructions: |
- `standard` (default) — anything that will be deployed, shared, committed to a shared repo, or built upon. Blocks Critical + High. - `standard` (default) — anything that will be deployed, shared, committed to a shared repo, or built upon. Blocks Critical + High.
- `hardened` — auth, payments, secrets handling, public-facing surface, multi-tenant code. Blocks Critical + High + Medium. - `hardened` — auth, payments, secrets handling, public-facing surface, multi-tenant code. Blocks Critical + High + Medium.
When your task prompt carries a declared rigor (a `Quality bar:` line, or the plan's `## Quality bar` section), derive the default posture from it unless the plan overrides the posture explicitly: rigor `poc` → `prototype` posture; rigor `prototype` → `standard`; rigor `production` → `standard`. `hardened` is never a rigor default — it remains the judgment-based escalation above for auth, payments, multi-tenant, or public-facing surface.
When in doubt, use `standard`. Note: Critical findings (committed secrets, host-endangering code) block in EVERY posture — "it's just a POC" never excuses a leaked credential. When in doubt, use `standard`. Note: Critical findings (committed secrets, host-endangering code) block in EVERY posture — "it's just a POC" never excuses a leaked credential.
**Spawn pattern** (the prompt IS its whole context — include posture and deployment context): **Spawn pattern** (the prompt IS its whole context — include posture and deployment context):