shapeup-sdlc 1.6.2 → 1.7.0

package/skills/spec-evaluator/references/dimensions/_registry.md

@@ -9,9 +9,9 @@ command line overrides this table for a single run.
 |----|---------|------|----------------------|-------|
 | `spec-conformance` | ✅ true | `dimensions/spec-conformance.md` | all tasks | baseline correctness: AC + Done-when + contract shapes + non-go |
 | `tdd-surface` | ✅ true | `dimensions/tdd-surface.md` | all tasks | suite green + companion test files for new code; TDD-1/2 critical, TDD-3 advisory |
-| `integration` | ✅ true | `dimensions/integration.md` | `.be` and `.e2e` variants only | full-stack integration test + auth boundary + RLS-JWT pattern; runs only when variant matches |
+| `integration` | ✅ true | `dimensions/integration.md` | `.be` and `.e2e` variants only | full-stack integration test + access boundary + enforcement-path integrity; stack read from the project profile, not hard-coded; runs only when variant matches |
 | `completeness` | ⚙️ auto | `dimensions/completeness.md` | all tasks (lens lite/standard) | auto-ON when spec has UC `## Invariants` (v2.8+); no-op on older specs |
-| `test-surface-conformance` | ⚙️ auto | `dimensions/test-surface-conformance.md` | all tasks (lens lite/standard) | auto-ON when spec has UC `## Test Surface` (v2.9+ or `--surface-only` retrofit); no-op otherwise. Report must list every TS row probed — qa-edge-hunter's negative-space input |
+| `test-surface-conformance` | ⚙️ auto | `dimensions/test-surface-conformance.md` | all tasks (lens lite/standard) | auto-ON when spec has UC `## Test Surface` (v2.9+ or a retrofit-surface order); no-op otherwise. Report must list every TS row probed — qa-edge-hunter's negative-space input |
 | `security` | ⛔ false | `dimensions/security.md` | be / shared | stub — flip on when ready |
 | `performance` | ⛔ false | `dimensions/performance.md` | be / web | stub — flip on when ready |
 

package/skills/spec-evaluator/references/dimensions/completeness.md

@@ -25,7 +25,7 @@ criteria?"* — it grades the tasks that exist. It cannot see the task that was
 written. Shape Up's discovered-task philosophy says the real bulk of work is found while
 building; an invariant declared on a UC but never backed by a regression task is exactly
 that blind spot. This dimension converts "absence of a task" from invisible into a graded
-**GAP** — the judge surfaces it; the planner (a ba-pitch-analyzer reconcile/generate-board order) fills it.
+**GAP** — the judge surfaces it; the planner (a ba-pitch-analyzer `reconcile` order) fills it.
 Judge never fills it itself.
 
 **Distinction held:** conformance = *the tasks that exist are correct*; completeness =

package/skills/spec-evaluator/references/dimensions/integration.md

@@ -15,28 +15,27 @@ requires_browser: false
 
 **Why this exists.** Unit tests verify isolated logic. `spec-conformance` drives the
 running app and confirms AC at the surface. Neither catches the class of bug where each
-layer works in isolation but the *seam* is broken: wrong auth header forwarded, RLS policy
-not invoked because the transaction is missing, Prisma schema migration not applied in the
-test database, or a contract mismatch between web's api-client and the API controller.
-This dimension fills that seam.
-
-**What "system integration" means here** (scoped to the IVS ADR-005 stack):
-the full request path — web api-client → API controller → service → repository (Prisma +
-RLS) → database — exercised by tests that use a real database, not mocked layers.
-An integration test that mocks `PrismaClient` or replaces the repository with an in-memory
-stub is a unit test wearing integration clothing and does not satisfy this dimension.
-
-**Project context (read AGENTS.md Section 2 rules 3 & 4 before probing):**
-- All user-scoped queries must run inside a transaction that injects the JWT claims so RLS
-  fires (`SET LOCAL request.jwt.claims`). An integration test that queries without this
-  transaction bypasses RLS and produces a false-positive PASS.
-- The connection string must point to the **transaction-mode pooler** (port 6543), not the
-  session-mode direct connection (port 5432). Session mode allows `SET LOCAL` to leak.
-- Never trust a `userId` sent in the request body — derive it from the verified JWT.
+layer works in isolation but the *seam* is broken: the wrong auth header forwarded, an
+authorization policy never invoked because the call bypassed the layer that enforces it, a
+schema migration not applied to the test database, or a contract mismatch between the client
+and the handler it calls. This dimension fills that seam.
+
+**What "system integration" means here:** the full request path — client → entry point →
+application logic → persistence — exercised by tests that use the project's **real**
+dependencies, not mocked layers. An integration test that mocks the database client or
+replaces the repository with an in-memory stub is a unit test wearing integration clothing
+and does not satisfy this dimension.
+
+**Read the project's stack from the artifacts, not from this file.** The commands, file
+patterns, and enforcement mechanisms differ per project: resolve them from
+`project-profile.md` (`archetype`, `entry_point`), the scope contract's
+`e2e_verification_fixtures`, and the spec's `contracts/`. This file states the invariant;
+the "Probing notes" section carries worked examples of what it looks like in common stacks.
+A project whose stack matches none of them still owes the invariant.
 
 **`.e2e` variant:** the e2e suite inherently exercises the full stack. INT-1 (integration
 test existence) maps to the e2e test file(s) added by the task. INT-2 and INT-3 apply if
