@hegemonart/get-design-done 1.27.6 → 1.27.7

package/scripts/mcp-servers/gdd-mcp/tools/gdd_phases_list.ts

@@ -0,0 +1,26 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_phases_list.ts
+//
+// Plan 27.7-02. Parses .planning/ROADMAP.md via scripts/lib/roadmap-reader.
+
+import {
+  readRoadmapMd,
+  parsePhases,
+} from '../../../lib/roadmap-reader/index.cjs';
+import {
+  errorResponse,
+  okResponse,
+  resolveProjectRoot,
+  type ToolResponse,
+} from './shared.ts';
+
+export const name = 'gdd_phases_list';
+export const schemaPath = '../schemas/gdd_phases_list.schema.json';
+
+export async function handle(_input: unknown): Promise<ToolResponse> {
+  try {
+    const md = await readRoadmapMd(resolveProjectRoot());
+    return okResponse({ phases: parsePhases(md) });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-mcp/tools/gdd_plans_list.ts

@@ -0,0 +1,39 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_plans_list.ts
+//
+// Plan 27.7-02. STATE.md does not have a dedicated <plans> block — we
+// surface must_haves as the closest analog (the per-plan acceptance
+// criteria the pipeline tracks). Input.phase is reserved for future
+// multi-phase indexing.
+
+import { read } from '../../../lib/gdd-state/index.ts';
+import {
+  errorResponse,
+  okResponse,
+  resolveStatePath,
+  type ToolResponse,
+} from './shared.ts';
+
+export const name = 'gdd_plans_list';
+export const schemaPath = '../schemas/gdd_plans_list.schema.json';
+
+interface PlansInput {
+  phase?: string;
+}
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const typed = (input ?? {}) as PlansInput;
+    const state = await read(resolveStatePath());
+    const plans = (state.must_haves ?? []).map((m) => ({
+      id: m.id,
+      name: m.text,
+      status: m.status,
+    }));
+    return okResponse({
+      phase: typed.phase ?? state.frontmatter.cycle ?? null,
+      plans,
+    });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-mcp/tools/gdd_reflections_latest.ts

@@ -0,0 +1,25 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_reflections_latest.ts
+//
+// Plan 27.7-02. Reads newest reflection under .design/reflections/.
+// ReflectionsNotFoundError surfaces as mcp_code='directory_not_found'
+// via errorResponse (Warning #5).
+
+import { readLatestReflection } from '../../../lib/reflections-reader/index.cjs';
+import { errorResponse, okResponse, resolveProjectRoot, type ToolResponse } from './shared.ts';
+
+export const name = 'gdd_reflections_latest';
+export const schemaPath = '../schemas/gdd_reflections_latest.schema.json';
+
+export async function handle(_input: unknown): Promise<ToolResponse> {
+  try {
+    const r = await readLatestReflection(resolveProjectRoot());
+    if (r === null) return okResponse({ cycle: null, path: null, content_excerpt: '' });
+    return okResponse({
+      cycle: r.cycle,
+      path: r.path,
+      content_excerpt: r.content.slice(0, 4096),
+    });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-mcp/tools/gdd_status.ts

@@ -0,0 +1,31 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_status.ts
+//
+// Plan 27.7-02. Thin wrapper over scripts/lib/gdd-state. NO fs/path
+// imports here — all I/O via gdd-state.read() + shared.ts helpers.
+
+import { read } from '../../../lib/gdd-state/index.ts';
+import {
+  errorResponse,
+  okResponse,
+  resolveStatePath,
+  type ToolResponse,
+} from './shared.ts';
+
+export const name = 'gdd_status';
+export const schemaPath = '../schemas/gdd_status.schema.json';
+
+export async function handle(_input: unknown): Promise<ToolResponse> {
+  try {
+    const state = await read(resolveStatePath());
+    const completed = (state.must_haves ?? []).filter((m) => m.status === 'pass');
+    return okResponse({
+      phase: state.frontmatter.cycle ?? null,
+      branch: process.env['GIT_BRANCH'] ?? null,
+      last_decisions: (state.decisions ?? []).slice(-3),
+      last_completed_plans: completed.slice(-3),
+      blocker_count: (state.blockers ?? []).length,
+    });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-mcp/tools/gdd_telemetry_query.ts

@@ -0,0 +1,27 @@
+// scripts/mcp-servers/gdd-mcp/tools/gdd_telemetry_query.ts
+//
+// Plan 27.7-02. Typed reader over .design/telemetry/*.jsonl via
+// scripts/lib/event-stream/index.ts readEvents.
+
+import { readEvents } from '../../../lib/event-stream/index.ts';
+import { errorResponse, okResponse, resolveTelemetryDir, type ToolResponse } from './shared.ts';
+
+export const name = 'gdd_telemetry_query';
+export const schemaPath = '../schemas/gdd_telemetry_query.schema.json';
+
+interface TelemetryInput { type?: string; since?: string; limit?: number; }
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const typed = (input ?? {}) as TelemetryInput;
+    const limit = typeof typed.limit === 'number' && typed.limit > 0 ? typed.limit : 100;
+    const events: unknown[] = [];
+    const opts: { path: string; type?: string; since?: string } = { path: resolveTelemetryDir() + '/events.jsonl' };
+    if (typeof typed.type === 'string' && typed.type.length > 0) opts.type = typed.type;
+    if (typeof typed.since === 'string' && typed.since.length > 0) opts.since = typed.since;
+    for await (const ev of readEvents(opts)) { events.push(ev); if (events.length >= limit) break; }
+    return okResponse({ events });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/mcp-servers/gdd-mcp/tools/index.ts

@@ -0,0 +1,75 @@
+// scripts/mcp-servers/gdd-mcp/tools/index.ts
+//
+// Tool registry for `gdd-mcp`. Plan 27.7-02 populates with 12 read-only
+// tools. The 12-tool cap is D-03 (hard); enforced at module load by a
+// runtime check + by tests in Plan 27.7-03.
+//
+// Convention (mirrors Phase 20 `gdd-state`):
+//   - Each tool exports `name`, `schemaPath`, and `handle` from its own
+//     module (e.g. `./gdd_status.ts`).
+//   - `schemaPath` is relative to THIS file's directory and points into
+//     `scripts/mcp-servers/gdd-mcp/schemas/`. Server.ts joins it
+//     against `<baseDir>/tools/` to load the Draft-07 JSON.
+//   - `TOOL_MODULES` is the canonical registry — server.ts iterates it
+//     once at startup to populate the dispatch map.
+
+import type { ToolResponse } from './shared.ts';
+
+import * as gdd_cycle_recap from './gdd_cycle_recap.ts';
+import * as gdd_decisions_list from './gdd_decisions_list.ts';
+import * as gdd_events_tail from './gdd_events_tail.ts';
+import * as gdd_health from './gdd_health.ts';
+import * as gdd_intel_get from './gdd_intel_get.ts';
+import * as gdd_learnings_digest from './gdd_learnings_digest.ts';
+import * as gdd_phase_current from './gdd_phase_current.ts';
+import * as gdd_phases_list from './gdd_phases_list.ts';
+import * as gdd_plans_list from './gdd_plans_list.ts';
+import * as gdd_reflections_latest from './gdd_reflections_latest.ts';
+import * as gdd_status from './gdd_status.ts';
+import * as gdd_telemetry_query from './gdd_telemetry_query.ts';
+
+export interface ToolModule {
+  /** Public tool name exposed via MCP (e.g. "gdd_status"). */
+  name: string;
+  /** Path to the input/output Draft-07 JSON Schema, relative to this
+   *  module's directory. Per-tool entries under `../schemas/`. */
+  schemaPath: string;
+  /** Executes the tool. Never throws — always returns a ToolResponse. */
+  handle: (input: unknown) => Promise<ToolResponse>;
+}
+
+/**
+ * Canonical tool registry. 12 tools (D-03 hard cap). Order is
+ * alphabetical (after `gdd_status` which leads as the canonical entry).
+ * All tools are advertised equivalently in `tools/list`.
+ */
+export const TOOL_MODULES: readonly ToolModule[] = [
+  gdd_status,
+  gdd_cycle_recap,
+  gdd_decisions_list,
+  gdd_events_tail,
+  gdd_health,
+  gdd_intel_get,
+  gdd_learnings_digest,
+  gdd_phase_current,
+  gdd_phases_list,
+  gdd_plans_list,
+  gdd_reflections_latest,
+  gdd_telemetry_query,
+] as const;
+
+/** Canonical count. The plan caps this at 12 — if you add a tool past
+ *  that bound, update the plan, the combined schema, and the lint
+ *  test (Plan 27.7-03). */
+export const TOOL_COUNT: number = TOOL_MODULES.length;
+
+// Module-load runtime assertion of the 12-tool cap (D-03). A compile-time
+// type guard is fragile against `readonly ToolModule[]` (the length type
+// widens to `number`); the runtime check is cheap, deterministic, and
+// fails fast on server boot if the registry ever drifts past the cap.
+if (TOOL_COUNT > 12) {
+  throw new Error(
+    `gdd-mcp: TOOL_COUNT=${TOOL_COUNT} exceeds the 12-tool cap (D-03). ` +
+      'Add tool past 12 requires re-scoping in a new plan.',
+  );
+}

package/scripts/mcp-servers/gdd-mcp/tools/shared.ts

@@ -0,0 +1,134 @@
+// scripts/mcp-servers/gdd-mcp/tools/shared.ts
+//
+// Shared helpers for gdd-mcp tools. resolveProjectRoot() implements the
+// D-05 walk-up algorithm: scan from process.cwd() upward looking for
+// `.design/` OR `.planning/` OR `.claude-plugin/plugin.json` — first
+// match wins. Override: if process.env.GDD_PROJECT_ROOT is set, return
+// it without walking.
+//
+// shared.ts itself is server-side infrastructure (it's the helper layer
+// for tools, not a tool); it MAY import `node:fs` and `node:path`
+// directly. The thin-wrapper rule (D-06) and the lint that will land
+// in Plan 27.7-03 target individual TOOL files in this same directory,
+// NOT this shared helper module.
+
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import { toToolError } from '../../../lib/gdd-errors/classification.ts';
+import type { ToolErrorPayload } from '../../../lib/gdd-errors/classification.ts';
+
+/** Public tool-handler response shape (consistent across all tools). */
+export type ToolResponse =
+  | { success: true; data: Record<string, unknown> }
+  | { success: false; error: ToolErrorPayload['error'] };
+
+/**
+ * Shorthand for a `{success:true, data}` return with a plain object.
+ */
+export function okResponse(data: Record<string, unknown>): ToolResponse {
+  return { success: true, data };
+}
+
+/**
+ * Map an error into a tool-response `{success:false, error}` object.
+ * Single entry point for every handler — keeps the error-shape decision
+ * in one place.
+ *
+ * Plan 27.7-02 Warning #5 projection: when the underlying error carries
+ * a `code === 'directory_not_found'` property (set by
+ * SnapshotNotFoundError / IntelNotFoundError / ReflectionsNotFoundError),
+ * we surface it as `error.mcp_code` so MCP clients can distinguish a
+ * missing-data-source from a genuine bug. The original `code`/`kind`
+ * pair stays intact for the GDD error taxonomy.
+ */
+export function errorResponse(err: unknown): ToolResponse {
+  const payload = toToolError(err);
+  if (
+    typeof err === 'object' &&
+    err !== null &&
+    'code' in err &&
+    (err as { code?: unknown }).code === 'directory_not_found'
+  ) {
+    const error = { ...payload.error, mcp_code: 'directory_not_found' };
+    return { success: false, error: error as ToolErrorPayload['error'] };
+  }
+  return { success: false, error: payload.error };
+}
+
+/**
+ * Resolve <root>/.design/STATE.md. State path can be pinned via
+ * `process.env.GDD_STATE_PATH` (mirrors the gdd-state server).
+ */
+export function resolveStatePath(): string {
+  const override = process.env['GDD_STATE_PATH'];
+  if (typeof override === 'string' && override.length > 0) {
+    return override;
+  }
+  return join(resolveProjectRoot(), '.design', 'STATE.md');
+}
+
+/** Resolve <root>/.planning/ROADMAP.md. */
+export function resolveRoadmapPath(): string {
+  return join(resolveProjectRoot(), '.planning', 'ROADMAP.md');
+}
+
+/** Resolve <root>/.design/intel. */
+export function resolveIntelDir(): string {
+  return join(resolveProjectRoot(), '.design', 'intel');
+}
+
+/** Resolve <root>/.design/telemetry. */
+export function resolveTelemetryDir(): string {
+  return join(resolveProjectRoot(), '.design', 'telemetry');
+}
+
+/** Resolve <root>/.design/reflections. */
+export function resolveReflectionsDir(): string {
+  return join(resolveProjectRoot(), '.design', 'reflections');
+}
+
+/** Resolve <root>/.design/snapshots. */
+export function resolveSnapshotsDir(): string {
+  return join(resolveProjectRoot(), '.design', 'snapshots');
+}
+
+/**
+ * Walk up from a starting directory looking for any of the three GDD
+ * project markers: `.design/`, `.planning/`, or `.claude-plugin/plugin.json`.
+ * First match wins; resolves to the absolute path of the directory that
+ * contains the marker.
+ *
+ * Override: `process.env.GDD_PROJECT_ROOT` short-circuits the walk and
+ * is returned verbatim (after path resolution). This is useful for
+ * tests and for users who want to pin a project root explicitly.
+ *
+ * Throws `Error('gdd project root not found: ...')` when no marker is
+ * found before the filesystem root. Callers in tool handlers should
+ * catch and forward via `errorResponse()`.
+ */
+export function resolveProjectRoot(startCwd: string = process.cwd()): string {
+  const override = process.env['GDD_PROJECT_ROOT'];
+  if (typeof override === 'string' && override.length > 0) {
+    return resolve(override);
+  }
+
+  let dir = resolve(startCwd);
+  while (true) {
+    if (
+      existsSync(join(dir, '.design')) ||
+      existsSync(join(dir, '.planning')) ||
+      existsSync(join(dir, '.claude-plugin', 'plugin.json'))
+    ) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      // Reached filesystem root — give up.
+      throw new Error(
+        `gdd project root not found: walked up to ${dir} from ${startCwd}`,
+      );
+    }
+    dir = parent;
+  }
+}

package/skills/health/SKILL.md

@@ -52,6 +52,42 @@ Health: 5 / 6 checks passing.
 ━━━━━━━━━━━━━━━━━━━━━
 ```
 
+<step name="check-mcp-registration">
+
+## Check MCP registration (gdd-mcp)
+
+This step inspects whether `gdd-mcp` (Phase 27.7+) is registered with any installed harness and renders a one-line status row after the health table. Dismissable via `.design/config.json#mcp_nudge=false`. This step is non-blocking: a fail-safe fallback ensures malformed config or missing harness settings MUST NOT crash the SKILL — skip silently to `unknown` status when anything goes wrong.
+
+### Dismissal check
+
+1. Read `.design/config.json` (if present). Parse JSON inside a try/catch.
+2. If `config.mcp_nudge === false`, SKIP this step entirely (render nothing).
+3. On parse failure: default to `mcp_nudge=true` (show the row) — fail-safe per threat T-27.7-04-05.
+
+### Detection
+
+1. Read `.claude/settings.local.json` (or equivalent harness settings file) and inspect its `mcpServers` object — alternatively run `claude mcp list` / `codex mcp list` if a CLI is available (see fallback below).
+2. Preferred invocation via the install-lib: call `detectMcpRegistration()` from `scripts/lib/install/mcp-register.cjs`. Returns `{harnesses: [{harness, present, registered}], summary}`.
+
+### Row rendering
+
+Based on the detection result, render exactly ONE of these row strings:
+
+- When `claude` and `codex` both present + both registered:
+  `MCP server: registered with claude+codex`
+- When only one harness is present and registered:
+  `MCP server: registered with claude` (or `MCP server: registered with codex`)
+- When at least one harness is present but `gdd-mcp` is NOT in its registered list:
+  `MCP server: not registered  (run: npx @hegemonart/get-design-done --register-mcp; dismiss: .design/config.json#mcp_nudge=false)`
+- When neither harness CLI is found on PATH:
+  `MCP server: unknown (claude/codex CLI not found)`
+
+### Fallback (if `mcp-register.cjs` not yet shipped)
+
+Skip this step silently with status `MCP server: unknown`. This step is non-blocking — failures here MUST NOT crash the SKILL.
+
+</step>
+
 ## Update notice (safe-window surface)
 
 After the health table, emit the plugin-update banner if one is present:

package/skills/next/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gdd-next
 description: "Routes to the next pipeline stage based on current STATE.md position"
-tools: Read, Write
+tools: Read, Write, mcp__gdd_status, mcp__gdd_phase_current, mcp__gdd_plans_list
 ---
 
 # Get Design Done — Next
@@ -12,9 +12,32 @@ tools: Read, Write
 
 ## Logic
 
+Two paths — MCP preferred when available, file-read fallback otherwise.
+
+### MCP path (preferred)
+
+When `mcp__gdd_phase_current` is exposed (Phase 27.7+, registered via `npx @hegemonart/get-design-done --register-mcp`):
+
+1. Call `mcp__gdd_status` (no args) → `{phase, branch, last_decisions, last_completed_plans, blocker_count}`. Gives cycle + branch context for the output block in one call.
+2. Call `mcp__gdd_phase_current` (no args) → `{phase, stage, task_progress, status}`. Use `stage` to drive the routing table below.
+3. (Optional) Call `mcp__gdd_plans_list` (no args) → current phase plans + status, to identify the next incomplete plan and refine the recommendation.
+4. If `mcp__gdd_status` returns a "STATE.md missing" error, print: "No STATE.md found. Run `/gdd:new-project` to initialize, or `@get-design-done brief` to start the pipeline." and stop. Otherwise, skip to the routing table.
+
+Two to three MCP calls = full routing decision (~3s, ~32k tokens — Storybloq benchmark).
+
+### File-read path (fallback)
+
+When MCP tools are not available, fall back to the legacy flow:
+
 1. Check if `.design/STATE.md` exists.
    - **No STATE.md** → Print: "No STATE.md found. Run `/gdd:new-project` to initialize, or `@get-design-done brief` to start the pipeline."
-2. If STATE.md exists, parse frontmatter `stage:` field and map:
+2. If STATE.md exists, parse frontmatter `stage:` field. Proceed to the routing table.
+
+This path loads the same context in 1–2 file reads (~20s, ~46.5k tokens — file-reading baseline).
+
+## Routing table
+
+Map the `stage` (from either path above) to the next recommended command:
 
 | Current `stage:` | Recommendation |
 |---|---|
@@ -24,7 +47,9 @@ tools: Read, Write
 | `design` | Run `@get-design-done verify` to audit and verify |
 | `verify` | Pipeline complete. Run `/gdd:new-cycle` for next cycle or `/gdd:ship` to create PR |
 
-3. Print the recommendation as a single formatted block:
+## Output
+
+Print the recommendation as a single formatted block:
 
 ```
 ━━━ Next step ━━━

package/skills/progress/SKILL.md

@@ -2,7 +2,7 @@
 name: gdd-progress
 description: "Shows current pipeline position and routes to next action. --forensic runs 6-check integrity audit."
 argument-hint: "[--forensic]"
-tools: Read, Bash, Grep, Glob, mcp__gdd_state__get
+tools: Read, Bash, Grep, Glob, mcp__gdd_state__get, mcp__gdd_status, mcp__gdd_phase_current
 ---
 
 @reference/retrieval-contract.md
@@ -13,12 +13,27 @@ tools: Read, Bash, Grep, Glob, mcp__gdd_state__get
 
 ## Step 1 — Read state
 
-Call `mcp__gdd_state__get` → parsed state object. Extract:
-- `stage`, `cycle`, `last_checkpoint`
-- `task_progress`, `status` (from `<position>`)
-- `decisions.length`, open todos from `.design/TODO.md` (count unchecked `- [ ]` — this file is outside the MCP catalog, so `Read` is still used)
+Two paths — MCP preferred when available, file-read fallback otherwise.
 
-If `mcp__gdd_state__get` returns a "STATE.md missing" error, print: "No pipeline state. Run `/gdd:brief` first." and stop.
+### MCP path (preferred)
+
+When the harness exposes `mcp__gdd_status` (Phase 27.7+, registered via `npx @hegemonart/get-design-done --register-mcp`):
+
+1. Call `mcp__gdd_status` (no args). Returns `{phase, branch, last_decisions, last_completed_plans, blocker_count}` in one call.
+2. If you need `stage` / `task_progress` for the output line, call `mcp__gdd_phase_current` (no args). Returns `{phase, stage, task_progress, status}`.
+3. Skip to Step 2.
+
+This path loads the full priming context in 1–2 MCP calls (~3s, ~32k tokens — Storybloq benchmark).
+
+### File-read path (fallback)
+
+When MCP tools are not available, fall back to the legacy flow:
+
+1. Call `mcp__gdd_state__get` if exposed (Phase 20 STATE.md mutator MCP) → parsed state object. Otherwise, `Read .design/STATE.md` and parse the frontmatter + `<position>`, `<decisions>`, `<plans>` sections.
+2. Extract: `stage`, `cycle`, `last_checkpoint`, `task_progress`, `status`, `decisions.length`, open todos from `.design/TODO.md` (count unchecked `- [ ]` — outside the MCP catalog, so `Read` is still used).
+3. If STATE.md is missing, print: "No pipeline state. Run `/gdd:brief` first." and stop.
+
+This path loads the same context in 5–10 file reads (~100s, ~46.5k tokens — file-reading baseline).
 
 ## Step 2 — Default output
 

package/skills/resume/SKILL.md

@@ -2,7 +2,7 @@
 name: gdd-resume
 description: "Restore session context from a numbered checkpoint. Lists available checkpoints when no argument given."
 argument-hint: "[<N>]"
-tools: Read, Write, Bash, Glob, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__set_status, mcp__gdd_state__resolve_blocker, mcp__gdd_state__checkpoint
+tools: Read, Write, Bash, Glob, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__set_status, mcp__gdd_state__resolve_blocker, mcp__gdd_state__checkpoint, mcp__gdd_status, mcp__gdd_phase_current, mcp__gdd_plans_list, mcp__gdd_decisions_list
 ---
 
 @reference/retrieval-contract.md
@@ -12,6 +12,31 @@ tools: Read, Write, Bash, Glob, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_s
 
 Inverse of `/gdd:pause`. Reads a checkpoint file, prints a clear "you were here" summary, and routes to the next command.
 
+## Step 0 — Prime cycle context
+
+Two paths — MCP preferred when available, file-read fallback otherwise. This runs BEFORE checkpoint restoration so the "you were here" summary has full cycle context (phase, plans, decisions).
+
+### MCP path (preferred)
+
+When `mcp__gdd_status` is exposed (Phase 27.7+, registered via `npx @hegemonart/get-design-done --register-mcp`):
+
+1. Call `mcp__gdd_status` (no args) → `{phase, branch, last_decisions, last_completed_plans, blocker_count}`. One call replaces reading STATE.md + parsing frontmatter + extracting decisions.
+2. Call `mcp__gdd_cycle_recap` (no args) → diff vs last cycle snapshot. Critical for session-restoration context: what changed since you paused?
+3. Call `mcp__gdd_decisions_list` (no args) → full D-XX list with rationale. Use for the "decisions you made" line in the resume summary.
+4. (Optional) Call `mcp__gdd_plans_list` (no args) → current phase plans + status, to identify next incomplete plan.
+
+Three to four MCP calls = full resume priming (~5s, ~32k tokens — Storybloq benchmark). Proceed to Step 1.
+
+### File-read path (fallback)
+
+When MCP tools are not available:
+
+1. `Read .design/STATE.md` and parse the frontmatter + `<position>`, `<decisions>`, `<plans>` sections. Extract `cycle`, `branch`, `last N decisions`, `completed plans`.
+2. Also `Read .design/CYCLES.md` (if present) to see prior cycle state for the recap.
+3. Proceed to Step 1.
+
+This path loads the same context in 3–5 file reads (~60s, ~46.5k tokens — file-reading baseline).
+
 ## Steps
 
 1. **Parse argument**: