Plan Milestone

Factory mode: If CLAUDE_AUTO is set in the environment, skip these instructions and instead run ./{scripts_dir}/skills/plan-milestone.sh "$@" via Bash — the shell script handles autonomous dispatch.

MCP Tool Map (Gemini/Codex): See .claude/skills/_shared/mcp-tool-map.md for tool name equivalents.

Plan Milestone — Epic & Task Breakdown

Takes a milestone goal and produces a full execution plan: epics with dependency ordering, tasks with test criteria, and task manager tickets ready for the factory.

Milestone Naming Rule — HARD GATE

Milestone titles must describe a CAPABILITY being added, not a STATE being reached.

The recurring failure mode is the "DAT004→008" pattern: milestones named Finish the Schema, Complete Phase 10, Wrap up the cleanup are open-ended buckets that absorb scope until they're marked Done without ever shipping a discrete capability. Capability names force a clear acceptance test (Add Lineage Tracking → "lineage column exists, populated for all rows").

Rejected patterns (regex enforced before milestone creation)

Canonical regex (case-insensitive — apply with (?i) inline flag or /.../i in JS-style engines). Markdown escapes the pipes in the table above; the raw patterns are:

^(Finish|Complete|Close|Wrap[- ]up|Finalize)\b
^Final\b

Plus literal substring checks (case-insensitive) for: the schema, the cleanup, the audit, remaining work.

Required pattern

Title MUST start with an action verb describing the capability added:

Add · Build · Enable · Ship · Deploy · Migrate · Lock-in · Harden · Retire · Replace · Extract · Introduce · Wire

The skill MUST refuse to create a milestone whose title matches a rejected pattern. Surface the regex hit, suggest the verb list, and force the operator to rename before save_milestone is called.

Step 0: Load Project Context (MANDATORY)

Before any planning, read .claude/project-context.md to get:

• task_manager — which adapter to use
• task_prefix — ticket prefix (e.g. APP, BEN, WEB)
• task_team_id — team/project identifier
• milestone_noun — what this project calls milestones
• main_branch — PR target branch
• areas — project area codes (if defined)
• storage_backend — load .claude/skills/_shared/storage/{storage_backend}.md; route all memory reads/writes (record_decision, list_decisions, save_task_plan, record_test_run, …) through its operations. Absent → none (reads empty, writes discarded). storage_schema_intel/storage_schema_qa name the namespaces (defaults intel/qa).
• agents — capability→agent map; reference agents below as {agents.<capability>}. Absent → template defaults (completion_audit: completion-audit, spec_audit: spec-audit, pragmatism_audit: pragmatism-audit, scalability_audit: future-self). If a mapped agent is unavailable, skip that step with a logged note.

Then load the task manager adapter:

Read.claude/skills/_shared/adapters/{task_manager}.md

If .claude/project-context.md is missing: stop and tell the user to run /project-init first.

GATE ENFORCEMENT: This skill is the ONLY path to write task manager issues. A PreToolUse hook (guard-task-writes.sh) blocks task creation calls unless .claude/.plan-milestone-active exists. This skill creates that flag on entry and removes it on exit.

Step 0b (MANDATORY — before any planning):

touch.claude/.plan-milestone-active

Final step (MANDATORY — after all issues created):

rm -f.claude/.plan-milestone-active

Naming Conventions (CRITICAL)

Milestone IDs — {AREA_CODE}{3D}{LETTER}

Format: 3-letter area code + 3-digit sequence + letter suffix.

Area codes are defined per project in .claude/project-context.md under areas:. If no areas are defined, auto-derive the code from the area name:

Auto-derivation rules (applied in order):
1. Split area name into words
2. If multi-word: take first letter of each word, uppercase, max 3 chars
   "Computer Vision" → CV → pad to CVX? No — use first 3 letters of each word initial: CVX
   "Machine Learning" → ML → MLX (pad single/double initials to 3 with X)
   "Analytics" → ANL (first 3 consonant-rich chars)
3. If single word ≤ 3 chars: uppercase as-is
4. If single word > 3 chars: first 3 chars, uppercase
   "Analytics" → ANL  |  "Factory" → FCT  |  "Platform" → PLT
5. Confirm with user before creating first milestone in a new area