-the e2e task introduces any auth-scoped endpoint.
+the e2e task introduces any access-controlled operation.
 
 ---
 
@@ -44,47 +43,59 @@ the e2e task introduces any auth-scoped endpoint.
 
 ```yaml
 - id: INT-1
-  statement: "At least one integration/e2e test exercises the feature's main flow end-to-end with a real database — no mocked repository or Prisma layer."
+  statement: "At least one integration/e2e test exercises the feature's main flow end-to-end against the project's real dependencies — no mocked data layer."
   probe: static + cmd
   evidence_required: true
   pass_rule: >
-    Locate integration test files for this task's package (typically `*.integration.spec.ts`,
-    `*.e2e-spec.ts`, or a `test/` directory at the package root). Grep for test cases that
-    touch the happy-path scenario the task implements. Verify the test does NOT mock the
-    data layer: `grep -rE 'jest\.mock|vi\.mock' <integration-test-file>` should return no
-    hits on repository, Prisma, or database imports. Then run `pnpm --filter <pkg> test:e2e`
-    (or the integration-specific script) and capture exit code + test count.
-    Zero integration test files → FAIL at `critical`. Any integration test that mocks the
-    DB layer → FAIL at `critical` (evidence: the jest.mock / vi.mock import path).
+    Locate the integration test files for this task's package — resolve the pattern and the
+    runner command from the scope contract's `e2e_verification_fixtures`, else the project's
+    test scripts (a target named for integration/e2e rather than unit). Grep for test cases
+    that touch the happy-path scenario the task implements. Verify the test does NOT mock the
+    data layer: search the file for the project's mocking primitive and inspect what it
+    replaces. Mocking outbound third-party calls (HTTP clients, email, payment sandboxes) is
+    acceptable and often required; mocking the database client, the repository, or the
+    persistence connection defeats the dimension. Then run the integration suite and capture
+    exit code + test count. Zero integration test files → FAIL at `critical`. Any integration
+    test that mocks the data layer → FAIL at `critical` (evidence: the mock call and the
+    module path it replaces).
   source: code
 
 - id: INT-2
-  statement: "An unauthorized-access scenario is covered: a request from a different user/org is rejected with the correct error (403 or empty set), exercised by an integration test."
+  statement: "An unauthorized-access scenario is covered: a request from an unentitled caller is rejected with the documented outcome, exercised by an integration test."
   probe: cmd + data
   evidence_required: true
   pass_rule: >
-    Find the integration test that exercises the unauthorized path: a user from a different
-    org (or an unauthenticated caller) attempts to read/write the resource this task
-    introduces. The test asserts the correct rejection: 403 Forbidden, an empty result set,
-    or an RLS-filtered response. If the resource is read-only to viewers (role_tag check),
-    also verify a `viewer` role cannot mutate it. Evidence = the test case text + the run
-    output showing it passes. No such test → FAIL at `critical` — this is the gap that lets
-    real authorization bugs slip through conformance testing.
-  source: code
+    FIRST establish whether the feature has an access boundary at all: does the spec
+    (`usecases/` Error Cases, `contracts/`, the Non-Go list) document any caller who must NOT
+    reach this operation — a different tenant/user/org, a lower-privilege role, an
+    unauthenticated caller? If the spec documents none and the operation is genuinely public,
+    record INT-2 as N/A with that citation and exclude it from the denominator; do not invent
+    an authorization requirement the spec does not state. Otherwise, find the integration test
+    exercising the unauthorized path and assert it checks the outcome the spec documents
+    (a rejection status, an empty result set, a filtered response). If the spec also
+    distinguishes read from write for a role, verify the read-only role cannot mutate.
+    Evidence = the test case text + the run output showing it passes. A documented boundary
+    with no such test → FAIL at `critical` — this is the gap that lets real authorization
+    bugs slip through conformance testing.
+  source: usecases
 
 - id: INT-3
-  statement: "Integration tests inject JWT claims via the RLS transaction pattern (set_config inside a transaction) and target the transaction-mode pooler (port 6543)."
+  statement: "Integration tests exercise the same enforcement path production uses — the test setup does not bypass or elevate past the mechanism that enforces the boundary."
   probe: static
   evidence_required: true
   pass_rule: >
-    Inspect the integration test setup (beforeAll / test helper): it must execute
-    `SET LOCAL request.jwt.claims` (or the equivalent `$executeRaw\`select set_config(...)\``)
-    inside a Prisma `$transaction` block before any user-scoped query. Also check the
-    DATABASE_URL used in the test config: it must include port 6543 (transaction pooler),
-    not 5432 (session mode). A test that queries without the JWT injection calls the DB as
-    the app role without RLS and will PASS rows it should not see → FAIL at `major`.
-    A test using port 5432 risks SET LOCAL leaking across pooled connections → FAIL at `major`.
-    If both problems are present, report as two separate findings.
+    Applies only when INT-2 is in scope AND the project enforces the boundary in a layer a
+    test could bypass (database row-level policies, a middleware/guard chain, a tenant-scoped
+    client, a signed-context requirement). Identify that mechanism from the project profile,
+    the contracts, or the production wiring — then inspect the integration test setup
+    (suite-level hooks, test helpers, test env config) and confirm it goes through the same
+    path: the same credential/claim injection, the same connection or client mode, the same
+    guard chain. A setup that connects as an administrative or unscoped principal, disables
+    the guard layer, or seeds state through a back door calls the system with privileges the
+    real caller never has, and every access assertion above it is a false positive → FAIL at
+    `major`. If the project enforces the boundary only in code the test already traverses
+    (no bypassable layer exists), record INT-3 as N/A with that reasoning. Report each
+    distinct bypass as its own finding.
   source: code
 ```
 
@@ -93,12 +104,16 @@ the e2e task introduces any auth-scoped endpoint.
 ## Threshold
 
 `no-critical` — INT-1 and INT-2 are `critical`: a task that cannot prove end-to-end
-correctness and cannot prove its authorization boundary is not integration-tested and is
-not done. INT-3 (JWT transaction pattern + pooler port) is `major`: incorrect plumbing in
-the test setup produces false-positive passes (the test appears to work without RLS firing),
-which is a confidence-undermining failure — but it is one step removed from observable
+correctness, and cannot prove a documented authorization boundary, is not integration-tested
+and is not done. INT-3 (enforcement-path integrity) is `major`: a bypassed enforcement layer
+produces false-positive passes — the test appears to work while the boundary is never
+exercised — which is confidence-undermining, but it is one step removed from observable
 breakage and is reported as major rather than critical.
 
+A criterion recorded N/A under its own rule (INT-2 with no documented boundary, INT-3 with
+no bypassable layer) leaves the denominator, exactly like `tdd-surface`'s TDD-2 on `.e2e`.
+N/A requires the citation that justifies it; "no auth here, probably" is not a citation.
+
 ---
 
 ## Bug template
@@ -106,24 +121,40 @@ breakage and is reported as major rather than critical.
 ```
 severity: [critical|major]
 criterion: [INT-1|INT-2|INT-3]
