shapeup-sdlc 1.6.2

package/skills/orient/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: orient
+description: "Use this skill for Shape Up step 7 (Orient) — the builder-led reconnaissance pass that runs AFTER kick-off and BEFORE any task board exists. Triggers on: \"orient on this feature\", \"scout the codebase for this pitch\", \"where does this pitch touch the code\", \"do an orient pass\", \"recon before we plan\", \"spike the riskiest part before mapping scopes\". The tech-lead orchestrator invokes it at step 7 before delegating to ba-pitch-analyzer (Map Scopes, step 8). Use it even when the user describes \"read the code first and surface the unknowns\" without naming Orient. Also accepts a tech-lead --order dispatch."
+---
+
+# Orient — the Scout (Shape Up step 7)
+
+In Shape Up, the team that builds also **orients**: after kick-off they read the real code,
+spike the scary parts, and let reality generate **Discovered tasks** — which outnumber the
+imagined ones. This skill is that pass, made explicit. It exists because the orchestrator
+(`tech-lead`) must *delegate* orientation, and the generator (`task-executor`) can't host it:
+its first gate needs a task file, and **at Orient time no board exists yet** — the board is
+mapped *after* this pass, by `ba-pitch-analyzer` at step 8.
+
+So the Scout's whole job is to make the planner's board **reality-born instead of imagined**.
+It hands `ba` a map of where the pitch lands in real code, the findings from de-risking the
+single scariest area, and a seed list of tasks (imagined + already-discovered). Nothing more.
+
+```
+PO: shaping → bet → kick-off ──► tech-lead ──► ORIENT (you) ──► ba (Map Scopes) ──► build
+                                                  reads code, spikes, seeds
+```
+
+---
+
+## What the Scout is and is not
+
+| Does | Does NOT |
+|------|----------|
+| Read the kicked-off pitch + breadboard | Re-shape, re-bet, or question the appetite (PO already did) |
+| Trace pitch elements to real files/modules | Write production code |
+| Spike the **single** riskiest area, time-boxed | Build the scope board / tasks (that is `ba`, step 8) |
+| Seed the discovered-task list (imagined + discovered) | Keep `run-state` (tech-lead owns it) |
+| Emit raw hill **signal** (per-area unknowns) | Render the hill **report** (tech-lead renders it) |
+
+The Scout is a **pure worker** (the harness rule: stateless workers, one stateful
+orchestrator). It receives run metadata — `feature`, `spec` folder, `stack` — as **arguments**
+from `tech-lead`; it never reads or writes a shared run-state file.
+
+---
+
+## Input contract (pure worker)
+
+Orchestrated, you are invoked as `--order <path>` (a WorkOrder): `payload.pitch` (the
+kicked-off pitch path), `payload.stack` (sweep hint), and `substrate.allowed` naming your one
+write surface — the orient output dir. Anything absent = unknown: confirm at GATE O-A
+(standalone) or report it in the result's `deviations`, never guess. Standalone, the
+`--pitch/--spec/--stack` flags below carry the same fields; the output dir derives from the
+spec path (`.shapeup/<feat>/orient/`).
+
+## Output — the four artifacts (the `orient → ba` contract) + a WorkResult
+
+All four land in the orient output dir (orchestrated: the order's substrate; standalone:
+`.shapeup/<feat>/orient/`). These ARE the contract `ba` Phase 1 consumes, so `ba` does
+not re-scan the codebase. Keep them factual and link real `file:line` so the planner can trust
+them. When dispatched with an order, also write the WorkResult envelope
+(`.shapeup/<feat>/results/<order-suffix>.json`, `work-result.schema.json`): `status`,
+`artifacts[]` (the four paths), and any pitch-level gaps as `deviations[]`.
+
+| File | Purpose | Consumed by |
+|------|---------|-------------|
+| `orient/code-surface.md` | where the pitch lands in real code: modules, files, existing entities, seams | `ba` Phase 1 (ingest), Phase 2 (DDD) |
+| `orient/spike-<area>.md` | findings from de-risking the single riskiest area | `ba` Phase 1b / contracts; tech-lead L1a |
+| `orient/discovered-seed.md` | imagined + already-discovered tasks, grouped by suspected scope | `ba` Phase 6 (task gen) |
+| `orient/hill-signal.md` | per-area inventory of open unknowns (raw signal, not a report) | `tech-lead` GATE L1a hill render |
+
+---
+
+## Workflow
+
+```
+INTAKE: kicked-off pitch (+ breadboard) + codebase + args(feature, spec, stack)
+          │
+⏸ GATE O-A │  Locate & validate ──► confirm pitch path, breadboard (if any), spec target, codebase root
+          │
+Phase 1   │  Read the shape ──────► extract elements/places/slices to ground in code
+Phase 2   │  Code-surface scan ───► map each element → real file:line / module / entity
+          │                         → write orient/code-surface.md
+Phase 3   │  Risk triage ─────────► rank areas by unknowns × integration risk; pick the ONE riskiest
+          │
+⏸ GATE O-B │  Spike scope ─────────► confirm the area + question + time-box before spiking
+          │                         (no-risk path: declare SPIKE-NOT-NEEDED, skip Phase 4)
+          │
+Phase 4   │  Spike ───────────────► time-boxed investigation in real code; answer the question
+          │                         → write orient/spike-<area>.md  (or spike-not-needed.md)
+Phase 5   │  Seed discovered tasks ► imagined + discovered, grouped by suspected scope
+          │                         → write orient/discovered-seed.md
+Phase 6   │  Emit hill signal ────► per-area open-unknown inventory
+          │                         → write orient/hill-signal.md
+✅ Done    └─► 4 artifacts in .shapeup/<feat>/orient/ — hand back to tech-lead for GATE L1a
+```
+
+Under `--auto` (passed by `tech-lead` when its run level is `--auto`/`--unattended`), run
+straight through, auto-confirming O-A and O-B with sensible defaults.
+
+---
+
+## GATE O-A — Locate & validate
+
+```
+Confirm (do not guess):
+  - kicked-off pitch path (shaping.md / pitch.md)
+      Shaped signal: frontmatter status: shaped AND bet: <S1|S2|...> (or equivalent).
+      If the pitch lacks appetite AND solution boundaries → STOP and tell tech-lead:
+        "Orient runs on a kicked-off pitch, not a raw idea. Shape/bet first (PO upstream)."
+  - breadboard.md path — read it if it exists; record "no breadboard" if absent
+  - spec folder target (create orient/ if absent)
+  - codebase root
+```
+
+---
+
+## Phase 1 — Read the shape
+
+Read the pitch and breadboard (if present). Extract the concrete things to find in code:
+
+- **With breadboard**: the **places** and **affordances** (U[N]/N[N] IDs), **slices** (if B5
+  named them), named entities, third-party mentions.
+- **No breadboard**: extract the pitch's *problem statement*, *solution shape* (the key
+  verbs/nouns), and any named entities or actions. These become your elements to ground.
+
+You are listing *what to look for* — not solutions.
+
+## Phase 2 — Code-surface scan → `code-surface.md`
+
+For each element, locate where it lands in the real codebase. Bias toward breadth over depth —
+the goal is a reliable **map**, not a deep read.
+
+```
+Useful sweeps (adapt to the stack arg):
+  find . -path "*/schema*"  -o -path "*/domain*"      # existing entities / aggregates
+  find . -path "*/repository*" -o -path "*/usecase*"  # seams to extend
+  find . -path "*<feature-keyword>*"                  # prior art for this feature
+  grep -rn "<entity or affordance keyword>" <src dirs>
+```
+
+Write `code-surface.md`: one row per pitch element → `file:line` it touches (or "NEW — no
+existing home"), the seam it extends, and whether it's new vs. existing. Flag every place the
+map is uncertain — uncertainty is signal for Phase 3, not something to hide.
+
+> **Output location.** All four orient artifacts are run-trace (recon scratch), so they
+> go to the **LOCAL** root `.shapeup/<feat>/orient/` (hidden, gitignorable) — *not*
+> into the shared `--spec` dir. `<feat>` is the feature slug (parent of the `--spec`
+> deliverable dir). The bare filenames below are all relative to `.shapeup/<feat>/orient/`.
+
+## Phase 3 — Risk triage
+
+Rank candidate areas by **(open unknowns) × (integration risk)**. The riskiest is usually
+where the pitch meets an unproven seam: a third-party API, a data-shape you can't confirm from
+code, a cross-layer contract, a performance assumption. Pick the **single** highest — the
+Scout spikes one thing well, not five things shallowly. List the rest as known unknowns (they
+feed the hill signal and `ba`'s rabbit-hole handling).
+
+## GATE O-B — Spike scope
+
+```
+No-spike path: if every area has confirmed prior art and no genuine unknown (Phase 3
+  returned rank 0 risk), declare SPIKE-NOT-NEEDED. Write orient/spike-not-needed.md
+  (one paragraph: why no spike is needed + what prior art covers the riskiest seam).
+  Then skip Phase 4 and proceed to Phase 5.
+
+Spike path: if a risky area exists, confirm before spiking:
+  Area      : [the one riskiest area]
+  Question  : [the single question — phrased so the answer is checkable]
+  Time-box  : [hard cap, e.g. 30–60 min of investigation]
+  Fallback  : [what ba plans around if spike can't resolve it]
+```
+
+## Phase 4 — Spike → `spike-<area>.md`
+
+Investigate in the **real code** — read the actual library/SDK, trace the actual data shape,
+write a throwaway probe if needed. This is `shapeup /spike` technique, but build-time and
+code-grounded rather than shaped-solution-time. Answer the question or declare it
+`SPIKE-UNRESOLVED` with the fallback. Cite `file:line` and any external source. Stay inside
+the time-box; a partial answer with a clear residual unknown is a valid result.
+
+## Phase 5 — Seed discovered tasks → `discovered-seed.md`
+
+Write the task seed `ba` Phase 6 will turn into the board. Two kinds, clearly labelled:
+- **Imagined** — what you'd expect from the pitch alone.
+- **Discovered** — what the code-surface scan and spike actually surfaced (the higher-value
+  set; in Shape Up these dominate). **Every discovered task must cite `file:line` or seam.**
+  If you can't cite a real location, it belongs in Imagined, not Discovered.
+
+Group by **suspected scope** so `ba` can map scopes naturally. Do **not** assign IDs, order,
+or dependencies — that is the planner's job. You are handing over raw material, not a plan.
+
+> This is the seed for the planner's first board. The *in-build* discovered-task loop
+> (build WorkResults' discoveries[] ingested into the live ledger, reconciled by a planner
+reconcile order) is
+> a separate, later mechanism — don't conflate the two.
+
+## Phase 6 — Emit hill signal → `hill-signal.md`
+
+For each suspected scope/area, list its **open unknowns** (unresolved spike question, `⏳ TBD`
+data shape, unproven seam, ambiguous requirement). This is the raw input `tech-lead` renders
+into the Hill at GATE L1a — a scope with open unknowns sits **uphill**; one whose approach the
+spike proved sits toward the **crest**. Emit the *facts*; let `tech-lead` position the dots.
+Keep it per-area (not per-slice) — slices don't exist until `ba` maps them at step 8.
+
+---
+
+## Done — completion output
+
+When all four artifacts are written, emit this summary (to tech-lead or directly to the user
+in standalone mode):
+
+```
+✅ Orient complete — .shapeup/<feat>/orient/
+
+  Artifacts:
+    code-surface.md   — <N> pitch elements mapped; <M> NEW / <K> EXISTING seams
+    spike-<area>.md   — [RESOLVED | SPIKE-NOT-NEEDED | SPIKE-UNRESOLVED: <fallback>]
+    discovered-seed.md — <N imagined> + <M discovered> tasks seeded across <K> scopes
+    hill-signal.md    — <summary line from hill, e.g. "No uphill areas; spike at crest.">
+
+  Ready for ba (step 8):
+    Pass --orient-dir .shapeup/<feat>/orient/ to ba-pitch-analyzer.
+    ba Phase 1 skips its own codebase scan and reads code-surface.md as its authoritative map.
+```
+
+Tech-lead uses this to render the GATE L1a Hill and confirm the spike before handing to `ba`.
+
+---
+
+## Hard rules
+
+| Rule | Why |
+|------|-----|
+| Runs on a kicked-off (shaped + bet) pitch only | Shaping/betting are PO-personal, upstream of Orient |
+| Writes the four artifacts, nothing else | The Scout is a pure worker; no code, no board, no run-state, no report |
+| Spike exactly one area OR declare SPIKE-NOT-NEEDED | Depth on the scariest unknown beats shallow coverage; don't spike for its own sake |
+| Every Discovered task in the seed cites `file:line` | If no real location exists, it belongs in Imagined, not Discovered |
+| Never assign task IDs/order/deps in the seed | Mapping scopes is `ba`'s job (step 8) — the Scout hands over raw material |
+| Receives `feature`/`spec`/`stack` as args; never touches run-state | `tech-lead` is the sole run-state writer |
+| Emits hill *signal*, never a hill *report* | `tech-lead` renders progress; workers emit facts |
+
+---
+
+## Invocation
+
+```bash
+# Invoked by tech-lead at step 7 (canonical) — compile-order --operation orient --slug <feat> …
+/orient --order .shapeup/<feat>/orders/orient.json
+
+# Standalone flags (the preamble shim compiles the same envelope)
+/orient --pitch shapeup/<feat>/shaping/shaping.md --spec shapeup/<feat>/spec/ --stack "pnpm, Next 16 web :3000"
+
+# Standalone recon (no orchestrator) — still writes only the four artifacts
+/orient --pitch shapeup/<feat>/shaping/shaping.md --spec shapeup/<feat>/spec/
+
+# Auto (tech-lead passes this under --auto/--unattended): run straight through
+/orient --pitch ... --spec ... --auto
+```
+
+### Flags
+| Flag | Effect |
+|------|--------|
+| `--pitch <path>` | The kicked-off pitch (+ sibling `breadboard.md` if present) |
+| `--spec <path>` | SHARED spec deliverable dir (shapeup/<feat>/spec/); orient *artifacts* are written to the LOCAL root `.shapeup/<feat>/orient/` |
+| `--stack <hint>` | Stack hint to aim the code-surface sweeps |
+| `--auto` | Auto-confirm O-A and O-B; run straight through |

package/skills/qa-edge-hunter/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: qa-edge-hunter
+description: "Use this skill for the post-PASS exploratory QA pass — Shape Up's \"QA is for the edges\", made explicit for the harness. Triggers on: \"hunt edge cases\", \"QA pass on this feature\", \"exploratory test the running app\", \"edge hunt before ship\", \"run qa-edge-hunter\", \"the evaluator passed — what did it miss?\". tech-lead invokes it after the run's first PASS at GATE L3, before SHIP; it also runs standalone given a spec folder, a PASS EVAL report, and a running app, or on a tech-lead --order dispatch. It charters edges OUTSIDE what the evaluator probed and hunts them through six fixed lenses. NOT for checking AC (spec-evaluator), deriving test cases (ba), or fixing bugs (task-executor)."
+---
+
+# QA Edge Hunter — the post-PASS edge pass (v1.1)
+
+Shape Up, Ch. 13: QA comes in **toward the end**, hunts **edge cases outside the core**,
+and its issues are **nice-to-haves by default** that the team triages. This skill is that
+role for the harness. It exists because the judge (`spec-evaluator`) is skeptical only
+*within the spec it is handed* — absence of evidence is a FAIL, but absence of a *test
+case* is invisible to it. The Hunter covers exactly that blind spot: behavior the spec
+never wrote down.
+
+```
+tech-lead: ... GATE L2 → EVAL → GATE L3 PASS ──► QA EDGE HUNT (you) ──► SHIP S.0 triage → L4
+                                                  charters · hunts · ~ findings → ledger
+            GATE L3 FAIL → fix round (never reaches you — conformance first, edges after)
+```
+
+**Division of labor (settled at the QA meeting, 2026-06-11):**
+
+| Tier | Owner | When |
+|---|---|---|
+| Derivable tests (boundaries, error codes, no-go breaches the spec implies) | `ba` `## Test Surface` + evaluator `test-surface-conformance` | spec time / every EVAL |
+| **Exploratory edges (this skill)** | `/qa-edge-hunter` | once, post-first-PASS |
+
+---
+
+## What the Hunter is and is not
+
+| Does | Does NOT |
+|------|----------|
+| Read EVAL-*.md to map covered territory — then hunt OUTSIDE it | Re-probe anything the evaluator already graded |
+| Charter edges via six fixed lenses, minus covered territory | Author or extend `## Test Surface` (that is the planner's retrofit-surface operation) |
+| Execute charters on the **running app** (session-based exploratory) | Read-only speculate from code ("this looks racy") — every finding needs a live repro |
+| Return each finding in the WorkResult's `discoveries[]`, **always `~`** | Promote `~` → must-have (PO/TL at SHIP S.0; severity-hint is advice, not a decision) |
+| Emit `qa/hunt-report.md` — charters run/cut, findings by lens | Render a verdict, score, or PASS/FAIL of any kind |
+| `--recheck`: re-probe ONLY items promoted+fixed after triage | Run a second full hunt in the same cycle; fix code; touch task files; keep run-state |
+
+Pure worker (harness rule: stateless workers, one stateful orchestrator). Its WorkOrder
+carries `payload.feature`, `payload.spec_folder`, `payload.eval_report`, `payload.app_url`,
+`payload.kb_rules_path` (+ read-only ledger path for covered-territory context); its write surface is
+`.shapeup/<feature>/qa/**` only. The Hunter never touches the discovery ledger itself —
+ingest appends its `discoveries[]` under a `## Discovered` section, preserving single-writer
+mechanically.
+
+---
+
+## Workflow
+
+```
+⏸ GATE Q0 │ Preflight ────► hard: app running? EVAL verdict PASS? ledger exists?
+          │                 soft: Test Surface present? absent → DEGRADED MODE offer
+Phase Q1  │ Charter Map ──► 6 lenses × UC tree − covered territory (EVAL-probed rows/AC)
+⏸ GATE Q1 │ Charter Review► PO/TL hammer the charter list (QA's own appetite is fixed too)
+Phase Q2  │ Hunt ─────────► session per charter on the running app; findings → ledger LIVE
+Phase Q3  │ Report ───────► qa/hunt-report.md — no score, no verdict
+```
+
+---
+
+## GATE Q0 — Preflight
+
+```
+HARD (any miss → STOP, report which):
+  ✅ app reachable at the given URL (one real request, not a ping)
+  ✅ EVAL-FEATURE-<slug>.md exists with verdict: PASS
+  ✅ if discovery/ledger.md exists: ledger.feature == <feature> (read-only context check —
+     a missing ledger is fine; ingest creates it when your findings land)
+SOFT:
+  ⚠️ any usecases/UC-*.md has `## Test Surface`?
+     NO → DEGRADED MODE:
+       "Test Surface absent — derivable cases (boundaries, error codes, no-go breaches)
+        were never systematically probed. Lenses ① and ⑤ will widen to compensate
+        (charters tagged [derivable-fallback]). Better: run
+        a ba-pitch-analyzer retrofit-surface order + one evaluator pass first, then hunt
+        with a narrower charter. Continue degraded? [y/n]"
+     Degraded is first-class, not an error — for old specs, a degraded hunt beats no hunt.
+Questions: max 2. The standing one: "Any areas OUT OF BOUNDS for exploratory testing?
+(e.g. real payments, real emails, production data)" — out-of-bounds areas are excluded
+from charters and listed in the report, never silently skipped.
+```
+
+**Output:**
+```
+⏸ GATE Q0 — Preflight
+App       : [url] ✅ reachable
+EVAL      : EVAL-FEATURE-[slug].md — PASS (dims: [...])
+Ledger    : [✅ feature match | absent — ingest will create it]
+Surface   : [present | ABSENT → degraded mode]
+Out-of-bounds? (max 2 questions) …
+```
+
+---
+
+## Phase Q1 — Charter Map
+
+A **charter** is a hunting ground + a mission — NOT a test case (test cases are the
+derivable tier; writing them here would re-do `ba`'s job badly). Generate charters by
+crossing the UC tree with the **six fixed lenses**, then subtract covered territory.
+
+| Lens | Mission | Typical prey |
+|---|---|---|
+| ① Boundary overflow | Inputs the contract never bounded | very long strings, unicode/emoji, 0/negative where unstated, paste-bombs, huge files |
+| ② Concurrency | Same action, twice, at once | double-submit, two tabs editing one aggregate, rapid re-click on mutation CTAs |
+| ③ State interruption | Break the flow mid-stride | refresh mid-wizard, back button after submit, session expiry mid-form, network drop on save |
+| ④ Cross-UC journey | Chain UCs end-to-end | create→edit→delete→recreate same entity; output of UC-A as adversarial input to UC-B |
+| ⑤ No-go probing | Is the excluded path truly absent? | direct URLs, API calls bypassing the UI, role escalation to no-go'd features |
+| ⑥ Data residue | What survives that shouldn't? | deleted data via old links/exports, prior-session state bleeding, cache after logout |
+
+The six lenses are **fixed** (simplicity as a hard constraint) — scoping happens by
+cutting charters at GATE Q1, not by configuring lenses.
+
+**Charter quality** — before generating, internalize the target altitude:
+- Good: "What happens to the order record if the user refreshes the page after clicking
+  Confirm but before the server responds?" → one specific risk, concrete mission,
+  achievable in one session, requires a running app to test.
+- Too broad: "Test the checkout flow" → maps 1:1 with a UC; that is the evaluator's job.
+- Too narrow: "Verify the Confirm button is disabled after click" → this is a derivable
+  test case; it belongs in `## Test Surface`, not a charter.
+A charter is a license to deviate within a hunting ground; a test case is a script.
+
+```
+Q1.0  Read team guidelines: the file at `payload.kb_rules_path` (if present; absent field = none).
+      `/coach`-distilled edge classes that kept biting past features (e.g. "session-expiry
+      mid-form keeps surfacing"). Use them to PRIORITIZE charters within the six fixed lenses —
+      never to add a seventh lens or skip covered-territory subtraction. Absent = none recorded.
+Q1.1  Parse EVAL-*.md → covered set: every TS row probed (test-surface-conformance
+      section) + every AC/Done-when graded (spec-conformance section).
+Q1.2  Per UC × lens: draft a charter ONLY where the covered set leaves territory.
+      Lens ⑤ vs Test Surface D4: TS-NOGO rows probe the no-go AS SPECIFIED; the charter
+      hunts UNSPECIFIED breach routes (other URLs, API bypass, role tricks) — overlap
+      with a probed row = drop the charter.
+Q1.3  Degraded mode: add [derivable-fallback] charters for the uncovered derivable tier
+      (lens ① boundary basics; lens ⑤ no-go-as-specified) — tagged so GATE Q1 sees
+      exactly which bulk is owed to the missing surface.
+Q1.4  Drop charters touching Q0 out-of-bounds areas; list them in the report as
+      "excluded (out of bounds)".
+Q1.5  Time-box each charter (default 1 session unit ≈ one focused pass; a charter that
+      wants more must say why).
+```
+
+---
+
+## ⏸ GATE Q1 — Charter Review
+
+The scope hammer applied to QA itself — the Hunter's appetite is as fixed as everyone
+else's.
+
+```
+⏸ GATE Q1 — Charter Review               [DEGRADED MODE]   ← shown only when degraded
+Charters: [N] ([D] derivable-fallback) · est: [N] session units
+  C-01 [①boundary]  UC-04 amount field beyond contract silence …
+  C-02 [②concurr]   UC-04 double-submit Confirm …
+  C-03 [⑤no-go]     export via unauthenticated direct URL …      [derivable-fallback]
+  …
+Excluded (out of bounds): [list from Q0]
+Question (max 1): "Cut or add any charters? (ids / add <desc> / none)"
+```
+
+Cut charters appear in the report under "Hammered out (not hunted)" — visible cuts, never
+silent ones.
+
+---
+
+## Phase Q2 — Hunt
+
+Session-based exploratory testing per approved charter, on the running app.
+
+```
+Per charter:
+  H.1  Execute the mission within its time box. Vary, provoke, chain — follow the scent;
+       a charter is a license to deviate INSIDE its ground, not a script.
+  H.2  Suspected finding → reproduce it (≥1 clean repro) before recording. No repro →
+       log in session notes as "unconfirmed observation", NOT a finding.
+  H.3  Confirmed → record it IMMEDIATELY (in the growing WorkResult, not batched to the end
+       of the hunt — a crashed session must not lose confirmed findings):
+
+       { "marker": "~",
+         "lens": "②concurrency",
+         "line": "[QA-NNN] [UC-04] Double-click \"Confirm\" creates 2 orders",
+         "repro": "<numbered steps, shortest path>",
+         "severity_hint": "data-integrity | boundary-breach | ux-degradation | cosmetic",
+         "test_gap": "unit | integration | exploratory-only" }
+
+       Always `~` — ingest appends these to the discovery ledger verbatim; you never open
+       the ledger file. severity_hint is the Hunter's advice to triage — the promotion
+       decision is PO/TL's at SHIP S.0, never made here.
+       test_gap is advisory for reconciliation: unit = a targeted unit test would have
+       caught this; integration = a cross-layer test would; exploratory-only = only
+       discoverable through live session dynamics.
+  H.4  A finding that contradicts a PASSED criterion (the evaluator graded it PASS, the
+       hunt shows otherwise) → set `"contradicts": "<EVAL criterion id>"` on the entry.
+       Do NOT edit EVAL-*.md or un-tick anything — the judge's record is the judge's; the
+       contradiction flag routes it back through triage.
+  H.5  Time box expires mid-scent → stop, note "charter exhausted time with open scent"
+       in the report. The circuit breaker applies to hunting too.
+```
+
+### Lens-specific hunting techniques
+
+Use these as your toolbox when executing a charter. The goal is to provoke the app
+in ways a spec author wouldn't think to write down.
+
+**① Boundary overflow** — things the contract never bounded
+- Strings: paste 10 KB of text, emoji sequences (🏳️‍🌈 multi-codepoint), RTL Unicode (؀؁),
+  null bytes (`\x00` via DevTools console injection), leading/trailing whitespace
+- Numbers: try -1, 0, 2147483647 (MAX_INT), 2147483648 (MAX_INT+1), floats where
+  integers are expected, strings that look like numbers ("1e9", "Infinity")
+- Files: 0-byte file, file with wrong extension but correct MIME type, size exactly at
+  the stated limit and size+1 byte above it
+- API: send the field missing entirely vs. `null` vs. `""` — three different cases even
+  if the UI treats them the same
+
+**② Concurrency** — same action, twice, at once
+- Open two tabs or two browsers sharing the same session; navigate both to the same
+  mutation form; submit within milliseconds of each other
+- Rapid double-click on a mutation CTA: check DevTools → Network for duplicate POSTs
+- Optimistic UI: click Save, navigate away immediately before the response arrives;
+  return — was state lost, duplicated, or correctly reconciled?
+- Two different roles editing the same aggregate simultaneously — last-write-wins vs.
+  conflict detection
+
+**③ State interruption** — break the flow mid-stride
+- Browser Back after submitting step N of a multi-step wizard; then Forward again —
+  is unsaved state preserved, lost, or doubled?
+- Refresh immediately after clicking Submit (before the response) — race between
+  browser reload and server confirmation
+- Network drop mid-save: DevTools → Network → Offline → toggle back; does the app
+  retry, error gracefully, or show stale data?
+- Session expiry mid-form: delete the session cookie (DevTools → Application →
+  Cookies → Delete) then attempt to submit — graceful redirect or silent failure?
+- Tab sleep: leave the tab idle for 10–15 minutes, return, and try a mutation
+
+**④ Cross-UC journey** — chain UCs end-to-end
+- Create → Edit → Delete → Re-create the same entity with the same name/ID — does
+  the second Create fail with an ID collision, ghost the deleted record, or succeed?
+- Use the output of UC-A as adversarial input to UC-B: if UC-A allows a 500-char name,
+  does UC-B's display truncate, wrap, or break layout?
+- Partial completion of UC-A → switch to UC-B → return to UC-A — is the partial state
+  saved, cleared, or corrupted?
+
+**⑤ No-go probing** — is the excluded path truly absent?
+- Direct URL: type a protected route into the address bar while unauthenticated or as a
+  lower-privilege role
+- API replay: in DevTools → Network, copy a privileged request as cURL, strip the auth
+  cookie, replay — does the server reject it?
+- DOM enable: find a disabled/hidden UI element, `element.disabled = false` or
+  `element.style.display = 'block'` in the console, submit — does the server validate
+  server-side?
+- Path traversal in URL params (`../`, `%2F..`) for file/export endpoints
+
+**⑥ Data residue** — what survives that shouldn't?
+- Delete an entity, then navigate to its detail URL via browser history — 404, redirect,
+  or stale cached data?
+- Log out, log back in (same browser, same session storage) — does the new session show
+  any leftover state from the prior session?
+- DevTools → Application → Cache Storage / Local Storage / IndexedDB after logout —
+  is sensitive data cleared?
+- Re-download a previously generated export URL after the source data was deleted —
+  does the export still serve the old data?
+
+---
+
+## Phase Q3 — Report + WorkResult
+
+Write `.shapeup/<feature>/qa/hunt-report.md` (your substrate) and, when dispatched with
+an order, the WorkResult envelope `.shapeup/<feature>/results/<order-suffix>.json`:
+`status: done`, `discoveries[]` (every confirmed finding from H.3), `artifacts:
+["qa/hunt-report.md"]`. The report:
+
+```markdown
+# Hunt Report — [feature] (round [r], [date])
+mode: [full | degraded | recheck]
+charters: [run]/[approved] · session units spent: [n]
+out of bounds (excluded): […]
+hammered out at GATE Q1 (not hunted): […]
+
+## Findings by lens
+| Lens | Hunted | Findings | Of which contradicts-EVAL |
+|---|---|---|---|
+| ① Boundary | C-01, C-05 | 2 | 0 |
+| … | | | |
+→ details live in .shapeup/<feature>/discovery/ledger.md ## QA Edge Findings (round [r])
+
+## Shaping-quality signal (advisory, for the PO — next cycle's input)
+- lens ⑤ findings ≈ No-gos written loosely (breach routes left open)
+- lens ④ findings ≈ UC decomposition cut too disjointly (journeys fall in the seams)
+- lens ① in degraded mode ≈ owed to the missing Test Surface, not to shaping
+
+## Session notes
+[per charter: what was tried, unconfirmed observations, open scents]
+```
+
+No verdict line exists in this file by design. The Hunter's last words:
+`✅ hunt complete — [N] findings (all ~) → ledger · triage at SHIP S.0 / GATE L4.`
+
+---
+
+## `--recheck` mode (after triage promoted + fixed items)
+
+```
+Input: the promoted finding ids (from tech-lead) + the fix round's PASS EVAL report.
+Q0   : hard checks only (app up, new EVAL PASS); no soft check, no charter map.
+Hunt : re-run EXACTLY the recorded repro of each promoted finding — nothing else.
+        fixed   → discoveries[] entry `{ "marker": "~", "line": "[QA-NNN] ✦ fixed r[N], verified" }`
+                  (ingest annotates the ledger — annotate, never delete; the ledger is history)
+        not fixed → `{ "marker": "~", "line": "[QA-NNN] ✦ NOT fixed r[N]", "repro": "<fresh evidence>" }`
+                  back to triage.
+Report: append a `## Recheck (round [r])` section to .shapeup/<feature>/qa/hunt-report.md.
+NEVER a second full hunt in the same cycle — new edges found while rechecking are
+recorded `~` like any finding and wait for triage; they don't restart the loop.
+```
+
+---
+
+## Invocation
+
+```bash
+# Orchestrated (how tech-lead calls it after first PASS) — the canonical form:
+#   compile-order --operation hunt --slug checkout-vnpay --worker qa-edge-hunter \
+#     --payload '{"eval_report": "…/EVAL-FEATURE-checkout-vnpay.md", "app_url": "http://localhost:3000"}'
+/qa-edge-hunter --order .shapeup/checkout-vnpay/orders/hunt.json
+
+# Standalone flags (the preamble shim compiles the same envelope)
+/qa-edge-hunter --feature checkout-vnpay --spec shapeup/checkout-vnpay/spec/ \
+    --eval .shapeup/checkout-vnpay/evaluation/EVAL-FEATURE-checkout-vnpay.md \
+    --ledger .shapeup/checkout-vnpay/discovery/ledger.md --app http://localhost:3000
+
+# Standalone (same arguments, human-invoked)
+/qa-edge-hunter --feature checkout-vnpay --spec shapeup/checkout-vnpay/spec/ --app http://localhost:3000
+# (--eval/--ledger default to the conventional paths under the LOCAL root .shapeup/<feature>/)
+
+# Recheck after triage promoted + fixed findings
+/qa-edge-hunter --recheck QA-001,QA-004 --feature checkout-vnpay --spec ... --app ...
+
+# Escape hatches
+--auto            # skip GATE Q1 pause (charter list logged, not reviewed) — Q0 hard
+                  # checks and the out-of-bounds question are NEVER skipped
+--lenses-note     # there is deliberately NO --lenses flag: the 6 lenses are fixed;
+                  # narrow by cutting charters at GATE Q1 (or --auto + report)
+```
+
+### Progress Markers
+```
+⏸ GATE Q0   Preflight (hard + soft checks, out-of-bounds question)
+▶ Phase Q1  Charter Map        ⏸ GATE Q1 Charter Review
+▶ Phase Q2  Hunt — C-01 ✅ C-02 🔍 …   (findings stream to ledger live)
+▶ Phase Q3  Report
+✅ hunt complete — [N] findings (all ~) → ledger · triage at SHIP S.0 / GATE L4
+```
+
+---
+
+## Hard rules (the never-list)
+
+1. **Never a verdict.** The run's verdict is the evaluator's PASS. One judge.
+2. **Never promote.** Every finding is born `~`. severity-hint advises; PO/TL decide.
+3. **Never fix.** Read-only on code; execute-only on the app; write-only to
+   qa/hunt-report.md + its own WorkResult (findings return as data; ingest owns the ledger).
+4. **Never block ship.** A hunt with 40 findings and a hunt with 0 both end the same way:
+   report, then triage at L4. The circuit breaker outranks the Hunter.
+5. **Never re-probe covered territory.** EVAL-*.md territory is subtracted at Q1; an
+   exception requires a `contradicts:` suspicion arising mid-hunt, not curiosity.
+6. **Never run on FAIL.** Conformance first; edges after.
+7. **Never invent severity from code reading.** Every finding has a live repro on the
+   running app.
+8. **Never gate on Test Surface.** Its absence degrades the hunt; it never blocks it.