shapeup-sdlc 1.7.0 → 3.0.1

package/skills/tech-lead/references/gates.md

@@ -12,7 +12,7 @@ lane emits them verbatim, and on the scoped lane `shapeup-run.js` returns the `b
 | lane | BUILD → GATE L2 → EVAL is | read |
 |---|---|---|
 | a spec with committed `scopes/*.md` (the common case) | **code** — `skills/tech-lead/workflows/shapeup-run.js`'s round loop | that script's comments |
-| `--tiny`, or a spec with no scope contracts yet | **prose**, unchanged and non-regression | `references/round-protocol.md` (`:11-22` states the same split) |
+| `--tiny`, or a spec with no scope contracts yet | **prose**, unchanged and non-regression | `references/protocol.md` (`:11-22` states the same split) |
 
 Order matches the run: GATE L0 → ORIENT → GATE L1a → ANALYZE → WIRE/L1a.5 → MAP SCOPES →
 GATE L1b → (BUILD → GATE L2 → EVAL — see the table above) → GATE L3 → SHIP → GATE L4.
@@ -55,7 +55,7 @@ Collect (explicit — never inferred):
   L0.3  lens: lite | standard | cross-context   (passed to planner at step 8)
   L0.4  stack hint (e.g. "pnpm, Next 16 web :3000") — aims orient's code-surface sweeps + run commands
   L0.5  eval dimensions: default [spec-conformance]; only add if user asks. An added dimension
-        must reach `init-run.mjs --dimensions <a,b>` — it is recorded in the ledger's
+        must reach `harness init run --dimensions <a,b>` — it is recorded in the ledger's
         `eval_dimensions:` line and every EVAL order is compiled from there, so a set agreed
         in conversation and not passed to the flag grades nothing. Shipped ids:
         spec-conformance, tdd-surface, integration, completeness, test-surface-conformance
@@ -74,7 +74,7 @@ Collect (explicit — never inferred):
           .claude/settings.json (team defaults, committed)  →  skill-shipped defaults
         Env knobs read at this layer: SHAPEUP_ORCH_MODEL, SHAPEUP_EXEC_MODEL,
         SHAPEUP_EVAL_MODEL, SHAPEUP_QA_MODEL, SHAPEUP_ATTEMPT_BUDGET (default 5),
-        SHAPEUP_DIGESTER_MODEL (default "script" — aegis-digest.mjs's regex pass; falls
+        SHAPEUP_DIGESTER_MODEL (default "script" — harness probe digest's regex pass; falls
         back to a Sonnet dispatch only when the digester reports unrecognized log formats).
         A requested model unavailable on the member's plan → degrade to the next tier down,
         record the degrade in the ledger (R2 — invariants are code paths, so adherence
@@ -92,6 +92,27 @@ Collect (explicit — never inferred):
         attempts. Set per scope (`no_progress_k` on the contract) or per run in the payload.
 ```
 
+**L0.9b — the launch record.** Every switch the operator typed becomes a `RunArgs` field, or it
+does nothing at all: the workflow cannot read a config file and cannot ask a follow-up, so a flag
+that stops at the skill boundary was accepted and ignored. That is not hypothetical — `--no-qa` was
+documented in seven places across the shipped set and inert in all of them, because no line of this
+protocol ever put `noQa` into the record.
+
+| Flag | `RunArgs` field |
+|---|---|
+| `--no-eval` | `noEval: true` |
+| `--no-qa` | `noQa: true` |
+| `--parallel-scopes N` | `maxParallelScopes: N` — how many scopes build at once (default 4; `1` = sequential) |
+| `--adversarial-verify` | `adversarialVerify: true` |
+| `--rounds N` / `--attempts N` / `--wall-clock-budget S` | `budgets.{maxRounds,attemptBudget,wallClockS}` |
+| `--gate-answers <set>` | `answers` |
+| `--orch-model/--exec-model/--eval-model/--qa-model` | `models.{…}` (L0.8) |
+
+The assembled object is written to `.shapeup/<slug>/run-args.json` before the launch, fresh on every
+launch and relaunch. It is the only artifact that records what a run was configured with; the ship
+report, a resumed session and any later measurement all read it, and none of them can recover a
+value that only ever existed as an argument.
+
 **L0.0 — intake precondition (before any other L0 collection):**
 ```
 resolve intake from, in order:
@@ -127,7 +148,7 @@ The Shape Up Building phase opens with **Orient, not planning**: the team reads
 and spikes the scary parts *before* any board exists, so the board comes out reality-born.
 
 ```
-Invoke via Agent (model: exec — see references/delegation.md "Invocation mechanism"):
+Invoke via Agent (model: exec — see references/protocol.md "Invocation mechanism"):
         Skill(shapeup-sdlc-plugin:orient) --pitch <intake> --spec <path> --stack "<hint>" [--auto]
 Owns:   its own GATE O-A/O-B; runs straight through under --auto.
 Writes: .shapeup/<slug>/orient/ → code-surface.md, spike-<area>.md, discovered-seed.md, hill-signal.md.
@@ -144,7 +165,7 @@ re-scanning the codebase. Pass `--auto` only when the run level is `--auto`/`--u
 committing to a scope map. This is the first Hill read (area-level — slices don't exist yet).
 
 ```
-Read .shapeup/<slug>/orient/. Render the 🗻 Hill from hill-signal.md (see ledger-schema.md "Hill report"):
+Read .shapeup/<slug>/orient/. Render the 🗻 Hill from hill-signal.md (see protocol.md "Hill report"):
   - each suspected area → uphill (open unknowns) | crest (approach proven by the spike) | downhill
 Print: the code-surface headline (where it lands), the spiked area + result, the riskiest
        open unknowns going into mapping.
@@ -170,11 +191,11 @@ Do NOT enter MAP SCOPES until Orient is accepted.
    ⟐ PRECONDITION: MAP SCOPES step 1 (ANALYZE) has already run and usecases/ is
    populated. WIRE writes one entry per use case, so dispatching it against an empty spec folder
    is an escalation, not a wiring map — and a phase that writes no artifact is re-dispatched on
-   every relaunch. Verify: node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/resume-state.mjs"
+   every relaunch. Verify: node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe resume
    --slug <slug> --require analyze (exit 0 = the spec tree is there; exit 6 = do not dispatch WIRE).
    Post-check the same way after the dispatch: --require wire.
    requirements.md registry (atomic REQ clauses, frozen ids).
-4. trace-lint — node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/trace-lint.mjs" --slug <slug>. ADVISORY at L1b:
+4. trace-lint — node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" verify trace --slug <slug>. ADVISORY at L1b:
    covers-closure (every covered REQ named by ≥1 AC's covers:) + reachability (every UC engine
    reaches entry_point). Promote to --gate only once covers: is populated.
 ```
@@ -189,7 +210,7 @@ against the seams WIRE declared. Sequence: ORIENT → L1a → **ANALYZE** → **
 **MAP SCOPES** → L1b.
 
 ```
-Two orders, two workers, one step (both model: exec — see references/delegation.md):
+Two orders, two workers, one step (both model: exec — see references/protocol.md):
 1. ANALYZE + BOARD — compile-order --operation analyze --slug <slug> --worker ba-pitch-analyzer
      --payload '{"pitch": "<path>", "lens": "<lens>", "orient_dir": ".shapeup/<slug>/orient/"}'
    dispatch: Skill(shapeup-sdlc-plugin:ba-pitch-analyzer) --order <path>. The order hands it
@@ -201,7 +222,7 @@ Two orders, two workers, one step (both model: exec — see references/delegatio
 2. MAP SCOPES — compile-order --operation map-scopes --slug <slug> --worker scope-architect
    dispatch: Skill(shapeup-sdlc-plugin:scope-architect) --order <path>. Sole writer of the
    committed scopes/<scope-id>.md contracts (import-graph slicing, substrate whitelists,
-   affordance manifest, fixtures, PA1/PA2 — mechanically linted by spec-lint.mjs).
+   affordance manifest, fixtures, PA1/PA2 — mechanically linted by harness verify spec).
 Record in ledger: planner duration + task count + scope count.
 ```
 Faithful note: keep the planner ambitious on scope but high-level on tech — do not push it
@@ -254,13 +275,24 @@ No scope contracts (pre-v0.3.0, unchanged from v0.2.6):
 Substrate-disjointness assertion (only when
 shapeup/<slug>/scopes/*.md exist — scope-architect's lint pass already ran;
 this is the orchestrator's own re-confirmation before committing to a build sequence):
-  - Run `node "${CLAUDE_PLUGIN_ROOT}/skills/ba-pitch-analyzer/scripts/spec-lint.mjs" --slug <slug>`: DISJOINT (a file in two
+  - Run `node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" verify spec --slug <slug>`: DISJOINT (a file in two
     scopes' `allowed_file_substrate` without BOTH declaring it `shared_substrate` — PA3
-    waiting to happen), PA1 (directory-aligned scope), PA2 (size cap). Any red → HARD STOP,
-    past a 🔴 at the architect's own checkpoint.
+    waiting to happen), PA1 (directory-aligned scope), PA2 (size cap), SCOPE-ANCHOR (a scope
+    naming no committed use case, or one that does not resolve), TIER-DIRECTION (a committed
+    contract naming LOCAL task ids), SCOPE-DEPS (a build-order id naming a scope that is not
+    in this run). Any red → HARD STOP, past a 🔴 at the architect's own checkpoint.
   - Lock the build SEQUENCE riskiest-first: order scopes by open-unknowns count (from
     hill/<scope-id>.yml if present, else the orient hill signal), not by file count or
     alphabetical — Shape Up's "solve in the right sequence" (step 10).
+    DEPENDENCIES CONSTRAIN THAT ORDER, and each contract declares its own: scope A follows scope
+    B when A names B in `depends_on`. The order lives in the same committed tier as the contracts
+    it orders, so it survives a clone. Risk orders the scopes; the dependencies decide when each one is
+    RELEASED — a scope starts as soon as the scopes it consumes have settled, not when its whole
+    level has, so a scope may well start while a sibling is still building. A scope that consumes
+    the others' output (an entry point wiring up command modules) therefore cannot be scheduled
+    alongside them however low its unknowns count. It fails open: a contract declaring no
+    `depends_on`, or naming a scope that is not in this run, falls back to releasing a level at a
+    time, and then to no constraint at all (spec-lint SCOPE-DEPS reports the dangling id).
 
 Ask (max 2): scope cuts? lens correct? any SPIKE to resolve before build?
   Scope-hammer framing: reference the appetite from the pitch
@@ -295,14 +327,14 @@ Under `--interactive` / `--auto`, the hook warns if the board is not truly green
 Render the 🗻 Hill report (slice-level) — NOT a task count. Scope contracts present → read
   committed hill/<scope-id>.yml shards (mechanical phases from GATE L2, never authored). No contracts →
   fall back to the board + open-unknowns heuristic (uphill/crest/downhill/done). See
-  references/ledger-schema.md "Hill report". Roadmap rule unchanged either way: progress is
+  references/protocol.md "Hill report". Roadmap rule unchanged either way: progress is
   reported by hill position, never by "N/M tasks done".
 
 Read EVAL-FEATURE-<slug>.md verdict.
 
 PASS:
   → first PASS of the run AND not --no-qa:
-      delegate ▶ QA EDGE HUNT → Agent (model: qa — see references/delegation.md
+      delegate ▶ QA EDGE HUNT → Agent (model: qa — see references/protocol.md
       "Invocation mechanism"): Skill(shapeup-sdlc-plugin:qa-edge-hunter) (pure worker; see
       round-protocol "QA edge hunt"). Args: spec folder, EVAL report path, ledger path, app URL.
       Its GATE Q0/Q1 pauses surface here. Output: `~` findings → .shapeup/<slug>/discovery/ledger.md
@@ -338,7 +370,7 @@ yet, report at task-group level and note the fallback in the ledger.
 
 ```
 S.0  GATE H — delegate to scope-hammer (this IS Shape Up's "Decide When to Stop", step 11):
-     Invoke via Agent (model: exec — see references/delegation.md "Invocation mechanism"):
+     Invoke via Agent (model: exec — see references/protocol.md "Invocation mechanism"):
        Skill(shapeup-sdlc-plugin:scope-hammer) --slug <slug> --baseline <shaping/baseline.md if present>
              [--breaker outer]   when round_budget hit 0 with scopes still open
              [--breaker inner --scope <id>]   once per queued hammer proposal (attempt_budget
@@ -380,7 +412,7 @@ S.6  Harvest one signal row → append to `.shapeup/metrics/<machine-id>.jsonl`
      (LOCAL root, gitignored since ADR-0001 — a committed shard keyed on a hostname only
      grows and publishes a machine name; sharded per machine so shards can be pooled
      deliberately without colliding on one filename. The read plane is
-     `stats.mjs`, or `cat .shapeup/metrics/*.jsonl`).
+     `harness probe stats`, or `cat .shapeup/metrics/*.jsonl`).
      Copy fields that ALREADY exist as structured output (run-state, final EVAL report,
      discovery ledger, qa/hunt-report, breadboard B5). Two hard rules:
        1. Harvest only fields that already exist at ship time — never evaluate something new.
@@ -388,16 +420,35 @@ S.6  Harvest one signal row → append to `.shapeup/metrics/<machine-id>.jsonl`
           a second judge behind spec-evaluator). The eval suite interprets; harvest records.
      `final_audit_score` is COPIED from the EVAL report, never re-graded.
      ALSO copy two run-quality measurements, both produced by scripts at zero model tokens:
-       node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/stats.mjs" --ratchet --slug <slug>
+       node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe stats --ratchet --slug <slug>
          → `ratchet`: {trials, scopes_multi_trial, improvement_rate, monotone_rate,
                        sawtooth_count, mean_trials_to_green}
-       node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/stats.mjs" --hooks
+       node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe stats --hooks
          → `hooks`: {evaluations, denials, errors, per_hook}
      Harvest them HERE or lose them: both read per-run working ledgers (t0/trials.jsonl,
      decisions.jsonl) that the next run's bookkeeping supersedes, so a number left there
      answers its question exactly once. The metrics shard is the one record that
      accumulates across runs — and neither measurement is meaningful from a single run.
-     → full field list + row template: references/ledger-schema.md "Harvest row".
+     ALSO copy `run_id` from `receipt.json`. It is the row's only link to the run trace
+     that produced it: every other field here is a count, and `feature_slug` groups runs
+     TOGETHER rather than apart. It is what joins this row to the S.7 export.
+     → full field list + row template: references/protocol.md "Harvest row".
+S.7  Export the run's records → one keyed dataset, before the trace is superseded.
+       node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" report export --slug <slug>
+     Same argument as S.6, applied to the records the harvest row does NOT carry: orders,
+     results, T0 verdicts, trial rows, criterion verdicts and this run's hook decisions all
+     live in the LOCAL tier, which is regenerable and gets wiped.
+     The export freezes them as fact tables under `.shapeup/exports/<run_id>/` (JSONL, one
+     object per line), keyed by run id so a second run of the same feature is a second
+     dataset rather than an overwrite. `--out <dir>` sends it somewhere durable instead.
+     It is READ-ONLY: it writes nothing into the trace, so it may be re-run at any time.
+     NOT COST/WALL-CLOCK. This harness carries no run-economics record — the design once
+     called for one derived from a per-agent-call journal, but nothing in the pipeline ever
+     wrote that journal, so the derivation and its reporting command were removed rather than
+     left presenting nulls as measurements. Even a real cost record would not belong in the
+     harvest row's schema either way — that row's contract rejects clock fields on purpose
+     (see protocol.md "Rejected fields"), because a signal feed that carried a duration would
+     become a velocity feed on the next person who read it.
 ```
 
 ---
@@ -414,7 +465,7 @@ Ledger    : harness-run.md
 ```
 Question (max 1): "Anything to record before I close the run? (y/n) or provide feedback for the next sprint."
 On confirm:
-- If the PO provides substantive feedback (not just 'y' or empty) → automatically delegate via Agent (model: exec — see references/delegation.md "Invocation mechanism"): Skill(shapeup-sdlc-plugin:coach) with the provided feedback for RLHF. The coach runs its own GATE COACH-1 to have the PO categorize each rule, then files it under the responsible skill in `shapeup/knowledge-base/<skill>.md` (committed → team-shared). Coachable skills: `task-executor`, `ba-pitch-analyzer`, `qa-edge-hunter`; each reads its own file at the top of its next run. The tech lead does not categorize the feedback itself — that is the coach's gate, by design (no assumptions).
+- If the PO provides substantive feedback (not just 'y' or empty) → automatically delegate via Agent (model: exec — see references/protocol.md "Invocation mechanism"): Skill(shapeup-sdlc-plugin:coach) with the provided feedback for RLHF. The coach runs its own GATE COACH-1 to have the PO categorize each rule, then files it under the responsible skill in `shapeup/knowledge-base/<skill>.md` (committed → team-shared). Coachable skills: `task-executor`, `ba-pitch-analyzer`, `qa-edge-hunter`; each reads its own file at the top of its next run. The tech lead does not categorize the feedback itself — that is the coach's gate, by design (no assumptions).
 - Then output → `✅ [slug] [shipped & deployed | built & verified, deploy pending] — [r] rounds, verdict PASS.`
 
 ---