-location: <test file path | package/test/setup.ts | .env.test | file:line>
-repro: <e.g. "grep -rE 'jest.mock.*repository' test/" | "grep DATABASE_URL .env.test" | "pnpm --filter api test:e2e">
-expected: <e.g. "integration test exists targeting BoardRepository with real DB" | "DATABASE_URL ends with :6543/...">
-actual: <e.g. "no *.integration.spec.ts in apps/api/src/boards/" | "DATABASE_URL uses port 5432" | "vi.mock('../../infrastructure/BoardRepository')">
-fix_hint: <e.g. "add boards/boards.integration.spec.ts; use PrismaService with a real test DB; wrap queries in $transaction with set_config">
+location: <test file path | test setup/helper | test env config | file:line>
+repro: <the command or search that shows it — e.g. the integration suite command, or the grep that finds the mock>
+expected: <e.g. "integration test covering <flow> against the real database" | "test setup injects the caller's own credentials">
+actual: <e.g. "no integration test found for <flow>" | "repository module is mocked in the suite" | "setup connects as the admin principal">
+fix_hint: <e.g. "add <flow> integration test using the real test database; route setup through the same guard chain production uses">
 ```
 
 ## Probing notes
 
-- Integration test scripts are often separate from unit tests: `test:e2e` / `test:int` /
-  `test:integration` in package.json. Check all scripts, not just `test`.
-- For mocking detection: `grep -rn "jest\.mock\|vi\.mock" <test-file>` and inspect what
-  is being mocked. Mocking HTTP clients, external APIs, or filesystem utilities is fine;
-  mocking the Prisma client or the repository class defeats integration testing.
-- For port check: the integration DB URL is typically in `.env.test` or `jest.config.ts`
-  (globalSetup). Check `DATABASE_URL` and `DIRECT_URL` separately — some setups split them.
-- For `.e2e` tasks: `supertest` or `axios` against the running NestJS server counts as
-  an integration test if it hits a real DB. Verify the test server's DB config, not just
-  the production server's config.
-- Do not skip INT-3 because the test "seems to work." RLS without `set_config` silently
-  returns all rows as the app role — the test passes but the auth boundary is untested.
+- **Find the suite before judging it.** Integration targets are usually separate from unit
+  tests (`test:e2e`, `test:int`, `test:integration`, a tagged subset, a separate config).
+  Check every script the project defines, not just the default `test` — "no integration
+  tests" is a FAIL, but "I only ran the unit target" is a probing error, not a finding.
+- **Mock detection is about the target, not the call.** Find the project's mocking primitive
+  (`jest.mock`/`vi.mock`, a DI container override, a fake registered in a test module,
+  a stubbed client factory) and inspect *what it replaces*. Outbound third parties: fine.
+  The data layer: fatal to the dimension.
+- **Worked example — row-level policies with claim injection.** Where the database enforces
+  access (e.g. Postgres RLS), the enforcement is a per-connection claim set inside a
+  transaction; a test that queries outside that transaction runs as the application role and
+  silently returns rows the real caller could never see. INT-3 there means checking the setup
+  performs the claim injection, and that the connection mode preserves it — a session-mode
+  connection can leak transaction-scoped settings across pooled connections where a
+  transaction-mode one does not. Both are INT-3 findings, reported separately.
+- **Worked example — guard/middleware chains.** Where a framework enforces access in a guard,
+  interceptor, or middleware, the bypass is a test that constructs the handler directly, or
+  registers a test module with the guard omitted. INT-3 means the test goes through the
+  composed application, not around it.
+- **Worked example — tenant-scoped clients.** Where scoping is a client constructed per
+  caller, the bypass is a shared admin/service client in the test setup. INT-3 means the test
+  builds its client the way a request does.
+- **For `.e2e` tasks**, a test driving the running server over HTTP counts as an integration
+  test if it reaches a real database. Verify the *test server's* configuration, not the
+  production server's — they routinely differ, and that difference is where INT-3 hides.
+- **Do not skip INT-3 because the test "seems to work."** An enforcement layer that is never
+  invoked returns the same green as one that passes. Absence of a bypass must be evidenced,
+  not assumed.

package/skills/spec-evaluator/references/dimensions/spec-conformance.md

@@ -26,16 +26,16 @@ dimensions, off by default.
 - id: SC-AC
   statement: "Every UC Step, Error Case, and (when present) Invariant/Test-Surface row for the
     use case(s) this task/feature implements is satisfied."
-  probe: cmd          # most are cmd; [ui]/[data] criteria use those probes per GATE V1.2 classification
+  probe: cmd          # most are cmd; [ui]/[data] criteria use those probes per the CONTRACT-phase classification
   evidence_required: true
   pass_rule: >
     Each criterion is drawn from usecases/UC-*.md (numbered ## Steps, ## Error Cases rows,
     ## Invariants [INV-NN] entries, ## Test Surface derived rows when present) for every UC
-    named in this task's use_case_refs (or confirmed with the user at V1.1 when no local task
-    file exists). Run each via its classified probe and PASS. Zero failing criterion.
+    named in this task's use_case_refs (or confirmed with the user at CONTRACT when no local
+    task file exists). Run each via its classified probe and PASS. Zero failing criterion.
     A stubbed/display-only implementation that satisfies a local task file's own AC wording but
     not the UC's actual behavior FAILS — the task's AC (if present) is a paraphrase read only
-    for traceability (GATE V0.2b), never the grading text itself.
+    for traceability, never the grading text itself.
   source: usecases
 
 - id: SC-DONE-WHEN

package/skills/spec-evaluator/references/dimensions/test-surface-conformance.md

@@ -21,7 +21,7 @@ requires_browser: true
 > Explicit `--dimensions ...,test-surface-conformance` always wins over the auto rule.
 
 **Why this exists.** `spec-conformance` grades the AC that were written; it does not
-*expand* them. The QA meeting (2026-06-11) located the gap: nobody systematically derives
+*expand* them. The settled division of labor locates the gap: nobody systematically derives
 the test matrix — boundary values, negative cases, error-code coverage, no-go breaches —
 that the spec already implies. The BA now derives that matrix into each UC's
 `## Test Surface` (D1 Invariants · D2 Error Cases · D3 Contract shapes · D4 No-gos,

