v7.7.0 — Wake-opportunism, worktree-aware lifecycle, worker model selection

Cumulative release covering v7.5.0, v7.6.0, and v7.7.0 since v7.4.0. Three falcon-skill minor versions land in one squashed snapshot per the kit's public-release convention.

v7.7.0 — Wake-opportunism convention + respawn ordering

• Wake-opportunism convention: on any steering-session wake (cron fire, operator message, monitor event), after the triggering role exits, probe all active dispatches for pending actionable state and process under the appropriate role's rules. Scheduled crons become the AFK latency floor, not a ceiling when the operator is present. Telemetry gains a source= attribution label; fires == silent + useful invariant preserved. New CRONS.md cross-cutting section; each cron template carries an exit-step pointer; PROTOCOL.md Step 3 gains the awake-supersedes-cadence note.
• /falcon respawn-fresh ordering fix: COMMANDS.md Behavior list now writes dispatch_continuation: true BEFORE spawning the successor, matching PROTOCOL.md's authoritative walkthrough. Closes a race where the successor's bootstrap could read the file before the flag landed and skip the three-step recovery sequence.

v7.6.0 — Worktree-aware worker lifecycle + --queue flag

• Worktree-aware lifecycle: under default --bg isolation, git checkout <branch> was impossible (steering holds the branch). Step 1 now branches on worktree detection — ancestry verify (git merge-base --is-ancestor origin/<branch> HEAD) replaces the checkout call when isolated, retained checkout path for non-isolated workers. Edit-root rule made explicit: only .claude/tmp/* paths resolve via repo_path; all work-product paths resolve against the worker's own git rev-parse --show-toplevel. Step 9 push contract becomes git push origin HEAD:<branch> (with rebase first), landing commits on the real branch ref without checkout.
• --queue flag for /falcon work beads: lock-conflict HARD-reject converts into a registered pending-dispatch in .claude/tmp/falcon-queue.yaml (cross-session FIFO). Both release paths (Step 4 auto-release + /falcon release) re-run the full pre-dispatch sequence for the eldest non-conflicting entry. New /falcon dequeue <queue-id> verb; /falcon list-pending shows queued entries with a STALE flag at >24h.

v7.5.0 — Worker model selection (cluster)

• /falcon work beads --model <model-id|auto|inherit>: default inherit in ALL modes including --autopilot. auto consults the model_defaults block in falcon-autopilot.md; if no match, falcon evaluates the bead (cynefin + size + Effort Forecast) and proposes with recorded rationale. Hard invariant: orchestrator always indicates the model, resolved before worker init; worker has no self-selection role.
• /falcon respawn-fresh --model <id> --thinking <mode>: prompted override at respawn — operator can escalate (or downgrade) a successor's model without re-authoring the dispatch.
• Intent-gate model escalation: orchestrator can kill a poor-intent worker and respawn on a stronger model. Manual: escalate <dispatch-id> [--model <id>]. Autopilot: escalation_ladder + escalation_budget policy keys (commented out in all profiles), escalations[] audit shape on dispatch files. Budget is separate from amendment budget; default 1 escalation per dispatch.

Documentation

• BOOTSTRAP.md new at the kit root — the full 6-step bootstrap prompt extracted from README.md. Two usage modes: Follow @BOOTSTRAP.md with my PRD @PRD.md in a fresh session, or copy-paste the prompt block as before. README's Bootstrap section shrinks to a ~15-line stub (same heading + anchor preserved).
• README.md restructure — TOC, mega-bullet → Path/Description table for "What this distribution contains", sub-bullets for --minimal and Architecture entries, mini-headings throughout. Version pointer rewritten to reference the latest release tag rather than SKILL.md frontmatter (one component among several).
• Example PRDs (examples/asteroids_prd.md, examples/snake_prd.md) — headers point at BOOTSTRAP.md with the direct @-reference invocation.
• AUTOPILOT-RULES.md gains the model_defaults template section 7 + escalation_ladder/escalation_budget section 8 (both shipped commented in all profiles).

Breaking changes

None. Default behavior preserved on every flag.

Schema additions (dispatch file + autopilot rules)

• worker_model: "inherit" | "<model-id>" | "auto" (default inherit)
• worker_model_rationale: string | null
• escalations[] array
• model_defaults, escalation_ladder, escalation_budget in falcon-autopilot.md template
• falcon-queue.yaml (queue file schema)

v7.4.0 — per-dispatch worker model + thinking-mode selection

Worker model + thinking-mode selection at pre-dispatch review

Steering proposes — and you can override — the worker's model and extended-thinking budget per dispatch, recorded in the dispatch file and injected into the claude --bg launch. A doc-only chore can run on a small model; a complex implementation bead can get a top-tier model with extended thinking.

Dispatch schema

• New fields worker_model + worker_thinking_mode (default inherit for both). inherit omits the --model flag and thinking env entirely — the launch is byte-identical to v7.3.0. Dispatch files missing the fields behave as inherit: no migration needed.
• Thinking delivery is MAX_THINKING_TOKENS env at spawn (none=0, think=10000, ultrathink=31999) — session-wide for the worker's whole lifecycle, unlike prompt keywords which decay after one turn.
• Enforcement is --bg-only for BOTH fields; in --via-paste/--paste the recorded values are advisory, the downgrade messages say so, and the dispatch prompt carries honoring instructions.

Protocol

• Step 1 proposal surface alongside file_scope confirmation, with a cynefin/type/forecast-driven heuristic table (guidance, not policy).
• --dry-run previews the selection + resulting launch shape.
• respawn-fresh successors reuse the recorded values.

Velocity report pipeline (kit scripts)

• velocity-report.py template path fixed (report generation was previously broken); new self-locating velocity.html dashboard template ships beside the script.
• Generator hardened: non-ASCII metrics no longer crash it; backslashes no longer silently corrupt the embedded data; malformed jsonl lines are counted to stderr instead of silently skipped.

Also

• .github/PULL_REQUEST_TEMPLATE.md now ships with the kit.
• Pre-release hardening pass: a 10-reviewer validation sweep over the dispatch docs fixed advisory-semantics gaps, a respawn template that silently dropped model pins, and stale decision-tree diagrams.

Validated against field deployment data. Full details: .claude/skills/falcon/changelog.md.

v7.3.0 — Required Context contract + effort-metrics kit (token tracking, typed YAML schemas, --minimal tiers)

Summary

The largest kit release to date. Three themes: dispatch context becomes a contract (the falcon skill now declares what a worker must read), effort becomes measurable (a full forecast → track → calibrate loop ships in the kit), and session state becomes typed (JSON Schemas + YAML replace freeform markdown for every kit artifact). Driven by 11 decision records grounded in a month of field-deployment transcript data (377 sessions).

Changes

Required Context contract (falcon skill v7.3.0)

Problem: Workers guessed which context files mattered for a bead. Misses surfaced as wrong-assumption implementations; steering had no visibility into what a worker actually read.

Solution: Dispatch files now carry required_context[] (steering populates it at Step 2 from the bead's ## Required Context section); the worker loads those files at new Lifecycle Step 2b before writing intent, and reports any unlisted_context_reads[] in its return. /wrapup absorbs unlisted reads as doc-gap enhancement entries — so the contract self-improves.

Files changed:

• .claude/skills/falcon/PROTOCOL.md — Step 2 population logic; Worker Lifecycle Step 2b
• .claude/skills/falcon/REFERENCE.md — dispatch yaml + worker return contract fields
• .claude/docs/work-item-templates.md — ## Required Context section (hard-bind for cynefin complicated/complex beads)

Token tracking + effort metrics (new infrastructure)

Problem: Effort Forecasts on work items were never compared against reality — no actuals existed, so forecasts couldn't calibrate.

Solution: A complete measurement loop: scripts/token-tracking.py (stdlib-only Python 3, zero dependencies — no jq) bookmarks transcript line offsets and sums per-phase token/turn actuals per bead, with cross-session resume, orphan recovery, and a --coordinate mode for multi-bead planning cost. /leroy starts tracking at claim; /wrapup Task 3c flushes segments to metrics.jsonl (validated by schemas/metrics.schema.json); scripts/velocity-report.py reports forecast accuracy by cynefin domain, size, and phase.

Files changed:

• .claude/scripts/token-tracking.py — the tracker (new)
• .claude/scripts/velocity-report.py — analysis reader (new)
• .claude/metrics.jsonl — committed-by-default data file (new, empty)
• .claude/docs/metrics-schema.md + .claude/schemas/metrics.schema.json — record contract (new)

5-phase Effort Forecast contract + bead linter

Problem: Forecasts and actuals used inconsistent phase vocabularies (3-phase forecasts vs 5-phase actuals produce 3–25× false-overrun signals), and nothing enforced bead quality before triage:ready.

Solution: One strict phase model — plan / discover / implement / test / fix (+ coordinate) — across templates, tracker, and metrics. New scripts/check-bead-contract.py (CONTRACTS_VERSION 1.2) lints beads in 6 modes with severity-by-tier: HARD failures only for triage:ready items and structural defects, SOFT for backlog/triaged so capture stays frictionless. docs/lint-integration.md ships pre-push hook, CI step, and /wrapup integration recipes.

Files changed:

• .claude/scripts/check-bead-contract.py (new), .claude/docs/lint-integration.md (new)
• .claude/docs/work-item-templates.md — 5-phase Effort Forecast with full-shape and clear-chore examples

Typed YAML artifacts + JSON Schema validation

Problem: enhancements.md and standards-history.md were write-only freeform files — categories collided, entries had no lifecycle, and nothing validated handoff.yaml/changelog.yaml shapes.

Solution: Five JSON Schemas (draft 2020-12) under .claude/schemas/; enhancements.yaml (typed entries: 6 kinds, per-kind state machines) and standards-history.yaml (slug-keyed rules, ID-bearing firings, renumber-safe section_ref) replace the markdown forms. Every YAML artifact carries a # yaml-language-server: $schema= header for live editor validation. Markdown docs remain as human references that cite the schemas as the contract.

Files changed:

• .claude/schemas/{handoff,changelog,enhancements,standards-history,metrics}.schema.json (new)
• .claude/enhancements.yaml, .claude/standards-history.yaml (new; legacy .md forms removed)
• .claude/docs/{enhancements,standards-history}-schema.md (new); handoff/changelog schema docs cross-referenced

/wrapup 2.4.0 → 2.13.2 — tier detection + --minimal

Problem: Every wrapup ran the full ritual regardless of session size; measured field-deployment data showed low-frequency tasks burning 300–500k tokens of ceremony in sessions where they produced nothing.

Solution: Tier Detection pre-check gates synthesis tasks on actual session shape; --minimal runs verify + commit + handoff only (typo fixes, checkpoints) with auto-fallback to the full ritual when substantive markers are detected; Task 9 defaults to a focused self-reflection retro (interactive 6-question mode behind --feedback); new Task 9b verification sweep consolidates three look-around tasks into one; Task 3c (token-tracking flush) runs unconditionally — calibration data is never skipped. Measured: ~30% median wrapup savings, ~73% on qualifying --minimal sessions.

/leroy 2.4.1 → 2.9.0 + navigator-recon 1.2.0 → 1.5.0 — startup tiers

Problem: Session startup cost the same whether resuming a known bead or planning fresh multi-bead work (~9M eff-tokens median).

Solution: --minimal continuation mode (skips health checks, history, and specialist routing; single corpus fetch — ~50% savings), --skip-health flag, cynefin-gated specialist routing (clear beads present their own body as the plan; saves ~250k tokens on ~35% of claims), session tracker schema v3 with per-bead phase tracking starts, and navigator-recon's Required Context parsing + enhancements alerts with empty-state suppression.

Session infrastructure: hooks + statusline ship in the kit

Problem: Session ID and transcript path (needed by token tracking) had no reliable in-context source; statusline lived at an inconsistent path.

Solution: hooks/session-start.sh injects session ID + transcript path at SessionStart; hooks/statusline.sh moves to the hooks directory; settings.json ships with both registered. Convention: hooks/ = Claude-Code-auto-fired, scripts/ = workflow/user/CI-invoked.

README rewrite

Full front-door rewrite: architecture overview, three install paths, autopilot quick starts, cost model with measured medians, and a "What this distribution contains" inventory.

Schema / API Changes

All additive — no breaking changes for existing dispatches:

• Dispatch yaml: new required_context[] field (nullable; absent = v7.2.x behavior)
• Worker return contract: new per-bead unlisted_context_reads[]
• New metrics.jsonl record contract (schema_version: 1, two record_type discriminators)
• /leroy session tracker JSON bumped to schema v3 (worked_beads object form)
• Legacy enhancements.md / standards-history.md removed in favor of typed YAML (see Upgrading)

Files Changed

Area	Files	Description
Falcon skill	PROTOCOL.md, REFERENCE.md, SKILL.md, changelog.md	Required Context contract; v7.3.0
Commands	commands/wrapup.md (2.13.2), commands/leroy.md (2.9.0)	Tier detection, --minimal, token-tracking integration
Agents	agents/navigator/navigator-recon.md (1.5.0)	Required Context parsing, §9 alerts, continuation mode
Scripts	token-tracking.py, velocity-report.py, check-bead-contract.py	Measurement + lint infrastructure (all new)
Schemas	5 × *.schema.json	Typed artifact contracts (all new)
Hooks	session-start.sh, statusline.sh, settings.json	Session identity injection; path consistency
Docs	metrics-schema.md, enhancements-schema.md, standards-history-schema.md, lint-integration.md, work-item-templates.md	Contracts + recipes
Root	README.md, .gitignore, metrics.jsonl	Front-door rewrite; tracking-state ignores; data stub

Verification

• Secret scan (gitleaks) + pattern sweep clean on the published tree
• All 5 JSON Schemas parse; all YAML artifacts validate against their schemas
• Install smoke test from the published tree: settings.json valid, skill loads, all three scripts execute, session-start hook emits session ID + transcript
• token-tracking.py covered by a 43-case black-box regression suite (happy path, error guardrails, resume/compaction banking, orphan recovery, coordinate mode) — maintained in the development repo

Upgrading from v7.2.x

1. Re-vendor .claude/ (or cherry-pick areas from the Files Changed table)
2. enhancements.md / standards-history.md → typed YAML: archive the old files and start fresh (no migration script; hand-port any entries you still need)
3. If you had a local statusline pointing at .claude/statusline.sh, update the path to .claude/hooks/statusline.sh (shipped settings.json already points there)
4. metrics.jsonl is committed by default; uncomment the .gitignore line if you'd rather keep metrics per-developer-private
5. Existing dispatch files keep working — required_context[] is additive

v7.2.0 — Cron prompt condensation + REFERENCE.md three-file split

7.2.0 (2026-05-27)

Cron prompt condensation + REFERENCE.md tripwire-fired three-file split (fdev-b2f + fdev-3h2). Two related changes that bundle naturally: a ~85% token-cost reduction on every steering-side CronCreate call, and a structural reorganization that splits REFERENCE.md into three single-purpose files now that the documented 1500-line tripwire fired.

Cron prompt condensation (fdev-b2f, Layer 1 + Layer 2 token wins)

The 5 steering-side autopilot cron templates (--watch, --auto-ack, --auto-amend, --worker-cron, --release-on-merge) previously embedded the full Step 0-N cron-fire logic verbatim. When steering armed one via CronCreate(prompt=...), the literal text — ~3000 tokens per cron — became the cron's complete system prompt for every fire. A standard --autopilot macro arms 3 steering crons → ~9000 tokens of CronCreate-prompt overhead per dispatch arm; per-fire amortized cost was ~30,000 tokens per 10 fires.

Each cron template section now has a #### Condensed CronCreate prompt (v7.1.2) sub-subsection holding the literal text steering passes to CronCreate. The condensed variant is a thin pointer (~215-628 tokens per cron, measured: --watch ~215, --release-on-merge ~212, --worker-cron ~363, --auto-ack ~463, --auto-amend ~628 — the two with inline Step 0 adaptive guards run longer because the guard's yq probes + decision tree stay inline by design) that Reads the canonical Step 1-N spec from the same file at fire time. --auto-ack and --auto-amend keep their v7.0.1 adaptive-cadence Step 0 guards INLINE (load-bearing — ~60-70% of fires short-circuit at Step 0 per v7.0.1 fdev-lbq.2/.3; pointer-style Step 0 would defeat the per-fire amortized win by replacing a system-prompt-cached predicate with a tool-result-loaded one). --worker-cron keeps its defensive worker_dispatch_mode == "bg" check inline. The other two (--watch, --release-on-merge) have no Step 0 — fully pointer-style.

Token-cost deltas:

Layer	Metric	Before (v7.1.1)	After (v7.2.0)	Reduction
Layer 1	CronCreate prompt parameter size, per cron	~3000 tokens	~215-628 tokens	~79-93%
Layer 1	Per --autopilot macro arm (3 steering crons: watch+autoack+autoamend)	~9000 tokens	~1306 tokens	~85%
Layer 2	Per-fire amortized context cost (per 10 fires, mixed silent/signal)	~30,000 tokens	~12,000 tokens	~60%

Drift discipline. The full Step 0-N spec stays in the canonical reference; the condensed variant is a derived pointer that Reads the spec at fire time. Eliminates the drift risk where armed crons carry stale Step 1-N text after the canonical spec is updated.

Three-file split (fdev-3h2, tripwire-fired action)

REFERENCE.md was at 3079 lines (post-condensation) — well past the 1500-line tripwire documented in falcon-dev/.claude/architecture.md Design Decisions (the original 2026-05-26 entry noted the tripwire's existence, but the line-count baseline cited there was inaccurate; the actual size at that time was ~2840 lines, already 90% past the threshold). v7.2.0 acts on the tripwire honestly.

File	Contents	v7.2.0 lines
REFERENCE.md (residual)	Schemas, init_prompt templates (default + paste-mode), bootstrap, dispatch prompt, worker return contract, stash file format, copy-paste convention	~915
CRONS.md (NEW)	## Worker Self-Poll Cron Templates (--bg mode only, v7.1.1) + ## Autopilot Cron Prompt Templates (5 cron templates with v7.2.0 condensed sub-subsections + advisor extensions) + shared cron infrastructure subsections (### Cron Telemetry Instrumentation, ### Cron Dispatch-Mode Conventions, ### claude agents CLI surface)	~1478
AUTOPILOT-RULES.md (NEW)	## falcon-autopilot.md Template (6-section rules-file template) + 3 profile definitions (conservative, standard, aggressive) + adopter customization guidance	~730

All three files are now well under the 1500-line tripwire individually. Each has a clear single purpose. REFERENCE.md retains pointer stubs at the locations of the three moved sections, so navigating from old anchors lands in the right new home.

Changes

• NEW .claude/skills/falcon/CRONS.md — cron prompt templates moved here from REFERENCE.md
• NEW .claude/skills/falcon/AUTOPILOT-RULES.md — falcon-autopilot.md rules-file template moved here from REFERENCE.md
• REFERENCE.md — 3 sections removed (## Worker Self-Poll Cron Templates, ## falcon-autopilot.md Template, ## Autopilot Cron Prompt Templates); pointer stubs left at their original locations. File: 3079 → 915 lines.
• PROTOCOL.md — 11 cross-references updated from REFERENCE.md to CRONS.md (4 Step 2 cron emission pointers + 3 worker self-poll pointers + 4 other cron-content references); 2 cross-references updated to AUTOPILOT-RULES.md (/falcon enable-autopilot profile-definitions lookup + autopilot-rules content references); v7.2.0 worker-cron-supersedes-by-self-poll cross-reference paragraph retained (closes Quartermaster Tension 1)
• SKILL.md — frontmatter version: 7.1.1 → version: 7.2.0; file-map updated with CRONS.md + AUTOPILOT-RULES.md entries
• changelog.md — this entry

No behavior change

Additive packaging refactor (condensed variants) + structural reorganization (file split). Full Step 0-N templates remain available as the canonical spec, just relocated. No new schema fields, no new CLI flags, no new runtime deps, no breaking changes to dispatched content. Existing {{ var }} marker + Claude-Code-driven substitution at CronCreate-time stays the templating mechanism (architecture.md "Keep falcon at 4 files; defer jinja adoption" decision remains intact for the template-engine choice; the file count moved from 4 to 6 within the skill directory, which is orthogonal — both decisions live in the updated architecture.md Design Decisions section).

Out of scope (deferred)

• v7.1.1 worker self-poll cron prompts already short; no condensation needed (moved to CRONS.md as-is)
• DAR-self-poll cron template work (same)
• v8.0.0 inotify epic (deferred until 2026-08-01 per separate operator direction)

v7.1.1 — Worker self-poll at pause points (--bg --autopilot AFK wake-gap fix)

7.1.1 (2026-05-27)

Worker self-poll at pause points — closes the --bg --autopilot AFK wake-gap (fdev-0wv). In --bg mode (v7.0.0+ default), steering's autopilot crons (--auto-ack, --auto-amend) faithfully write decisions to the dispatch file, but the worker session — idle in claude agents at intent-confirm — never observes those writes without an external poke (peek/reply, attach, falcon poll). The auto-ack-resume guard (PROTOCOL.md Worker Lifecycle Step 3) only fires when the worker takes a turn; it has no mechanism to schedule that turn itself. The documented "full AFK bundle" promise of --autopilot therefore degraded in --bg to "AFK except for the intent-ack wake injection" — exactly the pause point that most benefits from autonomous progression.

Fix. A worker-side convention (NOT a new flag, NOT a schema change). At intent-emission and DAR-response pause points, the worker arms a self-poll CronCreate scoped to the wait condition (intent_acknowledged_utc non-null; or DAR entry's response field non-null), CAPTURING the returned cron ID in session memory. The cron's prompt is delivered to the worker session as a user-message-style notification when it fires; the worker (which holds the captured ID) interprets the prompt, checks state, and on wait-condition-satisfied calls CronDelete(captured_id) and resumes past the pause. durable: false ensures the cron dies with the worker session.

Changes:

• PROTOCOL.md § --bg dispatch mode (v7.0.0): new subsection ### Worker self-poll at pause points (v7.1.1) describing the convention, the two armable points, the scope guardrail, and coordination/cost rationale
• PROTOCOL.md § Worker Lifecycle Step 3: explicit reference to the intent self-poll in the intent-confirm-pause body
• PROTOCOL.md § DAR protocol: explicit reference to the DAR self-poll for the pause-for-response case
• REFERENCE.md § init_prompt Content Template (default thin/pointer-style): new thin-pointer subsection ### Worker self-poll at pause points (--bg mode only, v7.1.1) with the mode-skip note + a pointer to the new sibling section
• REFERENCE.md § new sibling section ## Worker Self-Poll Cron Templates (--bg mode only, v7.1.1): the two literal CronCreate blocks (intent at */2 * * * *, DAR at */3 * * * *), the role-split contract (cron prompt = wake nudge; worker = CronDelete(captured_id) on wake), and the predicate-simplicity rationale (no commit-attribution check at intent pause; contrast with the auto-ack-resume guard which uses a richer predicate because it runs on session resume)
• SKILL.md frontmatter: version: 7.1.0 → version: 7.1.1