Sequence is auto-incremented: fetch existing milestones for this area from the task manager, find the highest sequence number, add 1. Start at 001 for new areas.

Examples (after derivation):

Computer Vision, seq 5, phase A  →  CVX005A
Machine Learning, seq 4, phase A →  MLX004A
Factory, seq 3, phase A          →  FCT003A

Z suffix = hardening/verification milestone (e.g. CVX005Z — Verify CV Pipeline E2E). NEVER use decimal suffixes. Increment the letter (A→B→C…) for sub-phases.

Epic Titles — [{MILESTONE_ID}] {Title}

[MLX004A] V3 Hybrid Architecture
[FCT003A] Budget & Safety Gates
[CVX005A] VERIFY: Baseline Verification

Task Titles — plain descriptive

No prefix needed — the parent relationship provides context.

Milestone Labels

Every epic and task gets a milestone:{CODE###X} label for cross-project filtering.

Git Branching — Derived from type:* Label

Each epic gets ONE branch. All tasks commit to that branch. ONE PR per epic to {main_branch}.

{prefix} = task_prefix from project-context.md (e.g. BEN, APP, WEB).

Branch format: {type}/{prefix}-{epic_id}-{short-kebab-name} PR target: {main_branch} from project-context.md (NEVER main if configured otherwise) Commit prefix: [{TYPE}] {prefix}-{task_id}: {what changed}

Invocation

/plan-milestone "Computer Vision" 5 "Ship tracking pipeline"
/plan-milestone CVX005E --update          # patch existing issues to match current spec
/plan-milestone CVX005E --update --dry-run

If a milestone ID is passed directly (e.g. CVX005E), skip code derivation and use as-is.

When called from /ccb, the --from-ccb flag is implicit and CCB context (blockers, debt, acceptance criteria) is already in conversation.

--update Flag — Bring Existing Issues Up to Date

When --update is passed, skip Steps 2-4 (no new planning). Instead:

Update Step 1: Load All Existing Issues

issues = list_issues(team: "{task_team_id}", query: "[{milestone_id}]")

Update Step 2: Resolve Correct Project & Milestone IDs

Same as Step 5a-pre — look up the Linear project by code prefix and the milestone by name.

Update Step 3: Audit Each Issue

For every epic and task in this milestone, check:

Update Step 4: Show Audit Report

PLAN-MILESTONE UPDATE: {milestone_id}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Issue         Field              Current              Fix
  ──────────── ──────────────────── ──────────────────── ────────────────────
  {prefix}-3433     projectId            (none)               → Computer Vision
  {prefix}-3433     milestoneId          (none)               → CVX005E
  {prefix}-3434     labels               missing model:*      → model:sonnet
  {prefix}-3435     Execution Context    (missing section)    → Add default block
  {prefix}-3436     milestone label      (none)               → milestone:CVX005E

  {fix_count} fixes needed across {issue_count} issues

If --dry-run: print report and stop. If not --dry-run: use AskUserQuestion to confirm, then apply all fixes via save_issue.

Update Step 5: Verify

Run the same verification sweep as Step 5g — confirm all issues are now linked correctly.

Step 0b: Operator Alignment Check

Ask before loading specs or generating anything:

Before planning {milestone_id}: anything to discuss, clarify, or flag?
(scope changes, locked decisions, timeline constraints, things that changed)

Use AskUserQuestion with options:

• Nothing — let's plan (default)
• I have something to flag — free-text; capture decisions via record_decision (storage) then continue
• Hold — scope isn't settled yet — STOP, do not proceed

If CLAUDE_AUTO=1: skip this step.

Grill me (strategic milestones): When the milestone has ≥ 3 epics planned or touches schema/ETL/auth, ask 2–3 clarifying questions before generating the epic breakdown:

1. "What does 'done' look like for this milestone — what can the Operator do that they can't do today?"
2. "Are there any scope items that should NOT be included, even if they seem related?"
3. "Any external dependencies (integrations, data sources, vendors) that could block this?"

Capture answers as decisions if they constrain scope. Skip if Operator answers "looks good" to any question.

Step 0c: Honesty Stack Mode Selection

Before generating epics, lock in the honesty-stack mode that the milestone and every child epic will inherit. The mode controls which honesty hooks fire at /epic close / /milestone close:

• full — all hooks (R-43 lint + audit-doubt + verifier-isolation + transition + dependency-audit). Use for P0 milestones (FCT*, DAT*, HARDEN, Z) where the cost of a missed honesty signal is high.
• lite — cheap hooks only (R-43 lint + transition-validator). The default — keeps routine epics cheap.
• off — nothing fires. Emergency override for trivial fixes / Operator directive.

Resolution order (highest precedence first)

1. HONESTY_MODE env var (non-interactive fallback for autonomous runs).
2. The Operator's AskUserQuestion choice in this step.
3. resolve_honesty_mode({milestone_id}) from scripts.factory.lifecycle_helpers — applies the per_milestone_overrides globs declared in .claude/project-context.md.

Procedure

import os
from scripts.skills.plan_milestone_helpers import (
    read_honesty_mode_from_description,
    record_honesty_mode_decision,
    resolve_honesty_mode,
    upsert_honesty_block,
)

resolved_default = resolve_honesty_mode(milestone_id)  # e.g. "full" for FCT*
env_override = (os.getenv("HONESTY_MODE") or "").strip().lower()
existing_mode = read_honesty_mode_from_description(current_milestone_description)

if env_override in {"full", "lite", "off"}:
    # CLI override always wins, even over a persisted block.
    chosen_mode = env_override
    rationale = "HONESTY_MODE env var override"
elif existing_mode in {"full", "lite", "off"} and not honesty_block_is_stale(current_milestone_description):
    # CR PR #9817: re-running /plan-milestone on an already-planned milestone
    # must NOT re-prompt the operator for the mode. Reuse the persisted
    # block when it's fresh.
    chosen_mode = existing_mode
    rationale = "Reused persisted honesty mode from milestone description"
elif os.getenv("CLAUDE_AUTO") == "1":
    chosen_mode = resolved_default
    rationale = f"CLAUDE_AUTO=1, using resolved default for {milestone_id}"
else:
    # Interactive: surface the resolved default + ask the operator.
    # Use AskUserQuestion with three options. The label of the resolved
    # default carries "(Recommended)".
    chosen_mode = ask_via_AskUserQuestion(resolved_default)
    rationale = f"Operator choice (resolved default was {resolved_default})"

The AskUserQuestion block:

Question: "Honesty stack mode for {milestone_id}? (resolved default: {resolved_default})"
Options:
  - "{resolved_default} (Recommended)" — recap of what {resolved_default} runs
  - "{other_mode_1}" — recap of what {other_mode_1} runs
  - "{other_mode_2}" — recap of what {other_mode_2} runs

Persistence

After resolving chosen_mode:

# 1. Write the block into the milestone description (idempotent — replaces
#    any existing block, otherwise inserts at end).
new_description = upsert_honesty_block(
    description=current_milestone_description,
    mode=chosen_mode,
    milestone_id=milestone_id,
    rationale=rationale,
)
# Apply via save_milestone (or save_issue for the
# tracker proxy).

# 2. Record the choice via record_decision (supabase → {storage_schema_intel}.decisions). Returns the decision_number on
#    success, None on failure (never raises).
record_honesty_mode_decision(milestone_id, chosen_mode, rationale)

The block rendered by upsert_honesty_block looks like:

<!-- honesty-stack:begin -->
## Honesty Stack

- mode: `full`
- resolved: 2026-05-18 by /plan-milestone for FCT011C
- rationale: Operator choice (resolved default was full)
<!-- honesty-stack:end -->

/milestone start, /pipeline run, and /epic start read this block via read_honesty_mode_from_description() to seed each session's honesty_mode column.

Skip conditions

• CLAUDE_AUTO=1 → use resolved default silently (no prompt).
• Milestone description already contains a non-stale honesty-stack block AND no CLI override → re-use the existing mode, do NOT re-prompt.

Step 1: Spec Grounding — HARD GATE (do NOT skip, do NOT plan from memory)

Planning from the milestone title or from memory — instead of from the spec files on disk — is the #1 cause of drift and false Done marking. You may not write acceptance criteria (Step 2), epics, or tasks until you have produced and shown the Spec Grounding Digest below. This gate is as binding as the naming gate above.

1a. Discover the relevant specs — run these, don't guess

ls {spec_dir}/ ; cat {spec_dir}/.abstract.md 2>/dev/null   # what specs exist
# milestone-goal keywords → matching specs (substitute 2-4 real keywords):
grep -rilE '<keyword1>|<keyword2>|<keyword3>' {spec_dir}/ rules/ | head -20
test -f {spec_dir}/GITHUB_FACTORY_SPEC.md && echo "factory spec present"

Also load the constraints that bound the plan:

• list_decisions() — storage op (supabase → {storage_schema_intel}.decisions) — locked decisions (D-block etc.) that constrain choices.
• Prior-milestone **Spec Section:** refs and any open carry-over.
• Open / recently-closed issues: gh issue list --state open --json number,title,labels,milestone --limit 100.

1a-verify. External model cross-check — did you miss any specs? (MANDATORY)

Before reading anything, send your discovered spec list + the milestone goal to Ollama or Gemini. The external model sees only filenames and the goal — it cannot read the files. Its job is to flag specs you might have missed based on filename pattern and milestone topic alone.

python3 {scripts_dir}/skills/verify_spec_coverage.py \
  --goal "{milestone goal as plain English}" \
  --found-specs "{spec_dir}/FOO.md {spec_dir}/BAR.md rules/areas/etl.md" \
  --spec-dirs "docs/specs docs/runbooks rules/areas"

The script calls Ollama (→ Gemini fallback) and returns:

• Confirmed: specs your search found that the model agrees are relevant
• Missed: specs in the tree the model thinks you should also read
• Irrelevant: specs your search found that the model thinks don't apply

Any file in Missed is a mandatory read — add it to your list before 1b. If the external model is unavailable, skip with a logged warning and proceed.

1b. READ each candidate spec end-to-end, then write the digest

Open every spec relevant to this milestone with the Read tool and read it in full. Then write a Spec Grounding Digest to .claude/.plan-specs-{milestone_id}.md and show it to the Operator. One row per relevant spec section:

The verbatim quote column is the forcing function: you cannot fill it without having opened the file. Paraphrase-only rows are rejected. Every quote needs its Lstart–Lend.

1c. Spec Quiz — mechanical verification (do NOT skip)

After writing the digest, run the quiz against every spec file you read. The quiz pulls verbatim lines and asks you to fill them in — it cannot be passed without having read the file.

python3 {scripts_dir}/skills/spec_quiz.py <spec_file1> [<spec_file2>...] --questions 2

• Pass (≥70%): proceed to gate check.
• Fail: return to 1b, re-read the flagged file end-to-end, retry once.
• Still fail: stop. Tell the Operator which spec is unclear before continuing.

Also verify the digest structure is valid (catches empty-quote cells):

python3 {scripts_dir}/skills/spec_quiz.py --digest.claude/.plan-specs-{milestone_id}.md

This must return OK before Step 2.

1d. Gate check — ALL must be true before Step 2

• Spec quiz passed (≥70%) for every spec file read.
• Digest structure check returned OK (no empty quote cells).
• Every spec path in the digest passed test -f (it is a real file).
• Every row has a verbatim quote and a line range — no empty/paraphrased quote cells.
• Every milestone epic in Step 3 maps to ≥1 digest row via its **Spec Section:** line.
• The digest file .claude/.plan-specs-{milestone_id}.md exists and is non-empty.
• Spec gaps are explicit: each section is marked none / partial / done — gaps drive the epic breakdown.

If you cannot quote a requirement, you have NOT read that spec — return to 1b. These rows are the source feeding the §46 spec-coverage producer hook (Step 5a-post); a missing digest there means you skipped this gate.

Step 2: Generate Acceptance Criteria

Before any epic planning, define milestone-level acceptance criteria. These are the tests that the hardening epic will run.

Format:

## {milestone_id} Acceptance Criteria

### Functional
- [ ] {User-visible behavior that must work end-to-end}
- [ ] {Another behavior}

### Technical
- [ ] {Performance/reliability requirement}
- [ ] {Integration requirement}

### Quality
- [ ] All new code has test coverage
- [ ] No new files over 500 lines
- [ ] All spec sections for this milestone have implementation

OUTCOME-BASED CRITERIA RULE (CRITICAL): Every acceptance criterion MUST assert an observable OUTCOME, never an operation.

Operation-based criteria are how false Done marking happens — a DROP COLUMN IF EXISTS silently no-ops, the agent checks "did it run?" (yes), marks Done, and the column is still there. Outcome-based criteria catch this because they check the actual state.

Present to Operator for approval. Adjust based on feedback.

Step 2b: Write Epic Test Files BEFORE Tasks (TDD — Red First, Independent Model)

HARD RULE: Claude does NOT write the tests. A separate model writes them. Claude's implementation plan is NOT shown to the test writer — only the Spec Grounding Digest and Exit Criteria. This is the only way tests are independent. Self-review is not review.

Step 2b-0: Dispatch Test Writing to External Model (MANDATORY)

After Step 2a (Exit Criteria are written), dispatch test writing to an external model. The test writer sees ONLY the spec digest and exit criteria — never Claude's internal planning notes.

Preferred dispatch order (try in sequence, use first available):

1. Ollama (local, free) — try codestral:22b or deepseek-coder-v2 first:

   ollama list 2>/dev/null | grep -E "codestral|deepseek-coder|qwen2.5-coder" | head -3
   

   If a suitable model is available:

   # Write the test brief (spec + exit criteria ONLY — no implementation context)
   cat > /tmp/test_brief_{milestone_id}.md << 'EOF'
   # Test Writing Brief — {milestone_id} {epic_id}
   
   You are a grumpy, adversarial test writer. You do not trust the implementation.
   Your job: write failing (RED) pytest tests that prove the exit criteria below are met.
   You have NOT seen the implementation. Write tests that WOULD CATCH a lazy implementation.
   
   ## Spec (verbatim from spec digest)
   {paste relevant rows from.claude/.plan-specs-{milestone_id}.md}
   
   ## Exit Criteria to Test
   {paste this epic's Exit Criteria from Step 2a}
   
   ## Rules
   - Every criterion gets ≥1 test function
   - Fail with raise NotImplementedError("RED: {criterion}") — NEVER pytest.skip
   - Docstring states which criterion is proven
   - Assert OUTCOMES, not "did the function run"
   - Be adversarial: write the test that would catch a stub or fake
   EOF
   
   ollama run codestral:22b < /tmp/test_brief_{milestone_id}.md > /tmp/test_output_{milestone_id}.py
   

   Review the output. If sensible, copy to the correct test path (see naming below). If garbage, fall back.

2. Codex (if available) — same brief, same isolation constraint. Codex does NOT see Claude's plan.

3. Claude as fallback (last resort only) — only if Ollama and Codex are both unavailable. If Claude must write its own tests, explicitly log in the milestone description:

   ⚠️ SELF-TESTED: No external model available at planning time. Tests written by Claude.
   Flag for adversarial review before epic closes.
   

   Then write tests using the Exit Criteria only — deliberately ignore the implementation plan.

For every epic in this milestone, write the actual test file(s) to disk NOW — before any task is created in Linear. These tests FAIL immediately (RED). They turn GREEN when the epic is done. This is not optional. If there is no test file, there is no proof of completion.

Tests are always specific to what THIS epic builds. Never write generic scaffolding or pytest.skip placeholders. Derive the test content directly from the epic's Exit Criteria — each criterion becomes one or more test functions.

Layer Routing Table — which suite for which epic type

Most epics need Layer 1 (unit) + one domain-specific layer. Never skip Layer 1.

Naming Convention (mandatory)

tests/{suite}/test_{milestone_id_lower}_{epic_short}_{what}.py

Examples:
  tests/unit/test_proc001a_e01_karen_blocks_done.py
  tests/contract/test_dat008a_e03_event_schema.py
  tests/security/test_proc001a_e02_apply_migration_blocked.py
  tests/regression/test_ben3706_onb001a_invite_flow.py   ← issue-named regressions

How to write the test (not a placeholder)

Read the epic's Exit Criteria. For each criterion, write one test function that:

• Asserts the OUTCOME directly — never "did it run?" but "does the result match?"
• Fails right now with raise NotImplementedError(f"RED: {what this epic must deliver}") — NOT pytest.skip. skip hides the test. NotImplementedError shows the gap.
• Has a docstring stating which Exit Criterion it proves

# tests/unit/test_proc001a_e01_karen_blocks_done.py
"""
PROC001A E01: completion-audit pre-commit hook tests.
Written RED before implementation. All must pass before epic closes.
"""
import pytest

class TestKarenDoneGuard:
    def test_blocks_commit_when_test_file_missing(self, tmp_branch):
        """Exit Criterion: git commit with 'Done' fails if ## Tests file doesn't exist."""
        raise NotImplementedError("RED: guard-done-marking.sh not yet implemented")

    def test_blocks_commit_when_test_file_has_zero_functions(self, tmp_branch):
        """Exit Criterion: commit blocked if listed test file has no test_ functions."""
        raise NotImplementedError("RED: guard-done-marking.sh not yet implemented")

    def test_allows_commit_when_tests_pass(self, tmp_branch, passing_test_file):
        """Exit Criterion: commit succeeds when listed tests all pass."""
        raise NotImplementedError("RED: guard-done-marking.sh not yet implemented")

Three layers required per exit criterion (thin tests are rejected)

Every exit criterion must produce tests in all three layers. One criterion = three test functions minimum:

A test file with only Layer 1 tests will be rejected by the TDD gate. Layer 2 docstrings MUST quote the spec verbatim — no paraphrase.

After writing all epic test files

pytest tests/ --collect-only -q 2>/dev/null | tail -5  # confirm tests are collected
pytest tests/unit/test_{milestone}_{epic}*.py           # confirm they FAIL (RED)
git add tests/
git commit -m "[TEST] {milestone_id}: Write RED test files for all epics (pre-implementation)"

This commit is the proof that TDD is real. The factory cannot claim an epic Done unless its test file exists and pytest returns 0.

The ## Tests section of every Linear task must reference these exact file paths.

Step 2b.1: Consume CCB Phase 3.26 output — testing-scenarios + walkthrough twin

If this milestone was planned via /ccb, Phase 3.26 already produced, per feature epic: a ## Testing Scenarios block, a walkthrough-twin issue under master_verification_milestone (.claude/project-context.md), and a row in config/test_coverage_matrix.json. /plan-milestone does NOT regenerate these — it writes them verbatim into the epic description alongside ## Tests, and confirms the twin link:

for each feature epic:
  assert epic.body contains "## Testing Scenarios"      # from CCB 3.26
  assert epic.body contains "Verification twin: {id}"    # walkthrough issue link
  if either missing:
    # This milestone was NOT run through /ccb (or /ccb predates Phase 3.26).
    # /plan-milestone must generate them itself — do not skip.
    build the testing-scenarios block per the template in
    `.claude/skills/ccb/SKILL.md` § Phase 3.26, using this epic's acceptance
    tests + spec refs as source material.
    create the walkthrough-twin issue under master_verification_milestone.
    append the row to config/test_coverage_matrix.json.

This is what makes planning output "feature epic AND its verification twin" with zero extra Operator steps — the twin either arrives pre-built from /ccb or gets built here, but it always exists before the epic is written to the task manager.

Step 2c: Write Acceptance Test Scaffolding (Outcome Verification — Red First)

For every epic, also create acceptance test scaffolding in tests/acceptance/ for each applicable tier. These answer "does this actually work for a real user?" — not just "does the code exist?"

Tier selection — auto-determine from what the epic builds:

All acceptance tests must:

• Use pytest.mark.skipif(not os.environ.get("SUPABASE_URL"), reason="requires live credentials")
• Fail RED with raise NotImplementedError("RED: {what this must prove}") until the epic is built
• Have a docstring stating the user story: "As a {user}, I can {action} so that {outcome}"

Also write the User Story and End-User Verification stub for each epic directly into the Linear epic description's ## End-User Verification section. Pre-fill the format:

## End-User Verification
**As a {user type}, you can now:** {action in plain English}

**To verify:**
1. {Step 1 — e.g. "Run `{project_cli} X` or go to /page/url"}
2. {Step 2 — what to look for}
3. Expected: {what correct looks like}

**Regression check:** verify {top 2 adjacent features} still work.

Write TBD — fill at close for the regression check if unknown at planning time.

After writing all acceptance scaffolding:

pytest tests/acceptance/ --collect-only -q 2>/dev/null | tail -5  # confirm collected
git add tests/acceptance/
git commit -m "[TEST] {milestone_id}: Write acceptance test scaffolding (RED)"

Step 3: Epic Breakdown

3a: Identify Epics

Group related work into epics. Each epic should:

• Map to 1-2 spec sections
• Be completable in 1-3 days of factory time (5-15 issues)
• Have clear entry criteria (what must exist before this epic starts)
• Have clear exit criteria (how do we know this epic is done)

3b: Dependency Ordering

Build a dependency graph:

[FCT003A] Codex/Cursor CLI ← no deps
[FCT003A] Clone Slots ← depends on CLI epic
[FCT003A] Review Loop ← depends on Clone Slots
[FCT003A] Auto-Merge ← depends on Review Loop
[FCT003Z] HARDEN ← depends on ALL above

3b.1: blockedBy Convention (CRITICAL — for all agents)

Every blockedBy relationship must be set explicitly via Linear. Never rely on implied ordering.

Within-Milestone Patterns

VERIFY epic:       blockedBy = []                    (always first, no deps)
Feature epic:      blockedBy = [VERIFY]              (all feature epics blocked by VERIFY)
Feature epic (cross-dep): blockedBy = [VERIFY, {prefix}-{other_feature}]
VERIFY-MECH epic:  blockedBy = [ALL feature epics]   (if selected in Step 3d.5)
HARDEN epic:       blockedBy = [VERIFY-MECH]         (or [ALL feature epics] if no VERIFY-MECH)
VERIFY-HUMAN epic: blockedBy = [HARDEN]              (if selected in Step 3d.5)

Standard within-milestone blockedBy call:

# VERIFY: no blockers
# Feature epic E02:
save_issue({ id: "{E02}", blockedBy: ["{prefix}-{VERIFY}"] })
# Feature epic E03 (also blocked by E02):
save_issue({ id: "{E03}", blockedBy: ["{prefix}-{VERIFY}", "{prefix}-{E02}"] })
# VERIFY-MECH (blocked by all feature epics, if selected):
save_issue({ id: "{VERIFY_MECH}", blockedBy: ["{prefix}-{E02}", "{prefix}-{E03}", "{prefix}-{E04}"] })
# HARDEN (blocked by VERIFY-MECH, or all feature epics if no VERIFY-MECH):
save_issue({ id: "{HARDEN}", blockedBy: ["{prefix}-{E02}", "{prefix}-{E03}", "{prefix}-{E04}"] })
# VERIFY-HUMAN (blocked by HARDEN, if selected):
save_issue({ id: "{VERIFY_HUMAN}", blockedBy: ["{prefix}-{HARDEN}"] })

Cross-Milestone Patterns

When one milestone depends on another milestone's completion (e.g. DAT004E depends on DAT004D):

# The VERIFY epic of the dependent milestone is blocked by the HARDEN epic
# of the prerequisite milestone. This is the official cross-milestone dependency wire.

# Example: DAT004E-VERIFY blocked by DAT004D-HARDEN
save_issue({
  id: "{DAT004E_VERIFY}",
  blockedBy: ["{DAT004D_HARDEN}"]
})

# TRK001A-VERIFY blocked by DAT004D-HARDEN (depends on migrations, not views):
save_issue({
  id: "{TRK001A_VERIFY}",
  blockedBy: ["{DAT004D_HARDEN}"]
})

Rule: Always wire VERIFY of the downstream milestone to HARDEN of the prerequisite. Never wire individual feature epics to epics in another milestone (too granular, breaks when plans change).

Task-Level blockedBy

Within an epic, tasks that must run sequentially:

# Task 2 blocked by Task 1 (schema must exist before API can reference it):
save_issue({ id: "{task2}", blockedBy: ["{prefix}-{task1}"] })

# REVIEW exit gate task is ALWAYS blocked by ALL other tasks in the epic:
save_issue({
  id: "{REVIEW_task}",
  blockedBy: ["{t1}", "{prefix}-{t2}", "{prefix}-{t3}"]
})

Tasks that CAN run in parallel have no blockedBy relationship — omit or set blockedBy: [].

3c: Epic Template

For each epic, produce:

## [{milestone_id}] {Title}

**Spec Section:** {spec_file}#§{section}
**Dependencies:** {prefix}-{prev}, {prefix}-{prev2}
**Entry Criteria:** {what must be true before starting}
**Exit Criteria:** {what must be true to close}

### Acceptance Tests (written BEFORE tasks)
- [ ] {Testable criterion 1}
- [ ] {Testable criterion 2}

### Tasks
1. {task title} — {size S/M/L} — {labels}
2. {task title} — {size S/M/L} — {labels}
...

### Task Dependency Order
{which tasks can run in parallel vs must be sequential}

3d: Add Verification Epic (FIRST)

ALWAYS add as the FIRST epic in any milestone:

## [{milestone_id}] VERIFY: Prior Milestone Verification

**Dependencies:** None (runs first)
**Entry Criteria:** Previous milestone closed OR first milestone (baseline audit)

### Tasks
1. **Smoke test infrastructure** — verify build, CI, daemon, and core systems are healthy:
   - `npm run build` in ui/dashboard/ exits 0
   - `pytest tests/` core tests pass
   - Factory daemon starts and claims 1 test issue
   - Supabase connectivity verified
   Size: M — type:test
2. **Quality sweep** — run Phase 6.5 quality sweep on ALL milestone artifacts:
   - Milestone issue has required sections
   - All epics have Outcome/Tasks/Exit Criteria/Gate Level
   - All tasks have Goal/Steps/Outcome/Guardrails/factory labels
   - Cross-references intact (no orphans)
   Fix anything that fails. Size: M — type:audit
3. Run prior milestone acceptance criteria (regression check) — M — type:test
4. {agents.completion_audit} audit: verify prior milestone completions still hold — M — type:audit
5. {agents.spec_audit} audit: verify spec sections from prior milestone — M — type:audit
6. Fix any regressions found — variable — type:fix
7. Generate baseline test snapshot for this milestone — S — type:test

### Exit Criteria
Infrastructure healthy. All artifacts pass quality sweep. Prior milestone criteria still pass. No regressions. Baseline captured.

For the FIRST-EVER milestone (no prior), this becomes a reality reconciliation:

## [{milestone_id}] VERIFY: Baseline Reality Audit

### Tasks
1. {agents.completion_audit}: audit all items marked DONE in the task-manager milestone — L — type:audit
2. {agents.spec_audit}: spec compliance sweep across all specs — L — type:audit
3. Fix critical lies/gaps found — variable — type:fix
4. Establish baseline acceptance test suite — M — type:test

3d.5: Gate Epic Selection — VERIFY-MECH / HARDEN / VERIFY-HUMAN

Not every milestone needs all three gate epics. Analyze the milestone scope and RECOMMEND which gates apply. Present to Operator for approval via AskUserQuestion.

Decision logic:

Ask the Operator:

GATE EPIC RECOMMENDATION for {milestone_id}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This milestone touches: {UI pages / data pipeline / security / etc.}

Recommended gates:
  ✓ VERIFY-MECH — {reason: "UI pages need Playwright testing across all roles"}
  ✓ HARDEN — {reason: "Always included — completion + spec audits"}
  ✓ VERIFY-HUMAN — {reason: "User-facing features need Operator walkthrough"}

  or for a data milestone:
  ✗ VERIFY-MECH — skip (no UI pages)
  ✓ HARDEN — completion + spec audits
  ✗ VERIFY-HUMAN — skip (no user-facing changes)

Use AskUserQuestion:

question: "Gate epics for {milestone_id}?"
options:
  - "All three (Recommended)" — VERIFY-MECH + HARDEN + VERIFY-HUMAN
  - "HARDEN + VERIFY-MECH only" — skip human walkthrough
  - "HARDEN only" — audits only, no Playwright
  - "Custom" — let me pick

If Operator picks "Custom", ask which modules/flows to include.

If CLAUDE_AUTO=1: use the recommendation without asking.

3e: Add VERIFY-MECH Epic (if selected in 3d.5)

Only add if Operator approved VERIFY-MECH in Step 3d.5. Runs /verify mechanical.

3f: Add Hardening Epic (ALWAYS included)

ALWAYS add after all feature epics. HARDEN runs the completion + spec audits ({agents.completion_audit} + {agents.spec_audit}). If VERIFY-MECH exists, HARDEN depends on it. If no

…(truncated)