package/skills/spec-evaluator/references/probing.md

@@ -43,7 +43,7 @@ The probe loop per [ui] criterion:
      the source file:line where the handler/wiring fails
 ```
 
-## Oracle dispatch (evaluation contract — Stage G)
+## Oracle dispatch (evaluation contract)
 
 Each criterion / Test-Surface row carries an `oracle` tag — the dispatch key that declares *how*
 this criterion is verified. **Dispatch on it to choose the probe mechanism; default to `ui` when
@@ -124,34 +124,53 @@ This is a static read; no running required. Record whether each key AC has a mat
 
 ## Integration probing (for `integration` dimension)
 
-**Finding integration test files:** Check for files matching `*.integration.spec.ts`,
-`*.e2e-spec.ts`, or a top-level `test/` directory in the package. Also inspect
-`package.json` scripts for `test:e2e`, `test:int`, or `test:integration` targets.
+The commands below are shaped for a JS/TS monorepo because that is the most common case, not
+because the dimension assumes one. Resolve the real test pattern and runner from the scope
+contract's `e2e_verification_fixtures` and the project's own test scripts; the criteria in
+`dimensions/integration.md` state the invariant each probe is collecting evidence for.
 
-**INT-1 (no mocks):** After locating integration test files for the task's feature:
+**Finding integration test files:** look for a naming convention that separates integration
+from unit tests (e.g. `*.integration.spec.ts`, `*.e2e-spec.ts`, a top-level `test/`
+directory) and inspect the project's script targets for an integration/e2e entry —
+`test:e2e`, `test:int`, `test:integration`, a tagged subset, or a separate runner config.
+Check every target the project defines: "I only ran the unit suite" is a probing error, not
+a finding.
+
+**INT-1 (no mocked data layer):** after locating the integration tests for the task's
+feature, find the project's mocking primitive and inspect **what it replaces**:
 ```bash
-grep -rn "jest\.mock\|vi\.mock" <integration-test-file>
+grep -rn "jest\.mock\|vi\.mock" <integration-test-file>   # adjust to the project's primitive
 ```
-Mocking HTTP clients, email senders, or third-party APIs is acceptable. Mocking
-`PrismaClient`, a repository class, or the database connection defeats integration testing.
-Then run the integration suite: `pnpm --filter <pkg> test:e2e` (or equivalent). Capture
-exit code and test count.
-
-**INT-2 (auth boundary):** Locate the test case exercising the unauthorized path. Inspect
-its setup: it should create a different user's JWT (or use no auth) and assert a 403 or
-empty-set response. Capture the test body and the run output as evidence.
-
-**INT-3 (RLS-JWT pattern + pooler port):**
+Mocking outbound third parties (HTTP clients, email senders, payment sandboxes) is
+acceptable. Mocking the database client, a repository class, or the persistence connection
+defeats integration testing. Then run the integration target and capture exit code and test
+count.
+
+**INT-2 (access boundary):** first confirm from `usecases/` Error Cases, `contracts/`, or the
+Non-Go list that the spec documents a caller who must not reach this operation. If it
+documents none, record N/A with that citation. Otherwise locate the test case exercising the
+unauthorized path and inspect its setup: it should present an unentitled caller (different
+tenant/user/org, lower-privilege role, or no credentials) and assert the outcome the spec
+documents. Capture the test body and the run output as evidence.
+
+**INT-3 (enforcement-path integrity):** identify the layer that actually enforces the
+boundary, then read the test setup — suite-level hooks, shared helpers, test env config — and
+confirm it traverses that layer rather than around it. What to grep for depends on the
+mechanism:
 ```bash
