shapeup-sdlc 1.6.2

package/skills/ba-pitch-analyzer/references/test-surface.md

@@ -0,0 +1,102 @@
+# Test Surface — Derivation Rules (v2.9)
+
+`## Test Surface` is a **derived section** on each UC. It is generated *mechanically* from
+material that already exists in the spec — never invented. If a test idea cannot cite its
+source row below, it does not belong here (it belongs to exploratory QA, post-build).
+
+**Why it exists.** `spec-conformance` grades the AC that were written; it cannot expand
+them. The Test Surface is the systematic expansion — boundary values, negative cases,
+error-code coverage — done once at spec time so the evaluator (`test-surface-conformance`
+dimension) can probe it. Division of labor settled at the QA meeting (2026-06-11):
+derivable tests = BA + Evaluator (this file); exploratory edges = `/qa-edge-hunter`,
+post-PASS, on the running app.
+
+---
+
+## Derivation table (exhaustive — these four sources, nothing else)
+
+| # | Source (must exist in spec) | Mechanical rule → test entries |
+|---|---|---|
+| D1 | `## Invariants` `[INV-NN]` | One **violation-attempt** entry per invariant: construct the action that would break it, expect rejection/hold. `TS-INV-NN`. |
+| D2 | `## Error Cases` table rows | One entry per error code: trigger the Condition, expect the Code + HTTP status. `TS-ERR-<CODE>`. |
+| D3 | Contract Request shape (standard lens: `contracts/*.contract.md`; lite lens: UC `Input` interface) | Per required field: one **missing-field** entry + one **type-violation** entry. Per bounded field (length/range/enum): one **boundary** entry at each edge (min−1, min, max, max+1 where meaningful). `TS-REQ-<field>-<kind>`. |
+| D4 | Pitch `No-gos` that touch this UC's actor/action | One **breach-probe** entry per relevant no-go: attempt the excluded behavior via the UC's surface, expect it blocked or absent (a hidden-but-reachable path = FAIL). `TS-NOGO-NN`. |
+
+**Dedup rule:** if D2 already covers a D3 case (e.g. error table has `VALIDATION_400` for
+missing field), emit ONE entry and cite both sources — never two entries for one probe.
+
+**Anti-invention rule (hard):** no entry may introduce a behavior, limit, or field not
+present in the four sources. Discovering "we should also test X" during derivation = a spec
+gap → surface it at GATE 4 as a question (max 2 rule applies), do not silently add a test.
+
+---
+
+## Entry schema (rows under `## Test Surface` in the UC)
+
+```markdown
+## Test Surface
+<!-- DERIVED — regenerate via a retrofit-surface order; do not hand-author rows here.
+     Source must cite D1–D4. Exploratory/edge tests live in QA's charters, not here. -->
+| ID | Oracle | Probe | Expect | Source |
+|---|---|---|---|---|
+| TS-INV-01 | ui | Attempt withdrawal exceeding balance via UC input | Rejected `INSUFFICIENT_FUNDS`, balance unchanged | D1: INV-01 |
+| TS-ERR-NOT_FOUND | http | Submit with non-existent aggregate id | 404 `NOT_FOUND` per Error Cases | D2 |
+| TS-REQ-amount-missing | http | Omit `amount` from request | 400 validation error, no side effect | D3 + D2 (dedup) |
+| TS-REQ-amount-boundary | http | `amount` = 0 / 0.01 / max / max+0.01 | Per contract bounds: edges accepted, outside rejected | D3 |
+| TS-NOGO-02 | ui | Attempt export via direct URL (pitch no-go: "no export") | Blocked/absent — no file served | D4 |
+```
+
+`Probe` must be executable against the running deliverable — no "verify code does X" static
+phrasing.
+
+### The `Oracle` column (evaluation-contract tag)
+
+`Oracle` declares **how the evaluator verifies the row** — it is the dispatch key of the
+evaluation contract. One verdict per row, single judge; the oracle changes only *how* evidence is
+gathered, never *who* decides.
+
+| `oracle` | When the deliverable is… | Evidence the evaluator cites |
+|---|---|---|
+| `ui` *(default)* | a running web app | accessibility-tree node, state before/after, console |
+| `process` | a CLI / script | spawned exit code + stdout/stderr + crash check |
+| `test` | a library / module | the project's own test suite (exit + failing-test names) |
+| `snapshot` | a generator / pure refactor | unified diff vs a golden file (empty = PASS) |
+| `http` | a service / API | response status + body assertion |
+
+**Rules:**
+- **Default is `ui`.** A row (or AC) that omits `Oracle` is treated as `ui` — pre-v2.9 specs and
+  existing web pitches are unchanged.
+- **Pick the oracle from the deliverable type, not the test idea.** A `todo` CLI's `TS-*` rows are
+  `process`; a shared library's are `test`; an HTTP endpoint's are `http`. When a UC's deliverable
+  is non-UI, set the oracle on every derived row so the evaluator does not fall back to driving a
+  browser that does not exist.
+- **The expectation must be observable by that oracle.** A `process` row's Expect is phrased in
+  exit code + stdout (e.g. *"exit ≠ 0, message names the file, no stack trace"*); a `test` row's is
+  *"suite green, the named case passes"*. Never phrase a row so its only check is reading source.
+- This is the half of the goal that makes **"build anything"** real: the same Test Surface
+  discipline now derives evaluable rows for a CLI or a library, not only a browser app.
+
+---
+
+## Generation points
+
+1. **Phase 4 (fresh run, v2.9+):** derived per UC immediately after Error Cases are
+   written, included in the GATE 4 review.
+2. **retrofit-surface operation (retrofit, incremental reducer):** for pre-v2.9 specs.
+   Frozen-zone discipline identical to the reconcile operation (the order's substrate enforces it):
+   - READ-ONLY: domain-model, UC Steps/Input/Output/Invariants, ux-behavior, contracts/, tasks/
+   - WRITE: append `## Test Surface` to each UC (after Error Cases; skip UCs that already
+     have one unless `--force-surface`), log touched UCs in `run-state.human_edited_files`,
+     set `run-state.test_surface: true`. Regenerate nothing else.
+   - Source material missing (no Invariants, no contracts on lite) → derive from what
+     exists; a UC whose four sources are all empty gets a one-line section:
+     `_No derivable surface — sources empty. Exploratory coverage only (see qa-edge-hunter)._`
+3. **reconcile operation:** when a new `[INV-NN]` is appended to a UC, also
+   append its `TS-INV-NN` row (same append-only discipline, same `human_edited_files` log).
+
+## Audit hooks (spec-lint)
+- L2: every UC (v2.9 spec or `test_surface: true`) has `## Test Surface` with ≥1 row or the
+  explicit empty-sources line.
+- L3: every `[INV-NN]` has a matching `TS-INV-NN` row; every Error Case code has a `TS-ERR-*`
+  row; every TS row cites D1–D4 in Source; the `Oracle` is one of the registry values (or omitted
+  ⇒ `ui`), and is non-`ui` when the UC's deliverable has no browser (CLI/library/service).

package/skills/ba-pitch-analyzer/references/ux-behavior-patterns.md

@@ -0,0 +1,269 @@
+# UX Behavior Patterns
+
+Reference for Phase 3 of the BA Pitch Analyzer. Read before writing `ux-behavior.md`.
+
+---
+
+## Deriving Screens From Pitch
+
+From the pitch breadboarding and fat marker sketches, identify:
+
+1. **Entry points** — how does the user reach this feature?
+2. **Core interaction** — the primary action the user takes
+3. **Decision points** — where does the flow branch?
+4. **Exit points** — success path, failure path, abandon path
+
+Each decision point is typically a screen boundary.
+
+---
+
+## State Machine per Screen
+
+Every screen must have a state table. States map to domain aggregate statuses from
+`domain-model.md`. Use this as a checklist:
+
+| State | Always Present? | Notes |
+|-------|----------------|-------|
+| `idle` / `default` | ✅ | Initial mount state |
+| `loading` / `submitting` | ✅ | Any async operation |
+| `error` | ✅ | Inline field errors vs. page-level errors |
+| `empty` | ⚠️ | When list/data can be empty |
+| `success` / `done` | ✅ for forms | Show confirmation, not just redirect |
+| `disabled` | ⚠️ | When action is conditionally unavailable |
+
+### State Table Format
+
+```markdown
+| State | Trigger | UI Behavior | CTA State |
+|-------|---------|-------------|-----------|
+| `idle` | screen mount | form editable | enabled |
+| `validating` | user taps submit | form locked, spinner on CTA | loading |
+| `field-error` | validation fails | inline error messages shown | enabled |
+| `submitting` | all validation passes | full-screen loader | hidden |
+| `success` | API response 200 | redirect or success toast | — |
+| `error` | API response 4xx/5xx | error banner, form re-enabled | enabled |
+```
+
+---
+
+## Behavior Rules Format
+
+Document explicit rules that aren't obvious from the state machine:
+
+```markdown
+### Behavior Rules
+- [RULE-01] CTA is disabled until all required fields pass validation
+- [RULE-02] Phone number field auto-formats to `0XX XXX XXXX` on blur
+- [RULE-03] If `totalAmount < 10,000 VND`, disable VNPay option with tooltip
+- [RULE-04] Auto-save draft every 30 seconds when form is dirty
+- [RULE-05] Back navigation shows confirmation dialog if form is dirty
+```
+
+Number rules so tasks can reference them: `implements [[ux-behavior#RULE-03]]`
+
+---
+
+## Error State Catalog
+
+Every screen must have an explicit error catalog. Categorize:
+
+| Category | Examples | UX Treatment |
+|---|---|---|
+| **Validation** | Required field, invalid format | Inline, under field, immediate |
+| **Business rule** | Insufficient stock, limit exceeded | Inline banner, blocking |
+| **Network** | Timeout, offline | Retry button, non-blocking toast |
+| **Auth** | Session expired, unauthorized | Redirect to login |
+| **Server** | 500, unexpected | Generic error page with support link |
+
+```markdown
+### Error Catalog: [ScreenName]
+
+| Error Code | Condition | User Message | Action |
+|---|---|---|---|
+| `NETWORK_TIMEOUT` | No response in 30s | "Connection is slow, please try again" | [Retry] button |
+| `ITEM_UNAVAILABLE` | Stock = 0 at checkout | "Product {name} is out of stock" | [View similar products] |
+| `SESSION_EXPIRED` | Token expired | "Your session has expired" | [Log in again] → redirect |
+| `PAYMENT_DECLINED` | VNPay returns fail | "Payment failed. Check your account." | [Try another method] |
+```
+
+---
+
+## Screen Flow Diagrams
+
+Use ASCII for flows — no Mermaid (Claude Code terminals can't render it):
+
+```
+[CartScreen]
+    │
+    ├─ empty cart ──► [EmptyCartScreen]
+    │
+    └─ confirm ──► [CheckoutScreen]
+                         │
+                ┌────────┴────────┐
+                │                 │
+           address ok         address error
+                │                 │
+         [PaymentScreen]    [AddressFormScreen]
+                │
+        ┌───────┼───────┐
+        │       │       │
+      vnpay   momo    cod
+        │       │       │
+        └───────┴───┐   │
+                    │   └──► [ConfirmationScreen] (cod)
+              [VNPayRedirect]
+                    │
+            ┌───────┴───────┐
+            │               │
+          success          failed
+            │               │
+    [ConfirmationScreen]  [PaymentFailedScreen]
+```
+
+---
+
+## Mobile vs Web Considerations
+
+Document when behavior differs by platform:
+
+```markdown
+### Platform Differences: [ScreenName]
+
+| Behavior | Mobile | Web |
+|---|---|---|
+| Payment redirect | Deep link back to app | Popup or same tab |
+| Address input | Native maps picker | Text autocomplete (Goong) |
+| Photo upload | Camera or gallery sheet | File picker |
+| Session expired | Toast + slide to login | Modal |
+```
+
+---
+
+## Vietnam-Specific UX Patterns
+
+Flag these when relevant to the pitch:
+
+- **VNPay redirect:** User leaves app → payment gateway → returns via deep link or webhook
+- **Zalo ZNS:** Transactional messages (not push) — user must be Zalo friend of OA
+- **MoMo deep link:** `momo://...` schema, must handle fallback to web
+- **Phone as primary identifier:** Format `0XX XXX XXXX`, normalize to `+84` for storage
+- **Vietnamese address:** Province → District → Ward → Street — hierarchical dropdown
+
+---
+
+## LITE Lens — ux-behavior.md is the Primary Spec
+
+When `lens: lite`, `ux-behavior.md` is the **most authoritative document** in the spec tree.
+It must be more exhaustive than in STANDARD mode. Apply these additional requirements:
+
+### Required additions for LITE
+
+**1. Navigation Stack**
+
+Document the full navigation hierarchy — not just screen flow:
+
+```
+Stack Navigator: AppStack
+  ├── Tab: HomeTab → HomeScreen
+  ├── Tab: OrderTab → OrderListScreen
+  │       └── push → OrderDetailScreen
+  │               └── push → CheckoutScreen   ← this feature
+  │                       └── modal → PaymentWebViewScreen
+  └── Tab: ProfileTab → ProfileScreen
+```
+
+**2. Offline Behavior Rules**
+
+For every screen that reads or writes data, document offline behavior explicitly:
+
+| Action | Online | Offline | Sync Strategy |
+|--------|--------|---------|--------------|
+| Load order list | fetch API | show cached data | stale-while-revalidate |
+| Submit order | POST /orders | queue locally | sync on reconnect |
+| Upload photo | PUT /photos | queue locally | retry × 3 on reconnect |
+
+**3. Gesture and Interaction Specs**
+
+Document non-obvious interactions explicitly — these are not derivable from API contracts:
+
+```
+- Pull-to-refresh: triggers full reload, resets pagination
+- Long press on order card: show context menu (copy ID, share)
+- Swipe left on list item: reveal delete action (iOS) / show checkbox (Android)
+- Back gesture during payment: confirm dialog — "Leave payment? Your cart is saved."
+```
+
+**4. Platform Differences (mandatory, not optional)**
+
+Every screen must have a Platform Differences sub-section when behavior diverges:
+
+```markdown
+### Platform Differences: CheckoutScreen
+
+| Behavior | iOS | Android |
+|----------|-----|---------|
+| Address picker | Apple Maps sheet | Google Maps bottom sheet |
+| Payment deeplink return | Universal Link | Intent filter |
+| Keyboard avoidance | KeyboardAvoidingView behavior="padding" | behavior="height" |
+| haptic feedback | UIImpactFeedbackGenerator | Vibrator.vibrate(50) |
+```
+
+**5. API Stub Contracts (LITE only)**
+
+In LITE mode, tasks use typed fetch wrappers without formal contracts.
+Document the assumed API shape inline in ux-behavior.md as a stub:
+
+```typescript
+// Assumed API stub — will be replaced by contracts/ in STANDARD upgrade
+interface CheckoutAPI {
+  submitOrder(payload: SubmitOrderPayload): Promise<{ orderId: string }>
+  getPaymentUrl(orderId: string): Promise<{ url: string }>
+}
+// Source: [[usecases/UC-SubmitOrder#Steps]]
+```
+
+This stub is the handoff artifact to the API team if/when STANDARD upgrade happens.
+
+---
+
+## Visual Design Contracts & Figma Integration (Co-authored by Product Designer)
+
+To prevent discrepancies between Figma designs and final UI implementation, the Product Designer and BA co-author the visual section of each screen specification.
+
+### 1. Figma Reference Mapping
+For every screen, specify the exact Figma Frame link in the header:
+```markdown
+Figma Frame: https://www.figma.com/file/XYZ/AppName?node-id=123-456
+```
+
+### 2. Visual & Layout Spec Table
+Define the layout model, alignment, spacing, and responsive behavior:
+```markdown
+| Layout Property | Mobile View | Desktop View | Styling Implementation Details |
+|---|---|---|---|
+| **Structure** | Vertical block (`flex-col`) | Horizontal side-by-side (`flex-row`) | Flexbox with gap size 16px (`gap-4`) |
+| **Grid / Columns** | 1 Column | 2 Columns (sidebar/main) | Sidebar: 300px width fixed, Main: flexible |
+| **Spacing** | Padding 16px (`p-4`) | Padding 24px (`p-6`) | Keep alignment strictly centered |
+| **Typography** | Body: 14px (`text-sm`) | Body: 16px (`text-base`) | Use Outfit font family |
+```
+
+### 3. Design Tokens Checklist
+Every component must map to the project's standard CSS variables or Tailwind utility classes. Do not use ad-hoc hex codes or absolute layout offsets:
+```markdown
+| Element | Visual Style / Token | Class/Property | Figma Source |
+|---|---|---|---|
+| Card Container | Rounded border, light shadow | `bg-card rounded-2xl shadow-sm` | Card Component |
+| CTA Button | Brand primary background, bold text | `bg-primary text-white font-bold h-12` | Primary Button |
+| Error Message | Brand red text, small font | `text-danger text-xs font-semibold` | Input/Alert Error |
+| Border | Divider line | `border-gray-200` | Border line |
+```
+
+### 4. Interactive & State Design
+Specify the visual styling changes for all active, hover, focused, disabled, and loading states:
+```markdown
+- **Button Hover**: Darkens background by 10% (`hover:bg-primary-dark`)
+- **Input Focus**: Border changes to brand color with subtle outline ring (`focus:border-primary focus:ring-1 focus:ring-primary`)
+- **Disabled State**: Button opacity is reduced to 50% (`disabled:opacity-50 disabled:cursor-not-allowed`)
+- **Loading Overlay**: Full-screen semi-transparent backdrop (`bg-black/40`) with center spinner
+```
+

package/skills/ba-pitch-analyzer/scripts/board-derive.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+// Board derivation (pure-skill architecture v1.0, plan §8.2).
+//
+// The mechanical half of the old ba-pitch-analyzer Phase 7b + v3.3 link-field rules — pure
+// graph math a model should never re-derive (and could get wrong: KB-BA-001's 10 asymmetric
+// edges came from hand-authored `unlocks`):
+//
+//   • `unlocks` = the depends_on inverse, recomputed over the WHOLE board (--write persists
+//     it into task frontmatter — run on every ingest; asymmetric edges become impossible)
+//   • Σ estimated_hours, package distribution, critical path (longest depends_on chain)
+//   • Appetite Guard arithmetic (--appetite-hours N → overflow flag; the HAMMER *pause* on
+//     overflow is an orchestrator gate, never resolved here)
+//   • board-vs-T0 drift check (a FINISHED scope whose tasks still read `ready`) when scope
+//     contracts name their tasks — flag, never fix
+//
+// Zero dependencies. Usage:
+//   node skills/ba-pitch-analyzer/scripts/board-derive.mjs --slug <slug> [--cwd <dir>] [--write]
+//        [--appetite-hours N]
+// Prints a JSON report; exit 0 (drift/overflow are flags for the caller's gate, not errors).
+
+import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { isMain } from "../../tech-lead/scripts/lib/is-main.mjs";
+import { runArgs } from "../../tech-lead/scripts/lib/argv.mjs";
+import { tasksDir, scopesDir, hillDir } from "../../tech-lead/scripts/lib/paths.mjs";
+import { readAllContracts, splitFrontmatter, SCOPE_CONTRACT } from "../../tech-lead/scripts/lib/contract-md.mjs";
+
+/**
+ * Read a list field from a frontmatter string, inline `[a, b]` or YAML block sequence alike.
+ *
+ * HD-004 — the SECOND instance of HD-003, in a second parser. This repo had two hand-rolled
+ * frontmatter readers: `contract-md.mjs` for the committed contracts, and this one for the board.
+ * HD-003 was fixed in the first, and this one still silently dropped a block sequence — so a board
+ * written as
+ *   use_case_refs:
+ *     - UC-01
+ *   touched_files:
+ *     - src/review/format.js
+ * lost EVERY list field. Measured on three paid `ba-pitch-analyzer` runs: `touched_files` and
+ * `use_case_refs` came back empty for all twenty tasks, `depends_on`/`unlocks` came back empty in
+ * both directions so edge-symmetry passed VACUOUSLY, and the only reason it was not entirely silent
+ * is that UC-ANCHOR went red. Downstream, `scope-architect` receives a board with no slicing input
+ * at all.
+ *
+ * The fix is to stop having two parsers rather than to patch this one: `splitFrontmatter` already
+ * reads both forms, so this delegates to it. A second implementation of a format is a second
+ * format, and these two had already drifted.
+ *
+ * @param {string} fm - The frontmatter text (without the `---` fences).
+ * @param {string} key - The list key to read.
+ * @returns {string[]} The trimmed, unquoted, non-empty members; [] when the key is absent.
+ */
+const listField = (fm, key) => {
+  const v = splitFrontmatter(`---\n${fm}\n---\n`).meta[key];
+  if (Array.isArray(v)) return v.map((x) => String(x).trim()).filter(Boolean);
+  if (v === null || v === undefined || v === "") return [];
+  return [String(v).trim()].filter(Boolean);
+};
+
+/**
+ * Parse every TASK-*.md in a board directory into structured task records.
+ * @param {string} tasksDir - Absolute path to the LOCAL tasks directory.
+ * @returns {Array<{file:string, id:string, type:string, status:string, hours:number, pkg:string,
+ *   depends_on:string[], unlocks:string[], use_case_refs:string[], body:string}>} One record per
+ *   task file; [] when the directory does not exist.
+ */
+export function parseBoard(tasksDir) {
+  if (!existsSync(tasksDir)) return [];
+  return readdirSync(tasksDir)
+    .filter((f) => /^TASK-[\w.-]+\.md$/i.test(f))
+    .map((f) => {
+      const body = readFileSync(join(tasksDir, f), "utf8");
+      const fm = (body.match(/^---\r?\n([\s\S]*?)\r?\n---/) || [, ""])[1];
+      return {
+        file: join(tasksDir, f),
+        id: (fm.match(/^id:\s*(TASK-[\w.-]+)/im) || [])[1] || f.replace(/\.md$/, ""),
+        type: (fm.match(/^type:\s*(\S+)/im) || [, ""])[1],
+        status: (fm.match(/^status:\s*(\S+)/im) || [, "unknown"])[1],
+        hours: Number((fm.match(/^estimated_hours:\s*([\d.]+)/im) || [])[1]) || 0,
+        pkg: (fm.match(/^package:\s*(.+)$/im) || [, ""])[1].trim(),
+        depends_on: listField(fm, "depends_on"),
+        unlocks: listField(fm, "unlocks"),
+        use_case_refs: listField(fm, "use_case_refs"),
+        body,
+      };
+    });
+}
+
+/**
+ * Compute `unlocks` as the inverse of `depends_on` over the whole board (never hand-authored).
+ * @param {Array<{id:string, depends_on:string[]}>} tasks - The parsed board.
+ * @returns {Object<string,string[]>} Map of task id → sorted ids it unlocks.
+ */
+export function deriveUnlocks(tasks) {
+  const unlocks = Object.fromEntries(tasks.map((t) => [t.id, []]));
+  for (const t of tasks) for (const dep of t.depends_on) if (unlocks[dep]) unlocks[dep].push(t.id);
+  for (const id of Object.keys(unlocks)) unlocks[id].sort();
+  return unlocks;
+}
+
+/**
+ * Find the critical path: the depends_on chain with the greatest summed hours.
+ * @param {Array<{id:string, depends_on:string[], hours:number}>} tasks - The parsed board.
+ * @returns {{hours:number, chain:string[]}} The longest chain's total hours and its task ids in
+ *   dependency order (cycles are guarded and contribute nothing).
+ */
+export function criticalPath(tasks) {
+  const byId = Object.fromEntries(tasks.map((t) => [t.id, t]));
+  const memo = {};
+  /**
+   * Longest depends_on chain rooted at a task, by summed hours (memoized, cycle-guarded).
+   * @param {string} id - Task id to start from.
+   * @param {Set<string>} [seen=new Set()] - Ids on the current DFS path (cycle guard); callers omit it.
+   * @returns {{hours:number, chain:string[]}} The heaviest chain's total hours and its task ids in
+   *   dependency order; {hours:0, chain:[]} for an unknown id or a detected cycle.
+   */
+  const longest = (id, seen = new Set()) => {
+    if (memo[id]) return memo[id];
+    if (seen.has(id)) return { hours: 0, chain: [] }; // cycle guard — lint reports it separately
+    seen.add(id);
+    const t = byId[id];
+    if (!t) return { hours: 0, chain: [] };
+    let best = { hours: 0, chain: [] };
+    for (const dep of t.depends_on) {
+      const c = longest(dep, seen);
+      if (c.hours > best.hours) best = c;
+    }
+    return (memo[id] = { hours: best.hours + t.hours, chain: [...best.chain, id] });
+  };
+  let best = { hours: 0, chain: [] };
+  for (const t of tasks) {
+    const c = longest(t.id);
+    if (c.hours > best.hours) best = c;
+  }
+  return best;
+}
+
+/**
+ * Flag board-vs-T0 drift: FINISHED scopes whose named tasks are not yet done (flag only, never fix).
+ * @param {Array<{id:string, status:string}>} tasks - The parsed board.
+ * @param {Array<{scope_id:string, tasks?:string[], finished?:boolean}>} scopes - Scope facts.
+ * @returns {Array<{scope_id:string, task_id:string, status:string}>} One entry per drifting task; [] when none.
+ */
+export function driftCheck(tasks, scopes) {
+  const byId = Object.fromEntries(tasks.map((t) => [t.id, t]));
+  const drift = [];
+  for (const s of scopes) {
+    if (!Array.isArray(s.tasks) || !s.finished) continue;
+    for (const id of s.tasks) {
+      const t = byId[id];
+      if (t && t.status !== "done") drift.push({ scope_id: s.scope_id, task_id: id, status: t.status });
+    }
+  }
+  return drift;
+}
+
+/**
+ * Derive the full board report (unlocks, hours, packages, critical path, appetite overflow, drift).
+ * @param {{cwd:string, slug:string, appetiteHours?:(number|null)}} opts - Working root, feature
+ *   slug, and optional appetite budget (in hours) that drives the overflow flag.
+ * @returns {object} The report: task_count, by_status, packages, total/keep hours, appetite
+ *   overflow (or null), critical_path, unlocks + unlocks_stale, drift[], and `_tasks` (the parsed
+ *   board, deleted before CLI output).
+ */
+export function derive({ cwd, slug, appetiteHours = null }) {
+  const tasksDir = tasksDir(cwd, slug);
+  const tasks = parseBoard(tasksDir);
+  const unlocks = deriveUnlocks(tasks);
+  const keepHours = tasks.filter((t) => t.status !== "cut").reduce((a, t) => a + t.hours, 0);
+  const packages = {};
+  for (const t of tasks) packages[t.pkg || "(none)"] = (packages[t.pkg || "(none)"] || 0) + 1;
+
+  // Scope facts for the drift check: contract `tasks` list + committed hill shard phase.
+  const hillRoot = hillDir(cwd, slug);
+  const scopes = readAllContracts(scopesDir(cwd, slug), SCOPE_CONTRACT).map(({ contract }) => {
+    const shard = join(hillRoot, `${contract.scope_id}.yml`);
+    const finished = existsSync(shard) && /phase:\s*FINISHED/.test(readFileSync(shard, "utf8"));
+    return { ...contract, finished };
+  });
+
+  return {
+    slug,
+    task_count: tasks.length,
+    by_status: tasks.reduce((m, t) => ((m[t.status] = (m[t.status] || 0) + 1), m), {}),
+    packages,
+    total_hours: tasks.reduce((a, t) => a + t.hours, 0),
+    keep_hours: keepHours,
+    appetite: appetiteHours === null ? null : {
+      appetite_hours: appetiteHours,
+      overflow: keepHours > appetiteHours,
+      overflow_hours: Math.max(0, keepHours - appetiteHours),
+    },
+    critical_path: criticalPath(tasks),
+    unlocks,
+    unlocks_stale: tasks.filter((t) => JSON.stringify([...t.unlocks].sort()) !== JSON.stringify(unlocks[t.id])).map((t) => t.id),
+    drift: driftCheck(tasks, scopes),
+    _tasks: tasks,
+  };
+}
+
+/**
+ * Persist derived `unlocks` into task frontmatter — the ONE write this script makes.
+ * @param {{_tasks:Array<object>, unlocks:Object<string,string[]>}} report - A {@link derive} report.
+ * @returns {string[]} The ids of task files actually rewritten (unchanged files are skipped).
+ *   Side effect: writes those task files.
+ */
+export function writeUnlocks(report) {
+  const written = [];
+  for (const t of report._tasks) {
+    const want = `[${report.unlocks[t.id].join(", ")}]`;
+    const fmMatch = t.body.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fmMatch) continue;
+    const fm = fmMatch[1];
+    const next = /^unlocks:.*$/m.test(fm) ? fm.replace(/^unlocks:.*$/m, `unlocks: ${want}`) : `${fm}\nunlocks: ${want}`;
+    if (next !== fm) {
+      writeFileSync(t.file, t.body.replace(fm, next));
+      written.push(t.id);
+    }
+  }
+  return written;
+}
+
+/** The typed argv contract (see `skills/tech-lead/scripts/lib/argv.mjs`). */
+export const ARGV_SPEC = {
+  usage: "board-derive.mjs --slug <slug> [--cwd <dir>] [--write] [--appetite-hours N]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str", required: true },
+  cwd: { type: "path" },
+  write: { type: "flag" },
+  "appetite-hours": { type: "num", min: 0 },
+};
+
+const isMainModule = isMain(import.meta.url);
+if (isMainModule) {
+  const args = runArgs(ARGV_SPEC);
+  const cwd = resolve(args.cwd || process.cwd());
+  const report = derive({ cwd, slug: args.slug, appetiteHours: args.appetiteHours ?? null });
+  if (args.write) report.unlocks_written = writeUnlocks(report);
+  delete report._tasks;
+  console.log(JSON.stringify(report, null, 2));
+}