shapeup-sdlc 1.6.3 → 3.0.0

package/hooks/session-rehydrate.mjs

@@ -1,109 +0,0 @@
-#!/usr/bin/env node
-// Session rehydrate — SessionStart hook, matcher "startup|compact|resume|clear".
-//
-// Fires when a session begins with a harness run already in flight, and injects the RunSnapshot's
-// rehydrate_hint as additionalContext: re-derive round/attempt/hill from the files, never from
-// memory. This is the reflex that makes the file-first run-state load-bearing at the exact moment
-// the in-context copy is absent or degraded: without it the orchestrator can re-dispatch an
-// already-ingested order, miscount attempts off a lossy summary, or — measured, below — re-open a
-// run that is already open and rebuild the whole pipeline from phase 1.
-//
-// v1.4.1 — `startup` ADDED TO THE MATCHER, and this is a measured correction, not a widening.
-//
-// The matcher was `compact|resume`. Both of those are continuations of a conversation that still
-// exists. The commonest continuity event in real use has neither: you close the terminal and come
-// back tomorrow, or a teammate picks the work up in a fresh checkout. The CLI reports that as
-// `SessionStart:startup`, and the reflex whose entire purpose is "trust the files, not your
-// memory" did not fire in the one case where there IS no memory to distrust.
-//
-// The SDD harness benchmark measured the cost. Its F4 handoff design is exactly this scenario — a
-// fresh `claude -p` in a workspace where a prior session was cut mid-build — and across three
-// Sonnet rows every one recorded `hooks_fired: ["SessionStart:startup"]` (the plugin's load echo,
-// not this hook). With no pointer to the run in flight, the orchestrator re-entered at phase 1:
-// 82–120 turns before its first write, $4.57–$10.36 for the session, and **0/3 of the gap closed**
-// while the run receipt and board sat on disk the whole time. One row reached GATE L4 — ship
-// sign-off — having advanced the deliverable by zero criteria.
-//
-// Firing on `startup` is free when there is nothing to say: `findRun` returns a run only for an
-// `active-scope` pointer or a `harness-run.md` whose status is mid-run, so an ordinary session in a
-// repo with no run — or with a shipped one — gets silence and exit 0, exactly as before.
-//
-// `clear` is included for the same reason: it discards the conversation and keeps the workspace,
-// which is the same problem wearing a different name.
-//
-// Derivation is always FRESH (files beat any persisted copy); the run-snapshot.json written
-// by hooks/compact-snapshot.mjs is only the fallback if live derivation throws. Fail-open:
-// no active run, or any error → silent exit 0.
-//
-// Contract: SessionStart stdin JSON { cwd, source: "startup"|"resume"|"clear"|"compact" }.
-// Inject via { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext } }.
-
-import { readFileSync } from "node:fs";
-import { deriveSnapshot, snapshotPath } from "../skills/tech-lead/scripts/run-snapshot.mjs";
-import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
-import { runHook, readStdin } from "./lib/decision.mjs";
-import { activeScope } from "../skills/tech-lead/scripts/lib/paths.mjs";
-
-// The snapshot's own hint says "trust the files, not the conversation summary" — correct after a
-// compaction, and slightly wrong on a cold start, where there is no summary and no conversation
-// either. The two sources also fail in DIFFERENT directions, so they need different first sentences:
-//
-//   compact / resume — the risk is acting on a lossy summary of work you remember doing.
-//   startup / clear  — the risk is not knowing the run exists, and OPENING IT AGAIN. That is the
-//                      failure the benchmark measured: a fresh session re-entered at phase 1 and
-//                      spent 82–120 turns rebuilding a pipeline that was already on disk.
-//
-// Naming the right failure is the whole value of the injection. A generic pointer to the files is
-// what a competent agent finds anyway; "there is a run open, do not re-open it" is not.
-function lead(source) {
-  if (source === "startup" || source === "clear") {
-    return "A shapeup-sdlc run is ALREADY OPEN in this workspace and you have no memory of it. " +
-      "Do NOT open a new run, re-run intake, or restart the pipeline from phase 1 — the receipt, " +
-      "the board and the ledger already exist. RESUME from the phase the files say the run is in. ";
-  }
-  return "";
-}
-
-async function main() {
-  await runHook("session-rehydrate", async () => {
-    const raw = await readStdin();
-    let p;
-    try { p = JSON.parse(raw || "{}"); }
-    catch (e) { return { verdict: "error", event: "SessionStart", reason: `unparseable payload: ${e.message}` }; }
-    const cwd = p.cwd || process.cwd();
-
-    let snapshot = null;
-    let source = "live";
-    try {
-      snapshot = deriveSnapshot(cwd);
-    } catch {
-      // Live derivation failed → fall back to the pre-compaction anchor, best effort.
-      source = "anchor";
-      try {
-        const pointer = JSON.parse(readFileSync(activeScope(cwd), "utf8"));
-        if (pointer?.slug) snapshot = JSON.parse(readFileSync(snapshotPath(cwd, pointer.slug), "utf8"));
-      } catch { /* no anchor either → stay silent */ }
-    }
-    if (!snapshot?.rehydrate_hint) {
-      return { verdict: "allow", event: "SessionStart", cwd, subject: p.source ?? null, reason: "no active run — nothing to rehydrate" };
-    }
-
-    return {
-      verdict: "allow", event: "SessionStart", cwd, rule: `injected:${source}`,
-      subject: snapshot.slug ?? p.source ?? null,
-      reason: `rehydrate_hint injected on SessionStart:${p.source ?? "?"}`,
-      // additionalContext is not a deny, but it IS output, so it rides the same channel.
-      payload: {
-        hookSpecificOutput: {
-          hookEventName: "SessionStart",
-          additionalContext: `${lead(p.source)}${snapshot.rehydrate_hint}\n${JSON.stringify(snapshot)}`,
-        },
-      },
-      emit: true,
-    };
-  });
-}
-
-if (isMain(import.meta.url)) {
-  main();
-}

package/skills/advisor-protocol/SKILL.md

@@ -1,171 +0,0 @@
----
-name: advisor-protocol
-description: "Use this skill whenever a harness worker (task-executor, scope-architect) hits a decision it cannot make alone during Build Vertically — a design decision, a spec ambiguity, or a request to write outside its scope's substrate — and needs it adjudicated under a budget instead of guessed or asked ad hoc. Trigger on: \"escalate this decision\", \"ESCALATE\", \"adjudicate this ambiguity\", \"ask the advisor\", \"substrate expansion request\", \"resolve this design decision within budget\", \"how many escalations does this scope have left\". Also triggers when tech-lead needs to answer a worker's structured ESCALATE return during a build round."
----
-
-# Advisor Protocol (ESCALATE grammar + budgets)
-
-The mechanism behind Shape Up's "advisor, not micromanager" posture (design spec v1.1 DD-1,
-DD-8). A worker mid-attempt hits something it genuinely cannot decide alone — not "what should
-I name this variable" (that's Principle A, resolved silently or at the worker's own gate), but
-a decision whose wrong guess is expensive: a design trade-off the spec left open, a spec
-ambiguity that changes behavior, or a file the worker needs to touch outside its scope's
-`allowed_file_substrate`. Instead of guessing or opening an unbounded chat with the PO, the
-worker emits one structured `ESCALATE` return and this skill adjudicates it.
-
-**Why this exists as its own skill, not inline PO chat.** Zero-memory handoff (design spec
-§3.6) means every attempt gets a *fresh* context — no chat history. An answer given once must
-survive every future reset for that scope. This skill is what turns a transient Q&A into a
-persisted decision: it writes the answer to the round-ledger (committed, Tier A) the moment
-it's made, and every future brief for that scope reads it back. Escalation memory lives in
-files, not in chat (DD-8).
-
----
-
-## The ESCALATE grammar
-
-A worker never asks a free-form question mid-attempt. It returns a structured block and stops
-work on the blocked AC/file until an answer comes back:
-
-```yaml
-ESCALATE:
-  scope_id: cart-creation
-  round: 2
-  attempt: 3
-  kind: design-decision | spec-ambiguity | substrate-expansion
-  question: "Contract leaves cart-total rounding unspecified — round half-up or banker's rounding?"
-  options: ["round half-up (matches existing order-total code)", "banker's rounding (matches contract's other money fields)"]
-  default_if_silent: "round half-up"     # optional — see --unattended below
-```
-
-Three kinds, three different resolution paths (below). `default_if_silent` is optional — a
-worker proposes it when it has a reasonable, low-risk fallback; the advisor is never forced to
-accept it.
-
----
-
-## Budget
-
-**≤3 ESCALATEs per scope per round** (design spec §3.3). Counted per `scope_id` + `round`, reset
-each new round. The budget exists so a struggling scope surfaces as *stuck* (routed to the
-hill's stuck-split rule, ≥3 rounds at the same position → forced scope-architect split order) rather than
-draining PO attention one question at a time.
-
-```
-1st–3rd ESCALATE this scope/round → adjudicate normally (below).
-4th+                              → do NOT ask again. Apply the most conservative resolution
-                                     (narrowest scope, no substrate expansion, closest precedent)
-                                     and flag it as a GATE-H hammer proposal: "scope exceeded its
-                                     escalation budget — question N unresolved, applied [X]".
-                                     The worker's attempt continues with that resolution.
-```
-
-Exceeding budget is never a hard stop — Build Vertically must keep moving; it's a signal that
-this scope needs GATE H's attention, not a excuse to freeze the round.
-
----
-
-## Adjudication (in order — cheapest resolution wins)
-
-```
-1. Precedent check (free, no PO time):
-   Search this run's round-ledger.md "Decisions" section (this scope AND sibling scopes) and
-   shapeup/knowledge-base/*.md for an already-answered question that is the same or a
-   clear superset of this one. Found → reuse verbatim, log "resolved by precedent: [ref]",
-   do NOT count against budget (a repeat question is a zero-memory artifact, not a new decision).
-
-2. kind: substrate-expansion:
-   Never silently approved. Present the requested path(s) + why the worker says it needs them.
-   PO/TL approves → dispatch a scope-architect remap order to add the path to the scope contract's
-   `shared_substrate` (never hand-edit the contract — `ba` is its sole writer, F.5). PO/TL
-   declines → worker re-plans within its existing substrate; log the decline as a decision too
-   (prevents re-asking).
-
-3. kind: design-decision | spec-ambiguity, interactive/--auto:
-   Print the ESCALATE block verbatim + budget remaining for this scope/round. Ask (max 1):
-   pick an option / provide a different answer / defer to default_if_silent if offered.
-   Never answer on the PO's behalf — a wrong silent guess here is exactly what zero-memory
-   handoff makes expensive to unwind later.
-
-4. --unattended (no PO available):
-   default_if_silent present → apply it, log "auto-resolved (default, unattended)".
-   No default offered → apply the most conservative option (narrowest scope / least
-   irreversible) and flag it as a GATE-H hammer proposal for PO review before ship — the
-   run must not block, but an unattended guess is never allowed to hide from the PO forever.
-```
-
----
-
-## Persistence — the decision must survive a reset
-
-The instant an ESCALATE is answered (any path above), append one row to the run's committed
-`round-ledger.md` "Decisions" section — never batch it for later, never keep it only in the
-current session (a crash before the next promotion point would lose it):
-
-```
-| Round | Scope | Kind | Question | Answer | Resolved by |
-|-------|-------|------|----------|--------|-------------|
-| 2 | cart-creation | design-decision | cart-total rounding | round half-up | PO (interactive) |
-```
-
-Every subsequent isolated brief for that scope (task-executor's zero-memory handoff, design
-spec §3.6) includes the full decisions table for its `scope_id` — this is how an answer given
-once in round 2 is still known in round 5's fresh-context attempt without replaying any chat
-history.
-
----
-
-## Envelope contract — the domain layer
-
-Orchestrated, this skill is dispatched like every worker: a **WorkOrder** in (`--order <path>`,
-operation `adjudicate`), a **WorkResult** out. The standalone flags below map 1:1 onto the
-payload fields registered for this worker in the central domain registry
-(`skills/tech-lead/schemas/domain.schema.json`, `x-payload-by-worker`):
-
-| Payload field | Standalone flag | Meaning |
-|---|---|---|
-| `payload.ledger` | `--ledger` | The run's committed `round-ledger.md` — every answer persists here |
-| `payload.escalate` | `--escalate` | The worker's ESCALATE block to adjudicate (the `EscalateBlock` grammar above) |
-| `payload.scope_id` | `--scope` | The scope the budget is counted against |
-| `payload.round` | `--round` | The round the budget/decision is counted against |
-
-The WorkResult may carry only `files_touched`, `artifacts`, `assumptions`, `deviations`
-(`x-result-by-worker`): the adjudicated Decision itself persists to the committed round-ledger,
-never to the envelope, so it survives every zero-memory reset.
-
----
-
-## Invocation
-
-```bash
-# Adjudicate one ESCALATE return from a worker (typical: tech-lead calls this mid-round)
-/advisor-protocol --ledger shapeup/checkout-vnpay/round-ledger.md --escalate '<ESCALATE yaml>'
-
-# Check remaining budget for a scope this round (worker or tech-lead, before emitting ESCALATE)
-/advisor-protocol --budget --scope cart-creation --round 2 --ledger shapeup/checkout-vnpay/round-ledger.md
-
-# Headless run — no PO available; apply defaults / conservative fallback, flag the rest for GATE H
-/advisor-protocol --unattended --ledger ... --escalate '<ESCALATE yaml>'
-```
-
-### Flags
-| Flag | Effect |
-|------|--------|
-| `--ledger <path>` | The run's committed `round-ledger.md` (decisions persist here) |
-| `--escalate <yaml\|path>` | The worker's ESCALATE block to adjudicate |
-| `--budget --scope <id> --round <N>` | Report remaining ESCALATE budget for a scope this round, no adjudication |
-| `--unattended` | No PO available — apply defaults/conservative fallback per rule 4 above |
-
----
-
-## Hard Rules (never override without explicit user instruction)
-
-| Rule | Rationale |
-|------|-----------|
-| A worker never guesses a design decision or spec ambiguity silently | The whole point of ESCALATE — wrong silent guesses are the expensive failure mode zero-memory handoff amplifies |
-| Substrate-expansion is never auto-approved | PA3 (cross-scope contamination) exists precisely because agents self-justify "just this once" writes |
-| Budget is ≤3/scope/round; exceeding it never blocks the round | Signals a stuck scope to GATE L2's stuck-split rule instead of freezing Build Vertically |
-| Every answer is persisted to the committed round-ledger the instant it's given | Zero-memory handoff means the *only* place a decision survives is a file, not a session |
-| Precedent reuse never counts against budget | A repeat question is a zero-memory artifact, not a new decision — don't penalize the worker for context loss |
-| An unattended conservative resolution is always flagged for GATE H | An automated guess must stay visible to the PO before ship, never silently absorbed |
-| This skill never designs, builds, or judges | Advisor, not a fifth worker — it adjudicates, it does not decide scope or verify code |

package/skills/ba-pitch-analyzer/scripts/spec-lint.mjs

@@ -1,239 +0,0 @@
-#!/usr/bin/env node
-// Spec lint (pure-skill architecture v1.0, plan §8.2).
-//
-// The mechanical half of the old ba-pitch-analyzer Phase 7a self-audit + Phase 7c parse steps
-// + Phase 6b PA1/PA2 lints — checkbox walking and glob checks a model should never grade on
-// its own output (a worker grading itself was always a judge-purity smell):
-//
-//   PA1  a scope substrate aligned 1:1 with a single top-level directory (directory-thinking)
-//   PA2  a scope substrate resolving to more than the size cap (~15 files)
-//   DISJOINT  a path matched by two scopes' allowed_file_substrate without BOTH declaring it
-//             in shared_substrate
-//   STRUCTURE spec tree completeness (usecases/ ≥1 UC, domain-model, UC ## Steps),
-//             unresolved wikilinks, task frontmatter completeness, unlocks edge-symmetry,
-//             depends_on referencing unknown tasks
-//   TIER-DIRECTION  a committed (SHARED) spec doc wikilinking the LOCAL board ([[tasks/...]]).
-//             Persisted links flow LOCAL→SHARED only: task ids are machine-local (boards
-//             regenerate and renumber) and .shapeup/ is gitignored — a committed task
-//             link dangles on every fresh clone. Cite the UC or scope_id instead.
-//   UC-ANCHOR a task whose use_case_refs is empty or names a UC with no usecases/UC-*.md —
-//             the LOCAL→SHARED anchor must be complete (single-anchor rule; SPIKE/CHORE/
-//             DOCS/MIGRATION tasks anchor elsewhere and are exempt)
-//
-// Zero dependencies (glob matcher inlined from hooks/sandbox-guard.mjs). Judgment stays in the skill
-// (gap severity, lens choice); this script only reports facts.
-//
-// Usage:  node skills/ba-pitch-analyzer/scripts/spec-lint.mjs --slug <slug> [--cwd <dir>]
-// Prints a JSON report. Exit 0 = no red findings, 1 = at least one red.
-
-import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
-import { resolve, join, relative } from "node:path";
-import { parseBoard, deriveUnlocks } from "./board-derive.mjs";
-import { isMain } from "../../tech-lead/scripts/lib/is-main.mjs";
-import { runArgs } from "../../tech-lead/scripts/lib/argv.mjs";
-import { LOCAL } from "../../tech-lead/scripts/lib/paths.mjs";
-import { specDir, scopesDir, tasksDir } from "../../tech-lead/scripts/lib/paths.mjs";
-import { readAllContracts, unreadableReason, SCOPE_CONTRACT } from "../../tech-lead/scripts/lib/contract-md.mjs";
-
-// Inlined from hooks/sandbox-guard.mjs so this skill ships self-contained (a skill's scripts
-// must not reach outside its own folder — channels that copy only skills/ would dangle).
-/**
- * Compile a substrate glob into an anchored RegExp (inlined from sandbox-guard so the skill ships
- * self-contained). Supports single-star, double-star, and double-star-slash segment wildcards.
- * @param {string} glob - The glob pattern.
- * @returns {RegExp} A full-string (`^…$`) matcher for repo-relative paths.
- */
-export function globToRegExp(glob) {
-  let re = "";
-  for (let i = 0; i < glob.length; i++) {
-    const c = glob[i];
-    if (c === "*") {
-      if (glob[i + 1] === "*") {
-        re += glob[i + 2] === "/" ? "(?:[^/]+/)*" : ".*";
-        i += glob[i + 2] === "/" ? 2 : 1;
-      } else re += "[^/]*";
-    } else if ("\\^$.|?+()[]{}".includes(c)) re += "\\" + c;
-    else re += c;
-  }
-  return new RegExp(`^${re}$`);
-}
-
-const SIZE_CAP = 15;
-
-/**
- * Recursively list repo-relative file paths under a root, skipping .git/node_modules/.shapeup.
- * @param {string} root - The base the results are made relative to.
- * @param {string} [dir=root] - Current directory being walked (callers omit it).
- * @param {string[]} [acc=[]] - Accumulator (callers omit it).
- * @returns {string[]} Repo-relative paths of every file found.
- */
-function walkFiles(root, dir = root, acc = []) {
-  for (const e of readdirSync(dir, { withFileTypes: true })) {
-    if (e.name === ".git" || e.name === "node_modules" || e.name === LOCAL) continue;
-    const p = join(dir, e.name);
-    if (e.isDirectory()) walkFiles(root, p, acc);
-    else acc.push(relative(root, p));
-  }
-  return acc;
-}
-
-/**
- * Lint scope contracts for PA1 (directory-thinking), PA2 (size cap), and DISJOINT substrate overlap.
- * @param {Array<{scope_id:string, topology_type?:string, allowed_file_substrate?:string[],
- *   shared_substrate?:string[]}>} scopes - The scope contracts.
- * @param {string[]} repoFiles - Repo-relative file list the substrate globs resolve against.
- * @returns {Array<{rule:string, level:("red"|"warn"), scope:string, detail:string}>} Findings; [] when clean.
- */
-export function lintScopes(scopes, repoFiles) {
-  const findings = [];
-  /**
-   * Resolve a list of substrate globs to the repo files they match.
-   * @param {(string[]|undefined)} globs - Glob patterns (undefined → none).
-   * @returns {string[]} The repo-relative files matched by any glob (deduplication is the caller's).
-   */
-  const resolveGlobs = (globs) => {
-    const res = (globs || []).map((g) => globToRegExp(g));
-    return repoFiles.filter((f) => res.some((r) => r.test(f)));
-  };
-  for (const s of scopes) {
-    const allowed = s.allowed_file_substrate || [];
-    // PA1 — directory-thinking: every glob confined to ONE layer directory (e.g. all of it
-    // under apps/web/). A flow slice crosses layers (apps/web/cart + apps/api/cart passes).
-    const layers = new Set(allowed.map((g) => g.split("/").slice(0, 2).join("/")));
-    if (allowed.length && layers.size === 1 && s.topology_type !== "CHOWDER") {
-      findings.push({ rule: "PA1", level: "red", scope: s.scope_id, detail: `substrate aligns 1:1 with '${[...layers][0]}/' — slice by flow, not by directory` });
-    }
-    // PA2 — resolved file count over the cap (chowder absorbs true strays).
-    const files = resolveGlobs(allowed);
-    if (files.length > SIZE_CAP && s.topology_type !== "CHOWDER") {
-      findings.push({ rule: "PA2", level: "warn", scope: s.scope_id, detail: `substrate resolves to ${files.length} files (cap ~${SIZE_CAP}) — consider splitting` });
-    }
-  }
-  // DISJOINT — pairwise overlap not covered by BOTH scopes' shared_substrate.
-  for (let i = 0; i < scopes.length; i++) {
-    for (let j = i + 1; j < scopes.length; j++) {
-      const a = scopes[i], b = scopes[j];
-      const filesA = new Set(resolveGlobs(a.allowed_file_substrate));
-      const overlap = resolveGlobs(b.allowed_file_substrate).filter((f) => filesA.has(f));
-      const sharedA = (a.shared_substrate || []).map(globToRegExp);
-      const sharedB = (b.shared_substrate || []).map(globToRegExp);
-      for (const f of overlap) {
-        const declared = sharedA.some((r) => r.test(f)) && sharedB.some((r) => r.test(f));
-        if (!declared) findings.push({ rule: "DISJOINT", level: "red", scope: `${a.scope_id}+${b.scope_id}`, detail: `${f} is in both substrates but not in both shared_substrate lists — PA3 waiting to happen` });
-      }
-    }
-  }
-  return findings;
-}
-
-/**
- * Lint spec-tree completeness, wikilink resolution, tier-direction, task frontmatter/graph
- * integrity (edge symmetry, dependency existence), and UC-anchor completeness.
- * @param {{specDir:string, tasks:Array<object>}} input - The SHARED spec dir and the parsed board.
- * @returns {Array<{rule:string, level:("red"|"warn"), detail:string}>} Findings; [] when clean.
- */
-export function lintStructure({ specDir, tasks }) {
-  const findings = [];
-  const ucDir = join(specDir, "usecases");
-  if (!existsSync(join(specDir, "domain-model.md"))) findings.push({ rule: "STRUCTURE", level: "red", detail: "domain-model.md missing" });
-  const ucs = existsSync(ucDir) ? readdirSync(ucDir).filter((f) => /^UC-.*\.md$/.test(f)) : [];
-  if (!ucs.length) findings.push({ rule: "STRUCTURE", level: "red", detail: "usecases/ has no UC-*.md — nothing to build or grade against" });
-  for (const f of ucs) {
-    const body = readFileSync(join(ucDir, f), "utf8");
-    if (!/^##\s+Steps/m.test(body)) findings.push({ rule: "STRUCTURE", level: "warn", detail: `${f} has no ## Steps section` });
-  }
-  // Wikilinks in spec docs must resolve within the spec dir — and never cross the tier
-  // boundary: a SHARED doc linking the LOCAL board is the wrong direction by construction.
-  const specFiles = existsSync(specDir) ? walkFiles(specDir) : [];
-  const names = new Set(specFiles.map((f) => f.replace(/\.md$/, "")));
-  for (const f of specFiles.filter((x) => x.endsWith(".md"))) {
-    const body = readFileSync(join(specDir, f), "utf8");
-    for (const m of body.matchAll(/\[\[([^\]#|]+)/g)) {
-      const target = m[1].trim().replace(/\.md$/, "");
-      if (target.startsWith("tasks/")) {
-        findings.push({ rule: "TIER-DIRECTION", level: "red", detail: `${f} → [[${m[1].trim()}]] links the LOCAL board from a committed doc — links flow LOCAL→SHARED only; cite the UC or scope_id instead (task ids renumber per machine)` });
-        continue;
-      }
-      if (!names.has(target) && ![...names].some((n) => n.endsWith(`/${target}`) || n === target)) {
-        findings.push({ rule: "WIKILINK", level: "warn", detail: `${f} → [[${m[1].trim()}]] unresolved in spec dir` });
-      }
-    }
-  }
-  // Task frontmatter + graph integrity (edge symmetry = the mechanized KB-BA-001 check).
-  const ids = new Set(tasks.map((t) => t.id));
-  const derived = deriveUnlocks(tasks);
-  for (const t of tasks) {
-    for (const k of ["id", "status"]) if (!t[k] || t[k] === "unknown") findings.push({ rule: "TASK", level: "red", detail: `${t.file} missing frontmatter ${k}` });
-    for (const d of t.depends_on) if (!ids.has(d)) findings.push({ rule: "TASK", level: "red", detail: `${t.id} depends_on ${d} which does not exist` });
-    if (JSON.stringify([...t.unlocks].sort()) !== JSON.stringify(derived[t.id] || [])) {
-      findings.push({ rule: "EDGE-SYMMETRY", level: "red", detail: `${t.id} unlocks ${JSON.stringify(t.unlocks)} ≠ derived inverse ${JSON.stringify(derived[t.id])} — run board-derive.mjs --write` });
-    }
-  }
-  // UC-ANCHOR — the LOCAL→SHARED anchor must be complete: every implementation task names
-  // ≥1 UC (single-anchor rule, task-generation.md) and each named UC exists on disk.
-  // SPIKE/CHORE/DOCS/MIGRATION tasks anchor elsewhere (api_ref / linked_docs) — exempt.
-  const ucIds = new Set(ucs.map((f) => f.replace(/\.md$/, "")));
-  const anchorExempt = new Set(["spike", "chore", "docs", "migration"]);
-  for (const t of tasks) {
-    if (anchorExempt.has((t.type || "").toLowerCase())) continue;
-    const refs = t.use_case_refs || [];
-    if (!refs.length) {
-      findings.push({ rule: "UC-ANCHOR", level: "red", detail: `${t.id} has empty use_case_refs — every task must anchor into the committed spec (LOCAL→SHARED, single-anchor rule)` });
-      continue;
-    }
-    for (const r of refs) {
-      const ucId = r.replace(/^\[\[|\]\]$/g, "").replace(/^usecases\//, "");
-      if (!ucIds.has(ucId)) findings.push({ rule: "UC-ANCHOR", level: "red", detail: `${t.id} use_case_refs "${r}" does not resolve to usecases/${ucId}.md` });
-    }
-  }
-  return findings;
-}
-
-/**
- * Run the full spec lint (scopes + structure) for a slug.
- * @param {{cwd:string, slug:string}} opts - Working root and feature slug.
- * @returns {{slug:string, scopes:number, tasks:number, red:number, warn:number,
- *   findings:Array<object>}} Counts and the combined findings from {@link lintScopes} and
- *   {@link lintStructure}.
- */
-export function lint({ cwd, slug }) {
-  const specRoot = specDir(cwd, slug);
-  const contracts = readAllContracts(scopesDir(cwd, slug), SCOPE_CONTRACT);
-  const scopes = contracts.map((c) => c.contract);
-  const tasks = parseBoard(tasksDir(cwd, slug));
-  const repoFiles = walkFiles(cwd);
-  const findings = [
-    // HD-001. A contract whose table this parser cannot see reads as a contract that declared no
-    // table, and every rule below then passes for the part it could not read. Loud, not empty.
-    ...contracts
-      .map(({ contract, path }) => ({ reason: unreadableReason(contract), scope: contract.scope_id || path }))
-      .filter((x) => x.reason)
-      .map((x) => ({ rule: "CONTRACT-UNREADABLE", level: "red", scope: x.scope, detail: `${x.reason} — the rules below could not check what they could not read` })),
-    ...lintScopes(scopes, repoFiles),
-    ...lintStructure({ specDir: specRoot, tasks }),
-  ];
-  return {
-    slug,
-    scopes: scopes.length,
-    tasks: tasks.length,
-    red: findings.filter((f) => f.level === "red").length,
-    warn: findings.filter((f) => f.level === "warn").length,
-    findings,
-  };
-}
-
-/** The typed argv contract (see `skills/tech-lead/scripts/lib/argv.mjs`). */
-export const ARGV_SPEC = {
-  usage: "spec-lint.mjs --slug <slug> [--cwd <dir>]",
-  _: { arity: 0, max: 0, name: "(no positional operands)" },
-  slug: { type: "str", required: true },
-  cwd: { type: "path" },
-};
-
-const isMainModule = isMain(import.meta.url);
-if (isMainModule) {
-  const args = runArgs(ARGV_SPEC);
-  const report = lint({ cwd: resolve(args.cwd || process.cwd()), slug: args.slug });
-  console.log(JSON.stringify(report, null, 2));
-  process.exit(report.red > 0 ? 1 : 0);
-}

package/skills/spec-evaluator/README.md

@@ -1,93 +0,0 @@
-# spec-evaluator
-
-The **judge** in a planner → generator → evaluator harness. Pairs with `task-executor`
-(generator) and `ba-pitch-analyzer` (planner). Reads the same spec tree, exercises the
-**running** app, returns a hard-threshold verdict + file:line bug list, and hands bugs back
-to the generator. Skeptical by default; never marks a task `done`.
-
-v0.1 evaluates one dimension only — **spec-conformance** (AC + Done-when + contract shapes +
-non-go). Security / performance ship disabled, injectable later with zero core changes.
-
----
-
-## Resource map
-
-```
-spec-evaluator/
-├── SKILL.md                              # entry point — frontmatter, GATE V0–V3, flags, hard rules
-├── README.md                             # this file
-└── references/
-    ├── dimension-contract.md             # ★ the injection interface every dimension implements
-    ├── anti-leniency.md                  # skeptical posture — read before any verdict (GATE V2)
-    ├── probing.md                        # Phase A — Playwright CLI + per-variant probe strategy
-    ├── report-schema.md                  # Phase B — the EVAL-TASK-NNN.md handoff file
-    └── dimensions/
-        ├── _registry.md                  # which dimensions are active + how to add one
-        ├── spec-conformance.md           # ✅ the only enabled dimension (correctness)
-        ├── security.md                   # ⛔ disabled stub — worked example of the contract
-        └── performance.md                # ⛔ disabled stub — worked example of the contract
-```
-
-| Resource | Loaded at | Purpose |
-|----------|-----------|---------|
-| `SKILL.md` | always | gate pipeline, invocation, authority rules |
-| `references/dimension-contract.md` | GATE V0.5 | the interface; validates each dimension before running it |
-| `references/dimensions/_registry.md` | GATE V0.5 | active set resolution (`--dimensions` overrides) |
-| `references/dimensions/spec-conformance.md` | per task | the default correctness dimension |
-| `references/dimensions/{security,performance}.md` | only if enabled | injectable stubs, off by default |
-| `references/anti-leniency.md` | before GATE V2 | absence of evidence = FAIL; banned phrases |
-| `references/probing.md` | Phase A | how to collect evidence (CLI > MCP, per variant) |
-| `references/report-schema.md` | Phase B | the file the generator reads next |
-
-★ = the load-bearing file for "spec now, more dimensions later."
-
----
-
-## Install
-
-```bash
-# Project scope (shareable via version control) — recommended
-cp -r spec-evaluator <repo>/.claude/skills/
-
-# or user scope (all your projects)
-cp -r spec-evaluator ~/.claude/skills/
-```
-
-Restart the session (or re-open the skills interface) so the new skill is discovered.
-
-## Invoke
-
-```bash
-/spec-evaluator --spec shapeup/checkout-vnpay/spec/ --task TASK-007  # default: spec-conformance
-/spec-evaluator --spec ... --task TASK-007.web                                # platform variant
-/spec-evaluator --spec ... --task TASK-007.be --browser none                  # backend-only, no browser
-/spec-evaluator --spec ... --task TASK-007 --dimensions spec-conformance,security   # inject a dimension
-/spec-evaluator --spec ... --task TASK-007 --single-pass --auto               # one end pass, skip sign-off
-```
-
-## Pipeline position
-
-```
-ba-pitch-analyzer (planner) ─► task-executor (generator) ─► spec-evaluator (judge)
-                                      ▲                                │
-                                      └──── bug list (EVAL-TASK-NNN) ◄─┘  on FAIL
-```
-The evaluator writes `.shapeup/<slug>/evaluation/EVAL-<task_id>.md` (LOCAL run-trace root) and sets `eval_verdict` on the task.
-`task-executor` owns `status: done`. Judge and doer stay separate by design.
-
-## Inject a new dimension (zero core edits)
-
-1. Copy the "Minimal valid dimension" block from `references/dimension-contract.md` to
-   `references/dimensions/<id>.md`; fill criteria, probes, threshold, bug template.
-2. Set `enabled: true` in `references/dimensions/_registry.md` (or pass `--dimensions … ,<id>`).
-3. Re-run. GATE V0.5 validates it against the contract and loads it; non-conforming files
-   are skipped with a warning, never half-run.
-
-`applies_to` scopes a dimension to a lens / package / platform variant, so a `visual`
-dimension can run only on `.web` tasks and `security` only on `.be`/`.shared`.
-
----
-
-## Version
-0.1 — initial template. GATE V0–V3, skeptical-by-default, single enabled dimension,
-pluggable dimension contract, Playwright CLI probing, file:line bug handoff.