-# Check for set_config call in test setup or helper
-grep -rn "set_config\|request\.jwt\.claims" <test-setup-files>
+# database row-level policies: is the caller's claim set injected, and in the right scope?
+grep -rn "set_config\|jwt\.claims\|SET LOCAL" <test-setup-files>
+
+# connection mode: transaction-scoped settings can leak across pooled connections in
+# session mode, so the configured port/mode is part of the evidence
+grep -rn "DATABASE_URL\|DIRECT_URL" <test env config>
 
-# Check connection string in test env
-grep "DATABASE_URL" .env.test apps/api/.env.test
+# guard / middleware chains: does the suite build the composed app, or the handler alone?
+grep -rn "createTestingModule\|overrideGuard\|overrideProvider" <test-setup-files>
 ```
-The `DATABASE_URL` must end with `:6543/...` (transaction-mode pooler). If no `.env.test`
-exists, check `jest.config.ts` or `globalSetup` for a `DATABASE_URL` override. A missing
-`set_config` call means queries run without RLS — false-positive auth passing silently.
+A setup that connects as an administrative or unscoped principal, omits the guard layer, or
+seeds state through a back door calls the system with privileges the real caller never has —
+every access assertion above it is a false positive. Report each distinct bypass separately.
 
 ## By task variant
 - `.be` — no browser (`--browser none`). Start the API; send contract-shaped requests;

package/skills/spec-evaluator/references/report-schema.md

@@ -17,12 +17,12 @@ bug_count: [N]
 browser_mode: cli | mcp | none
 evaluator: spec-evaluator v0.1
 eval_at: [ISO date]
-linked_docs: ["[[usecases/UC-Name]]", "[[scope-summary]]"]  # + "[[tasks/TASK-NNN-slug]]" only when a local task file exists this run (V0.2b)
+linked_docs: ["[[usecases/UC-Name]]", "[[scope-summary]]"]  # + "[[tasks/TASK-NNN-slug]]" only when a local task file exists this run
 t0_citation: ~ | { scope_id: cart-creation, artifact: t0/verdicts/r2-a3.json, sha256: 1a2b3c… }
 ---
 ```
 `t0_citation` is `~` (not applicable) only when the spec folder has no scope contracts
-(pre-v0.3.0 spec). On any scoped spec it is required — GATE V0.7/V2.5 in SKILL.md — an absent
+(pre-v0.3.0 spec). On any scoped spec it is required — SKILL.md's T0-citation rule — an absent
 citation there means the report should not have been written yet.
 
 ## Body sections (in order)

package/skills/spec-evaluator/scripts/verdict-ledger.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Verdict-ledger reference implementation (audit Stage D1) — spec-evaluator's own skill-local
+// Verdict-ledger reference implementation — spec-evaluator's own skill-local
 // reference impl (ships beside SKILL.md; not invoked at runtime).
 //
 // The `spec-evaluator` skill performs verdict re-probe / confidence / flip-detection as a

package/skills/task-executor/SKILL.md

@@ -26,6 +26,7 @@ rely on (anything absent = **unknown**; never invent it):
 | `substrate.allowed` / `substrate.shared` | The ONLY globs you may write. A needed file outside them → ESCALATE, never a write (a sandbox hook blocks it anyway) |
 | `payload.decisions[]` | Adjudicated answers from prior escalations — binding precedent, apply them |
 | `payload.digested_errors[]` | `{file, line, core_message}` triples from the previous attempt's failed verification — your starting bug list |
