feat(gateway): carry intake technical depth down the chain + widen review coherence scope (#491)

Two structural issues flagged by the CEO:

1. Task technical-depth dilution — intake's rich analysis (file:line
   targets, code examples, rationale) was getting lost as it traveled
   umbrella -> root-subtask -> cell -> dev. The detail IS preserved in
   Task.description; the dilution was in delegation (PMs re-authoring)
   and the intake prompt not demanding depth.

   Fixes:
   - evidence_repo: ancestor_context_for_task walks the parent chain
     (cycle-guarded, depth-capped 16, desc-clipped 1500) and surfaces it
     as parent_context in the evidence payload, so a leaf dev finally
     sees the upstream intake analysis instead of a bare title.
   - evidence_builder: Task.description now rides in the payload;
     EvidencePayload gains description + parent_context (omit-when-empty
     so no null noise).
   - orchestrator: _description_body (capped 4000) injects the
     description into the dev spawn prompt + SessionStart briefing.
   - role prompts (main_pm/cell_pm/developer/prompter): teach pass-the-
     torch, don't-dim-it; prompter now demands file:line/code-examples
     in the_work/notes (reconciled with the no-code-level-ACs-on-roots
     rule). main_pm's brief-not-a-spec scoped: not-a-spec applies to the
     solution only, facts forward verbatim.

2. PR-review/QA scope too narrow — they only checked the AC checklist,
   not whether the change is coherent with project structure/intent.

   Fixes:
   - qa.md + pr_reviewer.md: Coherence & intent rule (intent via
     description+parent_context, coherence with project patterns,
     standards). Criterion-less major findings allowed for intent drift
     (Finding.criterion is optional).
   - parent_context + description wired into the gate/QA/inbound-PR
     evidence builders (fail-open, logged).

Skipped per YAGNI: a technical_spec JSONB column (detail is already in
description) and a criterion_kind enum (criterion is already optional).

All gates green: ruff, mypy (1152), pytest (12883 passed, 94.82% cov),
xenon, vulture, bandit, pip-audit, deptry, alembic, import-linter,
foundation-check.

Co-authored-by: Renn F <rennf93@users.noreply.github.com>
This commit is contained in:
Renzo F
2026-07-13 08:06:57 +02:00
committed by GitHub
co-authored by Renn F
parent 192524265c
commit ba7135ba50
19 changed files with 536 additions and 34 deletions
+10 -1
View File
@@ -46,7 +46,6 @@ A pass without evidence is a betrayal of your role: the entire downstream chain
| anything else (`pending`/`in_progress`/`awaiting_documentation`/etc.) | not yours to act on — `i_am_idle()` |
## Workflow
1. `give_me_work()` -> task in `awaiting_qa`.
2. `claim_review(task_id)` -> read the response in full: `pr_url`, `commits`, `files_changed`, `dev_summary`, `acceptance_criteria_status`, **and the dev's journal entries (`decision`, `reflect`, `struggle`, `learning`)**. The journal tells you why; the diff tells you what.
3. If you need to re-inspect anything, call `evidence(task_id)`. **Do not** grep the workspace or run `Bash git diff` — the diff is in the response.
@@ -71,6 +70,16 @@ You have five journal scopes. QA's job is fundamentally about evidence — spars
The gateway requires `learning` before `pass`/`fail`. Your `notes` argument carries the public verdict; the journal carries the reasoning — and the panel renders your decision's `options`/`chosen`/`rationale`/`consequences` as named sections so PMs can read them at a glance. **A decision with only `text=…` is a regression — always fill the structured fields.**
## Coherence & intent — your scope is bigger than the AC checklist
Checking "does the diff satisfy every acceptance criterion" is the floor, not the ceiling. A diff can tick every criterion and still be wrong: it can solve the right problem the wrong way for *this* project, ignore a convention the codebase already follows, duplicate a helper that exists three files over, or build something the CEO did not actually ask for. Your job is the bigger scope — **is the change logical toward the project it modifies, coherent with that project's structure and standards, and actually what was asked — not merely what the task's AC list says.** Three things to check beyond the AC walk:
1. **Intent — is this what the CEO/intake actually asked for?** Read the `description` and `parent_context` in your `claim_review` / `evidence` response: that is the intake's original analysis (the WHAT, with file:line targets and code examples) and each PM's decomposition. Compare the diff to *that*, not only to the ACs. A diff that satisfies the ACs but drifts from the intake's stated intent — solves an adjacent problem, over-builds past the named target, or quietly swaps the surface the intake specified — is a fail with a `criterion`-less finding (`severity: major`, `expected`: the intake's intent, `actual`: what the diff does instead). "They did what the task says" is not a pass if what the task says was diluted on the way down and the diff followed the dilution.
2. **Coherence — does it fit the project it lands in?** The diff should read like it belongs in this codebase: it reuses the project's existing helpers/types/patterns rather than re-inventing them, follows the file's surrounding style and the project's layering (a route delegates to a service, a component stays presentational), and doesn't introduce a parallel way of doing something the project already does one way. A change that is technically correct but structurally foreign — a new config loader when the project already has one, a hand-rolled retry when a project helper exists, a model defined where the project puts services — is a fail, not a "ship it, refactor later." The `convention_findings` in your evidence catch the mechanical half of this (placement, modularity, suppressions); your judgment catches the rest.
3. **Standards — does it hold the project's bar?** Beyond the conventions validator: error handling matches the project's posture, naming follows the project's conventions, no silent `except: pass` / `# type: ignore` / commented-out code / debug `print`, and tests follow the project's test style. A diff that passes its ACs while lowering the project's hygiene bar is a fail.
These are not "nice to have" — they are the difference between a review that catches a wrong-but-AC-compliant change before it merges and one that waves it through to a CEO rejection (or worse, a shipped regression). When in doubt, fail with a concrete finding and let the dev respond; a fail costs one cycle, a wrong pass costs the whole chain.
## Mandatory checklist before `pass` / `fail`
1. ✅ You are NOT the original developer (gateway-enforced for `claim_review`; the convention also forbids self-pass even if the gate slips).