/alignment-check

Alignment Check

**Before reading further, print this status line so the user sees a progress signal during the upcoming reasoning pass:**

> *Working through the alignment loop - investigating where this story fits in the codebase, can take 30-90 seconds...*

You are running the codebase alignment check for a story. This is the engineer-to-product-manager handshake - you spawn an Explore agent to investigate the codebase where this work will land, and surface every product question that only the user can answer.

Definition: 95% Alignment

**95% alignment means: "I have asked the user every question the codebase raised that only they can answer."**

It is NOT about:

• Whether the solution approach is right (that's your job as the engineer)
• Whether the chunks will work (that's plan-chunks' job)
• Whether the code will compile (that's validation's job)

It IS about:

• **Conflicts discovered** - "Found existing X - replace, update, or coexist?" → asked
• **Adjacencies & suggestions** - "This pattern exists in N other places - apply there too?" → asked
• **Assumptions surfaced** - "You said X but the codebase implies Y - which is it?" → asked
• **Scope implications confirmed** - "Your answers expanded this - split or keep?" → asked

**The gate is not "do I feel confident?" It's "do I have zero unasked product questions?"**

Product questions go to the user. Engineering questions you solve yourself. The gate measures whether the user's intent is fully captured - not whether you know how to build it.

When This Runs

• During `craft-story-new` Step 8 (when user chose "Keep designing", before acceptance criteria)
• During `craft-cycle-design` per-story (before plan-chunks)
• During `plan-chunks` Phase 0 (if `alignment: pending` in story frontmatter - catches stories that skipped the check during creation)

Prerequisites

Before starting, you need: 1. The story file path (to read the spark, decisions, scope) 2. The story's `## Likely Files` section (if it exists - gives a starting point for investigation) 3. Any decisions captured so far

The Loop

Before Step 0: Research What Nobody in the Room Knows

Read the spark. If the story's work depends on something outside the project whose behavior nobody here has checked (a site, a person, a tool's output, a data source, a format), grep the project, `.craft/research/` and the story's Reference Materials for it. If they hold nothing, settle it; if a research folder already answers it, cite it onto the story instead of researching again. No such thing named, or it is already held: print nothing and go on to Step 0.

• **One fact** (one thing, one answer): at most three web searches, then say `Checked: <fact> (<source>).` in one line as you move on - it is not a question. Step 6 records it as `- OUTSIDE FACT: <fact> - <source>`.
• **Anything bigger** (a claim about a whole class, or a fact still open after three searches): Read `commands/references/research-inline.md` (a sibling of this file - resolve it against the absolute path you Read this file from) with `QUERY` the outside premise, `STORY` the story's absolute path and `DOOR=alignment`. Pass `DEPTH=--quick` for one bounded thing with few angles, no flag for a claim about a class ("every runner", "all providers"). Continue at Step 0 with the research in hand.
• **One run per door:** if the story's Reference Materials already holds a run line with `alignment door` and the gap is still open, never run again; ask the user on a question card (Step 3) what the story should assume.

Step 0: Empty-Codebase Short-Circuit

Before spawning the Explore agent, check whether the codebase has any source files. An empty codebase has zero adjacencies to find — running Explore would burn time and tokens to confirm there's nothing to find.

**Check (rough):** Look for any files outside `.craft/`, `.claude/`, `node_modules/`, `.git/`, and root-level dotfiles. Bash one-liner option:

find . -type f \
  -not -path './.craft/*' \
  -not -path './.claude/*' \
  -not -path './node_modules/*' \
  -not -path './.git/*' \
  -not -name '.*' \
  | head -1

If the result is empty: **skip Step 1 entirely.** There's no codebase to investigate.

**Where product questions come from on an empty codebase:**

Read the story's `## Notes` section (populated during cycle-design Phase 2a's brainstorm). Open questions raised during the brainstorm — naming choices, scope questions, data shape decisions — are the natural source of product questions for greenfield work.

After harvesting questions from the Notes section, **skip ahead to Step 3 (Surface Gaps on Question Cards)** to surface them to the user.

If the codebase has any source files: continue to Step 0.5 as normal.

Step 0.5: Planning Context Injection

Before spawning the Explore agent, check whether this story was created from a planning concept or carries approved decision records or research. If so, build a Planning Context block from the story's Reference Materials, and hand decision records to the agent as paths (see 4a - they never enter the block or its token cap), so the agent doesn't surface false-positive product questions for decisions already captured in planning.

**Detection:** Read the story frontmatter. If `source_concept:` is populated OR the story's `decisions:` list is non-empty OR its `## Reference Materials` holds at least one citation entry (a `- ` line; the template's comment alone does not count), continue with the injection below. Otherwise, skip directly to Step 1 with the existing prompt unchanged.

**Build the Planning Context block (orchestrator-level work, NOT delegated to the Explore agent):**

1. Read the story's `## Reference Materials` section.

2. Parse each citation: extract the file path + anchor(s). Citations may have multiple anchors per file (multi-anchor format - see plan-chunks-agent.md section 1.3.5 for the contract).

3. For each cited file + anchor, use **Read** with the anchor to extract the exc