+| `payload.trial_history[]` | Up to 8 prior attempts on this scope, oldest first, CROSSING the round boundary: `{score, status, delta, digest}`. `status: "reverted"` is a change that was tried and made things WORSE — do not re-propose it. `status: "kept"` with a still-red score is the tree you are building ON, not a failure to undo. Absent on the first attempt |
 | `payload.verify.test_cmd` | The command that verifies your work. No test_cmd → command-verifiable ACs still need *some* observable check; say what you used |
 | `payload.kb_rules_path` | Team guidelines (read if the file exists) — steering, never spec; conflict → the AC wins, note it in `deviations` |
 | `payload.constraints` | Non-Go items and freezes (e.g. `ui_layers.layer3_frozen`) |
@@ -104,28 +105,41 @@ no recorded evidence is reported `fail`, by your own hand.
 
 ---
 
-## ESCALATE protocol — the one outward port
+## ESCALATE protocol — how to stop without guessing
 
 When blocked on a decision that is not yours (design decision, spec ambiguity, substrate
 expansion): stop work on **that AC only**, keep building every AC that doesn't depend on the
-answer, and add a block to `escalates[]`:
+answer, then return `status: "escalated"` with the blocker as the **first** entry in
+`deviations[]`, in this shape (one entry per blocked decision, blockers first):
 
-```json
-{ "kind": "design-decision | spec-ambiguity | substrate-expansion",
-  "question": "one checkable question",
-  "blocked_ac": "which AC waits on this",
-  "context": "the two interpretations / the file and why it's needed" }
 ```
+ESCALATE <design-decision | spec-ambiguity | substrate-expansion> [<blocked AC>]
+<one checkable question>
+<the two interpretations, or the file you need and why>
+```
+
+`deviations[]` is the channel because there is **no `escalates[]` field** — the WorkResult
+envelope carries no structured escalation, so a question written anywhere else does not reach a
+human at all. `status: "escalated"` is what the run notices: the phase leaves its artifact
+unwritten, the orchestrator's post-condition fails, and the run stops and names the phase
+instead of looping. Your `deviations[]` text is the only record of *why*, so make it answerable
+on its own — whoever reads it will not have your context.
 
 Orchestrated (`mode: orchestrated`): never ask an ad hoc question — there is no session to
-answer it; the orchestrator adjudicates and the answer returns in the next order's
-`decisions[]`. Standalone (`mode: standalone`): you may ask the user directly (max 2
-questions) instead of escalating.
+answer it. Standalone (`mode: standalone`): you may ask the user directly (max 2 questions)
+instead of escalating.
 
 ---
 
 ## Output contract — the WorkResult
 
+**Escalation rule.** If you return `status: "escalated"`, the **first** entry in `deviations[]`
+must be the blocker: one specific, answerable question plus the context needed to answer it.
+Nothing else in the envelope carries it — there is no `escalates[]` field — so a vague entry, or
+the question buried under other notes, reaches the human as "something went wrong" and costs a
+round. Write it so someone without your context can answer it in one reply.
+
+
 Write `.shapeup/<slug>/results/<order-suffix>.json` (mirror of the order path; slug and
 suffix come from `order_id`) matching `work-result.schema.json`, and print its path:
 
@@ -142,7 +156,6 @@ suffix come from `order_id`) matching `work-result.schema.json`, and print its p
           "evidence": "pnpm --filter api test → 14/14" } ] }
   ],
   "files_touched": [ { "path": "apps/api/src/orders/create.ts", "change": "created" } ],
-  "escalates": [],
   "discoveries": [ { "marker": "+", "line": "empty-cart edge case unhandled" } ],
   "assumptions": [ "amount stored in minor units — inferred from schema" ],
   "deviations": []
@@ -167,7 +180,7 @@ orchestrator's `ingest-result.mjs` does all of that from your envelope.
 - [ ] Every interactive element built binds to a manifest `test_id` with `data-state`
 - [ ] No unused imports/symbols left behind by your changes
 - [ ] Assumptions and deviations are in the envelope, not in your head
-- [ ] Blocked ACs have an `escalates[]` block; unrelated ACs were still built
+- [ ] Blocked ACs are named in a `deviations[]` ESCALATE entry with `status: "escalated"`; unrelated ACs were still built
 - [ ] The WorkResult validates against `work-result.schema.json` and its path was printed
 
 ---