Out of scope (explicit non-goals). --worker-cron flag behavior in --bg stays a SILENT NO-OP as documented in v7.0.0 (the self-poll is a worker-side convention, not a steering flag). No new dispatch-file schema fields. No new IPC primitive — leverages existing atomic-write semantics on the dispatch file (v6.11.0). --via-paste / --paste modes do NOT arm the self-poll (operator paste / worker-cron handles those modes' wake mechanics).

Real-world provenance. Observed during a 7-wave sequential epic dispatch on feature/work-20260526-phase2 (sticker-shop project). Steering cron auto-acked every intent paragraph across 4 dispatches with 8-gate validation; each dispatch still stalled ~5-10 min waiting for human ack relay despite the gate evaluation being instant and trustworthy. Filed as fdev-0wv in falcon-dev (discovered-from fdev-lbq).

SKILL.md version bumped: 7.1.0 → 7.1.1 (PATCH — fixes the v7.0.0 --bg wake-gap; restores documented --autopilot AFK promise; no new flags, no schema change, no behavior change for existing --via-paste / --paste dispatches).

v7.1.0 — Cadence model triad (forecast-driven + per-phase + telemetry; bundles v7.0.1 retro)

Bundled release. This release merged v7.0.1 + v7.1.0 work together (PR #1 on main). Both version entries are reproduced below; no separate v7.0.1 release exists on the git layer since the work never had a standalone merge commit. Adopters who want v7.0.1 functionality alone should pin to a pre-v7.1.0 fork commit (none exist on this remote); otherwise, v7.1.0 carries everything v7.0.1 was scoped for.

---

7.1.0 (2026-05-27)

Forecast-driven initial cron cadence — LIVE (fdev-lbq.28 implements fdev-lbq.25 spec). Step 2 of the dispatch protocol now reads each bead's Effort Forecast (Total turns + Confidence) at dispatch time and computes the initial CronCreate cadence per the bucket table:

Total Turns	Initial cadence (auto-ack / auto-amend / watch)
≤ 15 (short)	2m / 4m / 6m
16-50 (medium)	4m / 7m / 11m (default)
> 50 (long)	8m / 14m / 22m

Confidence modulator shifts one bucket faster (low) or slower (high). Missing/malformed Effort Forecast → medium bucket default + inline log. Multi-bead dispatches use the FASTEST cadence across the bead set per cron type. --cron-cadence Nm overrides the bucket-computed value.

Implementation details:

• Parser regex on the bead body (from bd show --json <bead-id>): r'-\s*Total:\s*~?(\d+)\s*turns' for Total, r'-\s*Confidence:\s*(low|medium|high)' for Confidence
• 5 cron templates in REFERENCE.md (--watch, --auto-ack, --auto-amend, --worker-cron, --release-on-merge) had their CronCreate schedule strings parameterized via {{ schedule_expression }} substitution; --worker-cron and --release-on-merge are NOT bucket-computed (cadence is operator-supplied / PR-merge-polling-driven respectively)
• Offset-staggering convention from fdev-lbq.5 still applies — offset = (cron_slug_hash mod N) heuristic produces well-distributed offsets at any bucket cadence
• Step 0 adaptive-cadence guards from fdev-lbq.2/.3 unchanged — they fire on the same dispatch-file fields regardless of cadence value

Composition with other v7.x cadence work:

The cron cadence model now has THREE mechanisms operating at different scales:

1. Per-fire Step 0 adaptive guards (v7.0.1) — short-circuits when state hasn't shifted. Token cost is what adapts.
2. Forecast-driven initial cadence (v7.1.0, this release) — picks the initial bucket. Sets the cadence at CronCreate time.
3. Per-phase cadence re-arming (v7.1 spec, fdev-lbq.27/.29 pending) — shifts cadence as the dispatch progresses through phases. Re-arms via CronCreate on transition.

When all three are live, autopilot crons should land on signal-density > 30% across the dispatch lifetime per the fdev-lbq.6/.30 telemetry validation.

SKILL.md version bumped: 7.0.1 → 7.1.0 (MINOR — new feature, backwards-compatible; v7.0.x dispatches without Effort Forecast still work via the fallback path).

Per-phase cron cadence re-arming — LIVE (fdev-lbq.29 implements fdev-lbq.27 spec). Builds on the forecast-driven initial cadence above. Step 4 of the dispatch protocol now invokes the Phase Transition Handler before auto-release. The handler computes current_phase from existing dispatch-file fields, compares to phase_transitions[].last, and on transition re-arms each cron via CronDelete-then-CronCreate at the phase-appropriate cadence.

Per-phase × per-cron multiplier table (multipliers stack on .28's bucket):

phase --auto-ack --auto-amend --watch
pre_intent × 2 × 2 × 1
intent_confirm × 0.5 × 2 × 1
implementation CronDelete × 2 × 1
verify_amendment skipped × 0.5 × 1
post_validated self-cancel self-cancel self-cancel

Discover-phase resolutions (fdev-lbq.29):

• Auto-ack self-cancel ownership in implementation phase: ACTIVE CronDelete by the Phase Transition Handler. Step 0 adaptive-cadence guard from fdev-lbq.2 remains in the auto-ack template as redundant safety but is no longer the canonical owner of the transition.
• verify_amendment auto-ack "(quiescent)" path: handler checks <cron>_cron_id field at the top of each per-cron loop iteration; if null (already self-cancelled), skip entirely with {cron: "autoack", skipped: true} in cron_re_arms[]. No CronDelete attempt, no CronCreate, no error.
• Atomic-write ordering vs partial CronCreate failures: handler collects ALL per-cron outcomes in memory FIRST (CronDelete + CronCreate results, including failure captures), then writes the dispatch file ONCE — both cron_id field updates AND the new phase_transitions[] entry — in a single atomic write. Each cron's outcome (re-armed / self-cancelled / no-op / skipped / failed) is captured in cron_re_arms[] regardless of success.

Watch-cron no-op optimization: when new_cadence == current_cadence (most commonly the watch cron at × 1 across non-terminal phases), the handler skips CronDelete/CronCreate for that cron. Forensic record still appears in cron_re_arms[] as {cron: "watch", no_op: true, ...} for audit-trail completeness.

Known limitation: non-Step-4 invocations miss transitions. If steering is invoked mid-dispatch without reaching Step 4 (e.g., /falcon status or /falcon list-locks), the handler does NOT auto-fire. Cron cadences stay at their last-armed value until the next Step 4 invocation. The /falcon transition <dispatch-id> operator command (pending in fdev-lbq.31) fills this gap as a deliberate manual-invocation path.

Composition with v7.0.1 + v7.1.0 other cadence work:

The cron cadence model now has THREE LIVE mechanisms operating at different scales:

1. Per-fire Step 0 adaptive guards (v7.0.1, fdev-lbq.2/.3) — short-circuits when state hasn't shifted. Token cost is what adapts.
2. Forecast-driven initial cadence (v7.1.0, fdev-lbq.28) — picks the initial bucket at CronCreate time.
3. Per-phase cadence re-arming (v7.1.0, fdev-lbq.29) — shifts cadence as the dispatch progresses through phases. Re-arms via CronCreate on transition.

Cron telemetry instrumentation — LIVE (fdev-lbq.30 implements fdev-lbq.6 spec). Each autopilot cron now follows a counter-increment contract: on fire entry, increment cron_telemetry.<slug>.fires; before exit, classify outcome (silent / useful) and increment the matching counter. Slug map: watch / autoack / amend / worker / merge. Invariant: fires == silent + useful at all times. Atomic-write discipline preserves correctness under concurrent fires. Backward compat: dispatches predating v7.1.0 with no cron_telemetry field are excluded from /falcon retro aggregation and reported on a final line.

/falcon retro --branch <name> now emits a "Cron Telemetry" subsection in the RETRO SUMMARY block with per-cron fires / silent / useful / signal_density columns aggregated across all dispatches on the branch. Target signal density (per v7.1.0 design intent): > 30% per cron. The subsection also includes a "dispatches without telemetry: N" line for the legacy-dispatches accounting.

Implementation contract is centralized in REFERENCE.md ### Cron Telemetry Instrumentation (v7.1.0, fdev-lbq.30) (slug map + classify rules + atomic-write notes + backward-compat).

With all three v7.1.0 features now LIVE (fdev-lbq.28 + fdev-lbq.29 + fdev-lbq.30), operators get end-to-end empirical autopilot calibration: forecast picks the initial bucket; per-phase re-arming shifts cadence through the lifecycle; telemetry validates whether the result lands on the > 30% signal-density target.

/falcon transition <dispatch-id> — LIVE (fdev-lbq.31). Operator command that manually invokes the Phase Transition Handler against a dispatch. Fills the known limitation of fdev-lbq.29's Step-4-only auto-invocation pattern: operators running /falcon status, /falcon list-locks, or other read-only commands between Step-4-triggering events would otherwise miss intermediate phase transitions. Behavior: read dispatch file → refuse if not found OR session_status: complete → invoke the Handler (same code path Step 4 uses) → report inline (No transition if idempotent; Transition: <prev> → <new>; crons re-armed: ... if transition fired). COMMANDS.md adds the sub-command section; PROTOCOL.md cross-references from the Phase Transition Handler "Known limitation" subsection. Use cases: diagnostics (confirm current_phase), recovery (retry re-arm after a Step-4 graceful-degrade failure), proactive reconciliation during long-poll operator workflows.

---

7.0.1 (2026-05-27)

Bundled v7.0.x operational retro pass — multiple targeted fixes landed on the same release branch.

Detection-authority caveats: claude --help does NOT list --bg; falcon must not probe it (fdev-uwx)

Adopters and AI assistants doing falcon-related work were repeatedly mis-identifying --bg as unsupported by probing claude --help | grep -- --bg (empty result despite the flag being supported on Claude Code ≥ 2.1.139). Falcon's own detection logic was already correct (version gate via claude --version, never --help) — but the docs didn't pre-empt the natural fallback of consulting --help. This version adds explicit "Detection authority — do NOT consult claude --help" caveats in PROTOCOL.md, COMMANDS.md, and README.md Verify the install so AI assistants reading falcon docs don't fall through to a --help probe.

• PROTOCOL.md Step 2 §"Mode selection + detection" version-gate step — appended "Detection authority — do NOT consult claude --help" paragraph with rationale
• COMMANDS.md --bg ✓ detection sequence step 1 — appended short caveat with link back to PROTOCOL
• README.md §"Verify the install" — adopter-facing heads-up that claude --help may not list --bg
• SKILL.md frontmatter — version: 7.0.0 → 7.0.1

Cron emission dispatch-mode split: --bg uses inline STATE: lines; --via-paste keeps fences (fdev-lbq.9 + fdev-lbq.19)

Production retro observation: in --bg mode, autopilot crons were em...

v7.0.0 — --bg dispatch mode default

7.0.0 (2026-05-26)

MAJOR bump — new default dispatch mode via Claude Code background sessions. /falcon work beads <spec> (no mode flag) defaults to --bg: steering invokes claude --bg --name "falcon-<dispatch-id>" "<short-bootstrap>" via the Bash tool, spawning a detached Claude Code background session observable via the claude agents UI. The prior paste-into-tab default is preserved as the renamed --via-paste flag for environments without agent-view OR users who prefer manual tab control. The cross-machine --paste mode is unchanged. The shift is motivated by ergonomic wins discovered in conversation 2026-05-25:

• No tab management — one agent-view terminal monitors every dispatch (Working / Needs input / Completed state per row)
• Built-in peek-and-reply for INTENT-confirm pauses (Space → read INTENT → type proceed <id> → Enter)
• No paste-block reliability concerns — steering passes the bootstrap as a CLI arg pointer; the multi-line init_prompt content stays in the dispatch file (where it already lives)
• Session persistence across machine sleep + Claude Code auto-updates
• Built-in worktree isolation per session (configurable per-dispatch via --bg-isolated / --bg-no-isolation)
• Built-in PR status indicators on session rows

The architectural fit between falcon's dispatch lifecycle and Claude Code's background-session model is essentially 1:1; retrofitting agent-view as a dispatch mode supersedes several v6.x design decisions (notably example-r3q9 Safeguard A — wrong-paste-by-human is structurally impossible in --bg because there's no paste).

What flipped from ⊘ to ✓ (new flags + sub-command):

• --bg — default for local; auto-downgrades to --via-paste on detection failure. Per-dispatch worktree isolation via --bg-isolated / --bg-no-isolation.
• --via-paste — renamed from the implicit pre-v7.0.0 default. Auto-downgrade target. Worker-cron still applies (unlike --bg).
• --bg-isolated / --bg-no-isolation — per-dispatch worktree-isolation overrides. Default inherits worktree.bgIsolation from .claude/settings.json.
• /falcon respawn-fresh <dispatch-id> [--reason=<reason>] [--force] — NEW SUB-COMMAND. Spawn a FRESH --bg worker that continues an existing dispatch where the prior worker died. Three-step recovery sequence (push unpushed commits → close landed-but-bd-open beads → reconcile in-progress amendments) executes before normal lifecycle. Forensic record of replaced workers persists in worker_bg_prior_sessions[]; never re-claimed.

Environment detection + auto-downgrade. Before any dispatch action, steering runs version gate (claude --version >= 2.1.139) → disableAgentView settings check (project-level wins over user-level) → mode override → success path. Eager (Step 2 entry, before dispatch file written) so failures don't half-create state. Failure messages are actionable — cite the version, name the setting, suggest the explicit --via-paste flag.

Bootstrap-prompt pattern (extends v6.7.0 thin init_prompt design). The CLI arg to claude --bg is a SHORT bootstrap (~5 lines) pointing at the dispatch file using repo_path-anchored absolute paths. MUST include: (1) literal dispatch_id; (2) absolute repo_path; (3) instruction to VERIFY dispatch_id matches once loaded. Full template lives in REFERENCE.md ### Bootstrap Prompt Template (v7.0.0).

Worktree-isolation handling — the .claude/tmp/ shared-path concern: isolated workers run in <repo_path>/.claude/worktrees/<id>/ where the branch does NOT contain .claude/tmp/ (ephemeral, lives in main checkout, not committed). Workers MUST resolve dispatch-file paths via <repo_path>/.claude/tmp/.... The bootstrap-prompt template enforces this by including repo_path literally; PROTOCOL.md Worker Lifecycle Step 1 carries the convention.

New dispatch file fields:

• worker_dispatch_mode: "bg" — values: "bg" | "via-paste" | "paste". Autopilot crons consult this to apply --bg-aware behavior vs legacy paste-block emission.
• worker_bg_session_id: null — short session ID returned by claude --bg. Source of truth for claude attach / claude logs / claude stop reference.
• worker_bg_isolation: null — values: null (inherit project setting) | "isolated" | "none".
• worker_bg_prior_sessions: [] — read-only forensic record of replaced workers, oldest first. Each entry: {session_id, spawned_utc, replaced_utc, reason}. safety-tripped advisory (REQUIRED): if reason: safety-tripped, do NOT read claude logs <session_id> in a new session — the log may reproduce the triggering content and re-trip the safety filter in the reader's session (development-standards.md §3.15).
• dispatch_continuation: false — set to true by /falcon respawn-fresh so the successor's bootstrap detects continuation mode.

--worker-cron is a no-op in --bg mode. The auto-ack-resume guard (v6.9.0; Worker Lifecycle Step 3) handles amendment pickup within the same persistent background session — no separate worker-side cron needed. The flag stays explicit for --via-paste / --paste users; no formal deprecation in v7.0.0. --autopilot macro still expands to --auto-ack --auto-amend --worker-cron --watch; --worker-cron is suppressed at emission time in --bg mode.

Amendment-propagation latency caveat (--bg mode). Without a worker-cron, the worker picks up amendments on its next active turn (typically triggered by user peek/reply, autopilot cron STATUS UPDATE, or the worker's own self-poll mid-execution) rather than on a predictable cron cadence. NOT a regression from --via-paste UX (the user had to wait for the worker tab to poll), but cadence is event-driven rather than predictable. Pinning long-running autopilot dispatches in agent view (Ctrl+T on the row) keeps the worker process alive past the ~1hr supervisor-stop window.

/falcon create-rules bypassPermissions setup check (NEW SCOPE — Q6 verdict). After writing the rules file, the command checks for bypassPermissions: true in .claude/settings.json (project) → ~/.claude/settings.json (user). If neither: emit a non-blocking warning describing how to enable for unattended autopilot operation. If either: emit a one-line confirmation. Check belongs at setup-time (rules-file creation), NOT at activation-time (/falcon enable-autopilot), per quartermaster's reasoning that bypassPermissions is a settings-file value, not a CLI dispatch-time switch.

/rename is the canonical session-identity mechanism (P5.1 fix). The prior v6.7.0 Dispatch Prompt Template Step 1 advised tmux/printf/IDE-escape terminal-title setting; all three mechanisms silently failed across most real-world setups (shell-prompt redraw hooks override the OSC escape within milliseconds; tmux rename errors silently when not in tmux; IDE terminals vary). Replaced with single-line /rename falcon-<dispatch-id> for --via-paste and --paste modes — environment-agnostic, can't be overridden by shell prompts, shown on the prompt bar AND in claude agents. --bg mode does NOT need this step because claude --bg --name "falcon-<dispatch-id>" sets the session name at spawn time.

Supersedes / resolves:

• example-r3q9 (Safeguard A: worker_session_id field + claim mechanic) — RESOLVED by superseding design. In --bg mode there is no paste — steering invokes the session directly with the dispatch ID. Wrong-dispatch-paste-by-human is structurally impossible. Closes as "resolved by v7.0.0 default dispatch mode change."
• Residual concern (different class): steering code logic could pass a wrong dispatch_id to claude --bg. This is NOT what r3q9 was designed to prevent (which was user-attention errors). Mitigation: bootstrap-prompt's verify step ("Verify the dispatch_id field in the loaded file matches before any state change"). Documented in the bootstrap template + Worker Lifecycle Step 1.

Kept (still valuable):

• v6.12.1 Safeguard B (INTENT identity header) — still valuable for --via-paste and --paste modes; also helps users peeking the INTENT block in agent-view to verify dispatch ID matches the row name they're peeking.
• v6.11.0 --worker-cron — superseded for --bg mode but kept for --via-paste and --paste modes.
• v6.12.2 /falcon list-pending — still useful; complements claude agents (the former is per-branch; the latter is global).
• v6.12.2 --watch HIGH-STAKES DAR PENDING headline — still useful; agent-view's row "Needs input" shows that something needs attention but doesn't classify urgency.
• v6.14.0 /falcon enable-autopilot --profile=<name> — independent of dispatch mode.

8 resolved design decisions (initial draft → final):

1. Q1 — --bg is DEFAULT in v7.0.0 (not opt-in). Version-gate + disableAgentView detection logic IS the opt-out path. Eager detection + auto-downgrade is the safety net.
2. Q2 — Worktree isolation: per-dispatch flag (--bg-isolated / --bg-no-isolation) with default inheriting worktree.bgIsolation from settings; if absent, defer to Claude Code default. .claude/tmp/ shared-path concern resolved via repo_path-anchored absolute paths.
3. Q3 — --worker-cron suppressed in --bg mode (silent no-op); flag stays explicit for other modes; no formal deprecation. --autopilot macro expansion description must document the --bg-mode behavior.
4. Q4 — Bootstrap prompt generated from string template at dispatch time (NOT a bootstrap_prompt schema field). Template lives in REFERENCE.md.
5. Q5 — One background session per dispatch (matches current model; --sequential continues to work unchanged in --bg).
6. Q6 — bypassPermissions check belongs in /falcon create-rules (setup-time), NOT /falcon enable-autopilot (activation-time). Non-blocking warning. NEW SCOPE.
7. Q7 — Cost transparency out of scope. Claude Code's billing visibility is the right ...