Glossary

The Apple Neural Engine (ANE) runs different layers of a model at different precisions — cheap layers at 8-bit, critical ones at 16-bit. The framework adopted the same pattern for its model_tiering: cheap skills and simple tasks run on smaller models, reserving bigger models for work that actually needs them.

ARM's big.LITTLE architecture pairs high-performance "big" cores with energy-efficient "LITTLE" cores. The OS routes tasks to whichever core fits. The framework applies the same idea: a task_complexity_gate routes mechanical work to a cheap "LITTLE" model and complex work to a capable "big" one.

LoRA (Low-Rank Adaptation) is a technique for attaching tiny task-specific weight adapters to a large model without retraining the full thing. The framework borrowed this idea for "skill-on-demand" — only the skills relevant to the current phase are loaded into the agent's context, not all eleven at once.

Mahalanobis distance measures how far one point is from a cluster of other points, taking into account how correlated the different dimensions are. The framework's V7.0 HADF (Hardware-Aware Dispatch) uses it to match a running environment's performance fingerprint to the closest chip profile in its library of 17 chips.

Palettization quantizes neural network weights down to ~3.7 bits per value (from 32 or 16), dramatically reducing model size with minimal accuracy impact. The framework applied the same compress-then-decompress pattern to its cache entries, reclaiming roughly 24K tokens of context window per session.

A System on Chip integrates the CPU, GPU, memory controllers, and specialized accelerators onto a single piece of silicon. Modern mobile processors (Apple M-series, Snapdragon, etc.) are SoCs. The fitme-story framework borrowed seven organizing principles from SoC design — skill-on-demand loading, cache tiers, systolic execution, dispatch intelligence — and applied them to a software PM workflow.

Modern CPUs predict which branch of an if/else they'll take and pre-fetch the likely instructions before the actual decision lands. The framework does the analog for skills: while Phase 4 runs, it speculatively preloads the probable Phase 5 skills into context, so the transition is zero-wait.

In a TPU (Tensor Processing Unit), a systolic array is a grid of processing cells that pass data directly to their neighbors, avoiding expensive memory round-trips. The framework applies the same pattern inside a single task: Grep → Read → Edit chains forward results without re-reading files, cutting dispatch cycles dramatically.

Tensor Processing Units are Google-designed accelerators optimized for the matrix multiplications at the core of neural networks. The framework borrowed two TPU ideas: systolic dataflow (data passes cell-to-cell) and weight-stationary batch dispatch (reuse loaded weights across many inputs).

On Apple Silicon, the CPU and GPU share a single pool of unified memory. There's no expensive copying data between them. The framework mirrors this with "result forwarding": the output of one skill is handed to the next without a write-then-re-read cycle.

The /pm-workflow skill is the orchestrator at the heart of the framework. It enforces a nine-phase lifecycle — Research → PRD → Tasks → UX → Implement → Test → Review → Merge → Docs — with approval gates between each phase. Other skills (dev, qa, design, etc.) are invoked from inside pm-workflow as needed.

Shipped at framework v7.1 (2026-04-21). Every 72 hours a GitHub Actions workflow runs `scripts/integrity-check.py` against every state.json and every case study, then writes a snapshot. The first framework capability whose trigger is wall-clock elapsed rather than a code event.

Some checks are useful but too noisy or judgment-dependent to fail hard. Those run as advisory gates: they emit a warning into the integrity report but do not exit non-zero. v7.7 TIER_TAG_LIKELY_INCORRECT shipped advisory permanent because its kill criterion (false-positive rate) fired during baseline.

When a new gate is introduced, pre-existing data may not satisfy it. A backfill is a scripted bulk fix that brings prior documents into compliance. v7.7 backfilled 32 case-study frontmatters and `timing.phases` on three paused features. The framework also supports a backfill exemption tag (`case_study_type: "pre_pm_workflow_backfill"`) for legacy documents that bypass forward-only checks.

Rather than dispatch each task to its own subagent (high orchestration overhead), batch dispatch groups coupled tasks — e.g. four component files that change together — into a single subagent call that commits per task. Modeled on TPU weight-stationary: load the context once, run many small ops on it.

Exactly like CPU caches, the framework keeps frequently-accessed context close and rarely-accessed context further away. L1 is per-skill and fastest to hit. L2 (`_shared/`) holds cross-skill patterns. L3 (`_project/`) holds project-wide lore. Hit rates are instrumented in cache-hits.json.

The framework classifies its 32 instrumented gates by enforcement type. Class A fires automatically (a pre-commit hook or CI check that exits non-zero). Class B is an agent-attention rule documented in CLAUDE.md but not mechanically blocked. Class C requires human judgment (e.g. external audit). v7.6 was the explicit campaign to promote silent Class B gaps to Class A.

Complexity Units are a normalized measurement that lets the framework compare the velocity of features as different as "fix a typo" and "build a hardware-aware dispatch layer." The v2 formula (power-law fit, R²=0.82) accounts for view count, type count, and design iteration scope.

The `/control-room/*` routes on fitme-story.vercel.app expose the framework live state to anyone with the URL: `/control-room/framework` (framework health, all 32 gates, trend charts), the dispatch replay, and per-feature status. Originally an Astro dashboard inside FitTracker2; ported to Next.js as part of the Unified Control Center work.

Shipped 2026-06-29 (FIT-200) to give every trackable item one tracking spine across all layers. Three identifiers: the feature slug (canonical = the .claude/features/<slug>/ directory; the repo is the source of truth), state.json.linear_id (the FIT-NNN that joins repo ↔ Linear), and scheme-prefixed thematic codes — FW- (framework), TC- (test-coverage), DE- (dev-env), HADF-, AN- (analytics), PROD- (product) — which permanently kill the bare-number collisions (there were two different 'R14's and two 'R9's across schemes). `make crosswalk` builds .claude/shared/item-registry.json (the slug↔linear_id join table) plus an advisory for features missing the join. Shared status vocabulary across every layer: Backlog → Planned → In Progress → Blocked → Done → Won't-Do. The driving lesson (observed-pattern W40): trackers like Linear/Notion drift, so always verify an item against the repo before acting on its status.

Shipped advisory 2026-06-29 (AN-1B.1, analytics-master-plan §8.2). A commit-level write-time gate: when FitTracker/Services/Analytics/AnalyticsProvider.swift is staged and an AnalyticsEvent constant's raw event value has no row in docs/product/analytics-taxonomy.csv (and isn't listed in a state.json csv_taxonomy_exempt array), it emits an advisory — keeping the code-emitted analytics events and the documented taxonomy in sync. Baseline drift of 27 undocumented events was burned down to 0 on 2026-06-29; the advisory→enforced flip is gated on a ≥7-day coverage window (review ~2026-07-13). Part of analytics Phase 1.B alongside GA4_MCP_DISCONNECTED.

Introduced 2026-04-21 after the Gemini independent audit. T1 = the number came from real instrumentation; T2 = it is a self-declared estimate; T3 = it is narrative or anecdotal. Quoting a T3 number as if it were T1 is a documented integrity bug. The convention is enforced by the CASE_STUDY_MISSING_TIER_TAGS pre-commit hook plus the TIER_TAG_LIKELY_INCORRECT advisory.

Dispatch intelligence is the Floor 5 component that looks at an incoming task and makes three decisions before work starts: how complex is this (complexity_scoring), which model tier runs it (model_routing, LITTLE vs big), and how many tool calls is it allowed (tool_budgets). Together these cut wasted dispatch by roughly 48%.

DispatchReplay reads a JSON trace of an actual run (e.g. Sprint I, the fitme-story site itself) and animates each step — skill load, cache hit, model tier choice, subagent dispatch — at a controllable speed. It is the canonical way to see the framework behavior without running it.

The v7.5 Data Integrity Framework grouped existing and new checks into eight cooperating defenses across the three timing categories. Together they bracket every quantitative claim from the moment it is written to the moment it is read. v7.6 then promoted four silent Class B gaps in this set to mechanically enforced Class A.

The eval layer is the framework's formalized test-before-merge step for AI-generated output. A library of golden I/O pairs (known input, expected output) runs before any "AI produced" phase can advance. Coverage below a threshold blocks the phase. Introduced in v4.4.

The `TIER_TAG_LIKELY_INCORRECT` cycle-time advisory checks that any T1-tagged quantitative claim in a case study or PRD looks plausibly instrumented (matches a value in measurement-adoption.json / documentation-debt.json / case-study-t1-references.json). Pattern strings like "T+7d", "50 events / 14d", "within T+3d", "events / 24h window" describe *forward-looking* deadlines or volume targets — they are scheduling commitments, not measurements — and the validator should skip them rather than flag false positives. Filter added to `scripts/validate-tier-tags.py::is_target_or_kill_claim()` at FT2 PR #540 (2026-05-31) via a new `FORWARD_DEADLINE_RE` regex with case-insensitive alternation over four shapes. 8/8 unit smoke tests + zero new false positives against the 2026-05-31 case-study corpus. Closes the v7.9.1 docket entry F-TIER-TAG-FORWARD-DEADLINE-FILTER.

Framework honesty-ledger entry FT2-FH-003, written 2026-05-21 alongside the v7.9 promotion. The ledger is an append-only public record of framework claims that were later falsified by data, plus the closure path. FT2-FH-001 and FT2-FH-002 captured silent-pass incidents (v7.7 CACHE_HITS_EMPTY_POST_V6 coverage was 0/46; v7.8.3 PR-cache-staleness produced 33 false-positive findings). FT2-FH-003 is the first ledger entry that is NOT a correction — it codifies the calibration discipline the framework used to AVOID a silent-pass at v7.9. The pattern: every advisory → enforced promotion must execute a B1-style freeze-day checklist (`make integrity-check`, `make integrity-diff`, `make documentation-debt`, `make measurement-adoption`, `python3 scripts/membrane-status.py`, 14-day `gate-coverage.jsonl` review per candidate gate, per-gate decision recording) BEFORE the flip lands. Any gate failing any of the 4 §2.2 criteria stays advisory; re-evaluation defaults to T+14d after the next attempted promotion window.

An access binding is GA4's term for the IAM grant that links a Google Cloud service account identity to a specific GA4 property (e.g., FitMe's property `531124395`) with a stated role (typically Viewer). Without it, the GA4 MCP server hits 403 PERMISSION_DENIED on every query. The happy path is the GA4 UI: paste the SA email → click Add. Two failure modes stack on top of each other and have been observed: (1) the UI rejects the SA email with `This email doesn't match a Google account` — caused by identity-propagation lag, the "Notify by email" checkbox left CHECKED, or Google's 2026-04-23 behavior change blocking newly-created SAs from being added via the UI; (2) the OAuth Playground API workaround is blocked by Google's Advanced Protection Program (APP) when requesting elevated scopes like `analytics.edit`. Three recovery paths are documented in `docs/setup/ga4-access-binding-setup-guide.md` (FT2 PR #376, 2026-05-16): UI retry with propagation-wait + checkbox UNCHECK; bind from a non-APP Google account; configure an own OAuth client + use it in Playground.

Shipped advisory 2026-06-29 (AN-1B.2, analytics-master-plan §8.3). When analytics-affecting code is staged (Analytics/*, control-room/analytics.ts, or the taxonomy CSV) and GA4 MCP is unreachable via env (GA4_PROPERTY_ID set + GOOGLE_APPLICATION_CREDENTIALS pointing at a real file), it prints an advisory. It is advisory-ONLY by design — it never blocks a commit even when 'promoted', so there is no calibration ladder. Pre-launch the GA4 env is typically unset, so the advisory is the expected signal that reminds whoever touches analytics code that GA4 ingest isn't wired yet. Completes analytics Phase 1.B with CSV_TAXONOMY_DRIFT.

Shipped at framework v7.8.6 (2026-05-15, FT2 PR #363). Each Monday at 05:00 UTC, the framework-status-weekly.yml workflow runs scripts/weekly-trend-scan.py over .claude/logs/gate-coverage.jsonl and appends a single row to .claude/shared/gate-coverage-weekly.jsonl listing the distinct gates that emitted that week. Any gate that previously emitted but stopped → the framework-status digest issue opens with reason "A2 gate-coverage", surfacing the silent-pass risk before it accumulates. Complements per-gate GATE_COVERAGE_ZERO advisory by adding a week-over-week comparator, addressing the documented v7.8.0-era HADF Phase 2-bis 9-commit silent-pass incident (observed-patterns #3) at a longer time horizon.

The framework is organized as a hub-and-spoke graph: /pm-workflow is the root orchestrator, and domain skills (dev, design, qa, analytics, etc.) are spokes invoked from the hub based on phase and task type. The topology emerged at v4.3 and produced a 6.5x speedup over the previous mesh.

Every audit rule has a stable check code. Codes ending in `_LIE` catch state.json contradicting reality (PHASE_LIE, TASK_LIE). Codes naming a missing thing flag absence (NO_CS_LINK, V2_FILE_MISSING, STATE_NO_CASE_STUDY_LINK). Codes with `_NO_LOG` / `_NO_TIMING` / `_EMPTY_POST_V6` flag missing instrumentation. As of v7.7 there are 13 cycle-time codes plus 9 write-time codes.

Every PRD and every new gate must declare its kill criterion before it ships — a numeric threshold that, if crossed, triggers a roll-back or a downgrade. v7.7 TIER_TAG_LIKELY_INCORRECT pre-registered "false-positive rate >50%" as its kill criterion; that fired during baseline, so the gate shipped advisory rather than hard.

Shipped at framework v7.8.6 (2026-05-15, FT2 PR #363). The script scripts/integrity-diff.py compares the current platform integrity state (gate counts, advisory counts, mechanism A coverage, doc-debt ledger, measurement-adoption ledger) against a pinned baseline anchor — by default the 2026-05-14 pre-v7.9 baseline at ~/Documents/FitTracker2-backups/2026-05-14-…/platform-baseline/. Closes the documented 96-hour drift window between the weekly framework-status cron (Mon 05:00 UTC) and the 72-hour integrity-cycle workflow — without this surface, drift accumulating during the gap was invisible until the next periodic run. Override the baseline with INTEGRITY_DIFF_BASELINE=<path>; CI mode EXIT_ON_REGRESSION=1 exits non-zero on regression. Invoked daily as part of `scripts/daily-integrity-checkpoint.py`.

v7.6 (shipped 2026-04-25) closed the remaining Class B → Class A gap from the Gemini audit by promoting four silent checks into pre-commit failures (PHASE_TRANSITION_NO_LOG, PHASE_TRANSITION_NO_TIMING, BROKEN_PR_CITATION, CASE_STUDY_MISSING_TIER_TAGS) and adding two recurring CI defenses (per-PR review bot, weekly framework-status cron).

Shipped at framework v7.8.5 (2026-05-13, FT2 PR #328). A single file at .claude/integrity/observed-patterns.md catalogues 25 gate-firing patterns (#1–#25; write-time + cycle-time, e.g. BRANCH_ISOLATION_HISTORICAL, CACHE_HITS_AUTO_INSTRUMENTATION_DRIFT, TIER_TAG_LIKELY_INCORRECT) and 39 workflow patterns (W1–W39; e.g. SSH signing, branch drift, no-auto-merge). Each entry documents trigger, why-expected, signal-vs-noise rule, silence path, and first-observed date. Auto-loaded as preflight by /pm-workflow; CLI access via `make observed-patterns`. The catalog grows append-only-by-default: any novel pattern surfaced during a session MUST be appended before the protocol closes the feature. Converts framework debugging from "every advisory triggers fresh investigation" to "look it up first, only escalate if novel."

When multiple subagents work in parallel, they can write to the same files. Parallel write safety prevents corruption: each subagent works on a mirror of the file, snapshots the original, and rolls back if the build fails. Part of framework v5.2.

Phase E is the post-promotion soak window in the 5-phase Calibration Protocol established at infra-master-plan §3.5. For v7.9 it runs 2026-05-21 → 2026-06-04. During the window: no new gates ship; no new test discipline work (F14, F18) starts; the operator monitors `.claude/logs/gate-coverage.jsonl` for unexpected `failure` rows from the newly-enforced gates; read-only artifacts (e.g., F17 `last_fired_at` index) MAY be built in parallel since they do not add new gates. Mid-window checkpoint = B2 post-v7.9 baseline snapshot on 2026-05-28 (via `make snapshot-phase PHASE=post-v7-9-baseline FEATURE=framework-v7-8-branch-isolation`). Window close ≈ 2026-06-04 → opens the v7.9.1 build window. The 4-criterion §2.2 promotion checklist is the gate that closes each Phase E with a yes/no decision; if Phase E surfaces a regression, the reversibility runbook (single-line revert in under 5 min) restores advisory mode and a new T+14d calibration window opens.

Every phase transition is timestamped and recorded in phase-timing.json. Replaces the old "±15-30 min estimates" with real, retrospective data. Introduced in framework v6.0 as part of the measurement overlay.

platforms_tested is a state.json object {ios, web, backend, ai} of booleans, added by T14 (2026-06-07), recording which platforms a completed feature’s tests exercised — making platform-test parity a queryable property instead of "tests passed somewhere". A companion enforced PLATFORMS_TESTED gate fires at current_phase=complete when no platform is set; framework-meta features (work_type=chore / work_subtype=framework_feature) are exempt. Shipped advisory 2026-06-07; now ENFORCED as of 2026-06-21 (PR #781) after the clean 14-day B15 calibration window. Out of scope: per-platform coverage percentages.

Pre-commit hooks live in `.githooks/pre-commit` and are installed via `make install-hooks`. Each hook calls a Python checker (e.g. `scripts/check-state-schema.py`, `scripts/check-cu-v2.py`). A non-zero exit aborts the commit before it touches the index. This is how the framework enforces its write-time gates.

Shipped at framework v7.8.6 (2026-05-15, FT2 PR #363). `make preflight WORK_TYPE=<feature|enhancement|fix|chore> [FEATURE=<name>]` runs every pre-work check once (W1 ssh-agent, PR-cache freshness, branch isolation, integrity findings, drift vs anchor, doc-debt, adoption baseline) and writes the result to .claude/shared/preflight-cache.json. All 10 downstream skills (ux, design, dev, qa, analytics, cx, ops, release, marketing, research) then read from that cache via their `## Shared Data` section instead of each re-executing the same checks. Schema documented at docs/skills/preflight-cache-schema.md. Mandatory Phase 0.0 step in /pm-workflow.

When Skill A's output is Skill B's input, result forwarding passes it in memory rather than serializing through a file. Modeled on Apple Silicon's unified memory architecture. Eliminates the classic write-then-re-read cycle.

Shipped 2026-06-29 (DE-R18). Every .claude/features/*/state.json carries an integer schema_version (current = 1; all 130 features backfilled). scripts/migrate-state-schema.py (`make migrate-state-schema`) holds an ordered registry of (from, to, transform) migration steps and applies every pending step to bring a file to CURRENT_SCHEMA_VERSION — idempotent, dry-run by default. This closes the field-rename incident class (the historic created/created_at mismatch where a reader silently saw half the data): future schema changes append a migration step and bump the version instead of renaming fields in place.

Rather than load all eleven skill files into context at session start (which ate ~48% of the context window), the framework loads only the 1–2 skills relevant to the current phase. Inspired by LoRA hot-swap in neural networks. Reclaims ~30K tokens per session.

Before any risky write operation, the framework snapshots the current file state to a side store. If the subsequent build or test fails, rollback auto-restores from the snapshot. Prevents half-applied changes from corrupting main. Part of v5.2's parallel write safety.

At dispatch time, the task complexity gate inspects the task and routes it to either a "LITTLE" (cheap, fast) or "big" (capable, slower) model. Mechanical token migrations go to LITTLE; architectural rewrites go to big. Modeled on ARM's big.LITTLE.

V7.0 HADF extends the dispatch layer with a hardware awareness stage. It detects the chip/runtime fingerprint via OS APIs and Mahalanobis distance matching against 17 chip profiles + 7 cloud signatures, then adjusts model routing and cache strategy for the detected environment. Ships as framework version 7.0.

Framework v7.10, shipped 2026-06-10. Hardens the observability of the gates themselves — the meta-layer that watches whether each gate is actually firing — with no new product-facing gates. Three changes: (1) the `GATE_COVERAGE_ZERO` meta-check (advisory) reads the F17 `gate-last-fired.json` index and flags any gate that went silent relative to the active corpus, plus a new 0-candidate mis-wire detector that distinguishes a healthy zero-firing gate (e.g. STATE_OWNER_MISSING: many candidates, 0 violations) from a check site that runs but never reaches a candidate; (2) three cycle-time checks (BROKEN_PR_CITATION, CASE_STUDY_MISSING_TIER_TAGS, PATTERN_SKILL_UNMAPPED) that previously emitted no Mechanism A coverage now emit `mode="cycle"` coverage so the F17 index can see them; (3) field-rename silent-pass closure (observed-patterns #24) — `measurement-adoption-report.py` read only legacy `complexity.cu_version` not canonical top-level `cu_v2` (halving adoption; fixed PR #687), and `refresh-gate-last-fired.py` read only `timestamp`, dropping `w9.auto_isolate` rows keyed `ts` (fixed PR #688). Current canonical state (reconciled 2026-07-13): 131 features · 32 instrumented / 34 live gates (20 write-time + 9 cycle-time + 2 W9 hooks + 1 standalone), 28 firing · 0 integrity findings. Calibration ladder: F16 advisory→enforced (shipped 2026-06-17), PLATFORMS_TESTED (T14) promoted advisory→enforced 2026-06-21 (FT2 PR #781), F4 FRAMEWORK_VERSION_STALE advisory→enforced 2026-07-08 (PR #858), CSV_TAXONOMY_DRIFT (AN-1B.1) advisory→enforced 2026-07-13 (cadence B16), R9 Track-B 30-day read done 2026-07-04, W9 held at advisory 2026-06-28. SCHEMA_DIFF (T12) shipped 2026-07-09 as the 34th live gate. Predecessors: v7.9.1 Build Window (2026-06-04) and v7.9 Promotion (2026-05-21). See FT2 docs/FRAMEWORK-FACTS.md for the live current-state reference.

Framework v7.9, shipped 2026-05-21 via FT2 PR #417 (merge commit ea53ff4) and post-merge close-out PR #419. A single line edit at `scripts/check-state-schema.py:132` (`BRANCH_ISOLATION_ADVISORY_MODE = True → False`) promoted 3 v7.8.1 advisory gates to enforced simultaneously: BRANCH_ISOLATION_VIOLATION Mode B (infra commit-level), BRANCH_ISOLATION_VIOLATION Mode C (per-state.json mutation), and FEATURE_CLOSURE_COMPLETENESS (write-time). All four §2.2 promotion criteria were met against 14-day Mechanism A telemetry (18 + 13 + 13 firings, 0 zero-candidate rows, 0 false positives) per the calibration discipline established at v7.8. The first real-world Mode C gate fire was caught + resolved in the same session: the post-merge close-out commit triggered Mode C because state.json still declared the now-merged-dead `feature/v7-9-promotion` branch; resolved via 1-line `state.json::branch` field update. Total framework mechanisms post-promotion: 37 mechanical gates + 5 advisories (3 advisories promoted). Reversibility: single-line revert in under 5 min. Phase E validation soak runs 2026-05-21 → 2026-06-04. Case study at `docs/case-studies/framework-v7-9-promotion-case-study.md`. Cold-start entrypoint at `.claude/entrypoints/framework-v7-9.md`.

Framework v7.9.1 — single-day build window that opened at v7.9 Phase E exit (2026-06-04) and closed the same day. 8 ships landed across 14 PRs. The unifying constraint: 0 new enforcement gates added — Phase E exit discipline forbids new gates for the first 14 days post-promotion. Every ship is an observability surface, doc update, reusable substrate, or warn-only CI workflow. Ships: F16 try-repo harness (3rd layer of gate testing via subprocess invocation) + F17 last_fired_at index (derived telemetry materialization, AWS Config Rules pattern) + F2 Phase 0 reality-check sub-step (defense against post-squash-merge state drift) + Dev-env Track B (R7 SwiftLint + R8 ruff + R12 markdownlint Makefile + lint.yml CI) + F-LAUNCHD-DRIFT-EXTENSION (b)+(c)+(a) (cron-context phantom-finding suppression + plist path-resolution health checks) + observed-patterns W29-W32 catalog batch (v7.8.5 mandatory-rule append) + F-PHASE-E-ADOPTION-FREEZE-DISCIPLINE (soak-window denominator-dilution discipline) + R9 Track B coverage aggregator (iOS Slather + Python pytest-cov warn-only CI) + dev-env R11/R13/R14/R17/R18 hygiene batch (gitleaks + pip-audit + SBOM + commitlint + shellcheck) + F-DEPLOYED-URL-PROBE FT2 substrate (W18 og:image + W19 GA_ID encoded-newline defense via reusable scripts/probe-deployed-url.sh). Five of 8 ships close documented silent-pass classes (W11.b, W18, W19, W30, soak-window dilution). Quantitative roll-up: CI workflows 8 → 14 baseline (+6 warn-only); observed-patterns W1-W28 → W1-W32 (+4); FT2 dev-env open R-items 7 → 0; v7.9.1 docket 7 candidates → 2 open (both fitme-story-side: F-AUTH-LATENCY-SERVER-METRIC + F-CONTRACT-FIXTURE-SAMPLING + F-DEPLOYED-URL-PROBE workflow integration). Cascading rebase rhythm shipped 14 PRs with 5 mechanical rebases and zero rollbacks. Synthesis case study at `docs/case-studies/framework-v7-9-1-promotion-case-study.md`. Calendar follow-ups: 2026-06-11 T+7d F-LAUNCHD + F-DEPLOYED-URL-PROBE verification; 2026-06-12 External Audit #2; 2026-06-17 F16 advisory→enforced (try-repo-harness → main required status check, 1d early; K2 0% false-positive rate); 2026-07-04 R9 Track B 30-day coverage data read.

The v8.x build window opened 2026-06-17 once the kickoff gate cleared, building on v7.10 (2026-06-10). Its headline change: F16, the try-repo pre-commit harness (the 3rd layer of gate testing that spawns a throwaway git repo and runs the real pre-commit hook via subprocess), was promoted advisory→enforced on 2026-06-17 — one day early. The mechanism is NOT a code flag: the `try-repo-harness` CI job was added to main’s required status checks via `gh api` branch protection, making it an integration-test gate at the CI layer. Calibration: K2 false-positive rate 0% over 60 CI runs / 13 days. A gate’s integration surface can no longer regress silently into main. Alongside F16, three v8.x docket "ready-now" gates shipped: F4 `FRAMEWORK_VERSION_STALE` (write-time, PR #740, 2026-06-16 — fires when a feature is advanced while its framework_version is older than canonical; detection only, NOT auto-mutation; advisory→enforced 2026-07-08 PR #858; the 18th write-time gate), F1 `STATE_TASKS_FILESYSTEM_DRIFT` (cycle-time advisory-permanent, PR #752, 2026-06-17), and F3 `DEPENDENCY_GRAPH_CYCLE` (cycle-time advisory-permanent, PR #753, 2026-06-17). Current canonical counts per FT2 docs/FRAMEWORK-FACTS.md: 131 features tracked, 32 instrumented / 34 live gates (20 write-time + 9 cycle-time + 2 W9 hooks + 1 standalone). T14 PLATFORMS_TESTED was promoted advisory→enforced 2026-06-21 (PR #781); F4 FRAMEWORK_VERSION_STALE advisory→enforced 2026-07-08 (PR #858); CSV_TAXONOMY_DRIFT advisory→enforced 2026-07-13 (cadence B16). Extended 2026-06-29 (v7.10 chores, no version bump): analytics advisories CSV_TAXONOMY_DRIFT + GA4_MCP_DISCONNECTED; then SCHEMA_DIFF (T12) shipped 2026-07-09 as the 34th live gate. See FT2 docs/FRAMEWORK-FACTS.md for the live current-state reference.

v7.7 (shipped 2026-04-28) closed seven remaining gaps from the post-v7.6 inventory: four new write-time pre-commit hooks (CACHE_HITS_EMPTY_POST_V6, CU_V2_INVALID, STATE_NO_CASE_STUDY_LINK, CASE_STUDY_MISSING_FIELDS), one cycle-time check, and the TIER_TAG_LIKELY_INCORRECT advisory. Brings the framework to 25 mechanical gates plus 1 advisory.

Workflow pattern W1 in the Observed Patterns Catalog. When git is configured for SSH commit signing (`commit.gpgsign=true` + `gpg.format=ssh`) but the ssh-agent has no identities loaded, every commit attempt prompts for the key passphrase + fails non-interactively with `exit 128: fatal: failed to write commit object`; worse, `ssh-keygen -Y sign` hangs silently with no error in non-interactive shells. The framework ships scripts/check-ssh-agent.sh (framework v7.8.6, FT2 PR #363) as a SessionStart hook: it runs `ssh-add -l` once per session and emits a loud stderr warning when no identities are present, with the exact `ssh-add ~/.ssh/id_ed25519` recovery command. Disable temporarily via CLAUDE_W1_DISABLE_SSH_CHECK=1. Caught silently broken sessions during the 2026-05-13 T7.9.0 seed-commit attempts; preflight now eliminates the failure mode at session boundary.

Workflow pattern W10 in the Observed Patterns Catalog. Shipped at framework v7.8.6 (2026-05-15, FT2 PR #365) as part of the daily-checkpoint nice-to-have batch. `scripts/daily-integrity-checkpoint.py` lists, in its daily output, local branches whose remote-tracking ref is `[gone]` (the remote was deleted, typically by squash-merge) plus any worktrees in `.claude/worktrees/` that may have been forgotten. The surface is informational, not blocking — cleanup is operator-driven by design because (a) W5 prohibits destructive ops without approval and (b) `[gone]` branches sometimes still hold unpushed WIP. Cleanup is run via the bundled `commit-commands:clean_gone` skill, which lists candidates, asks for confirmation, and atomically removes branch + worktree. Routine drift is 1-5/week; investigate when >10/week, when a worktree is on a non-`[gone]` branch (forgotten active work), or when an unfamiliar branch appears (possible W9 branch-drift artifact from a concurrent session).

Workflow pattern W15 in the Observed Patterns Catalog (`.claude/integrity/observed-patterns.md`, added 2026-05-21 via FT2 PR #422). MDX is JSX-flavored Markdown; `<` is reserved as the start of a JSX tag, and JSX tag names must begin with a letter, `$`, or `_`. Common gotcha strings: "less than 5 min" written as `<5 min`, `<3` (heart emoji), `<10s`, `<0.5%`, `<HEAD~1`, `<==`, `<-->`. At `next build` time the prerender hits `[next-mdx-remote] error compiling MDX: Unexpected character X (U+0XXX) before name`, the build worker exits 1, and the entire production deployment fails. Critical silent-pass class because pre-commit hooks do not compile MDX, PR `verify`+`gates` checks skip MDX render for docs-only PRs, and the Vercel preview shows `fail` but is NOT a required branch-protection check — so the bad PR can merge with all required checks green. First surfaced by fitme-story PR #129 (2026-05-21, v7.9 dev-guide bump) which shipped the pattern in `content/framework/dev-guide.md` and broke production for ~3 hours until hotfix PR #130 (`f27a780`). Silence paths (preference order): (1) rewrite without `<` (e.g., "in under 5 min"); (2) HTML-escape `&lt;`; (3) backtick-wrapped code span; (4) block-fence wrap. Prevention: fitme-story PR #131 added a `mdx-render` job to `integrity.yml` that compiles every MDX file under `content/framework/` + `content/04-case-studies/` via `@mdx-js/mdx` at PR time.

Workflow pattern W9 in the Observed Patterns Catalog, shipped at framework v7.8.5 (2026-05-13, FT2 PR #341). The script at scripts/check-branch-drift.py runs as a PostToolUse:Bash hook: on first invocation it records the current git branch to .claude/_session-state/<session_id>-branch.txt; on subsequent calls it compares + emits a LOUD stderr warning if HEAD has changed without the session running git checkout itself (typically caused by another concurrent Claude session sharing the same working directory). The warning is surfaced back to the assistant via tool output, so the assistant can flag the drift to the operator in real time before the wrong-branch commit lands. Includes a 4-step recovery playbook (stop → inspect → stash-or-cherry-pick → push with explicit --head). Prevention: each concurrent session should run in its own git worktree.

Each integrity gate fires at one of three moments. Write-time: pre-commit hooks that block bad data from entering the repo at all (e.g. SCHEMA_DRIFT). Cycle-time: scheduled audits via GitHub Actions every 72h, scanning the whole repo. Readout-time: dashboards that surface current state on demand (`make documentation-debt`, `make measurement-adoption`).

When the framework audits itself (every few months), it produces findings: typed issues with severity (critical / high / medium / low) and domain. The v7.0 audit produced 185 findings, 12 critical. Every finding is publicly tracked, addressed, and closed out in a sprint.

The 2026-04-21 Gemini audit produced nine remediation tiers grouped into three layers: Tier 1.x = measurement adoption, Tier 2.x = runtime + contemporaneous evidence, Tier 3.x = documentation discipline. Each tier has its own dashboard or playbook (e.g. `make measurement-adoption` surfaces Tier 1.1, `make documentation-debt` surfaces Tier 3.2).

A bootstrap token is a 32-byte random secret printed by the issue-bootstrap-token.ts CLI and pasted into /control-room/sign-in/recover to authorize a first-device passkey registration. Stored as a SHA-256 hash with a 15-minute TTL — the raw token never sits in Redis at rest. Single-use: redemption marks it consumed. This is the explicit recovery channel when an operator loses a device.

The case-study-monitoring.json file records process metrics, quality metrics, success cases, and failure cases for every feature run through the framework. These records become the source material for real case studies — no invented numbers.

Workflow pattern logged 2026-05-30 during HADF Phase 2-bis Sub-experiment 1B Fire 0. Endpoint cardinality (50 calls × 4 providers = 200 calls) appeared modest, but mistral.ai-free returned 41/50 HTTP 429 ("Requests rate limited") and the Vercel AI Gateway returned 45/50 HTTP 429 ("Free tier requests rate-limited. Upgrade to paid credits") — both invisible until first fire. Final yield 114/200 vs pre-reg kill-criterion 600. The post-mortem decision tree: (A) upgrade to paid tier (~$5–$50, multi-day setup), (B) scope reduction (drop the rate-limited endpoints, accept smaller test), or (C) per-call throttle (operationally annoying, doesnt scale to subsequent runs). 2026-05-31 operator decision = (B): drop both, ship 2-endpoint design (anthropic + google) for 2026-06-10 launch. v1 prereg lock sha256=cfc7e968feeb retained as historical record. Pattern surfaced as v7.9.1 docket entry W-MISTRAL-VERCEL-FREE-TIER-BURST so any future multi-provider experiment dry-runs the per-endpoint RPS before counting the experiment as feasible.

The two-sample Kolmogorov–Smirnov (KS) test computes the maximum absolute difference between two cumulative distribution functions and returns a p-value for the null hypothesis "both samples came from the same distribution." HADF Phase 2-bis Sub-experiment 2 uses KS on the (ttft_s, tps) marginals — cloud vs local Ollama — at p_max threshold 0.01 with min yield 250 records, to test the hypothesis "local inference signatures are statistically distinguishable from cloud-provider signatures, not just visually different." Shipped to the verdict script `scripts/hadf-phase2bis-verdict.py --metric ks` at FT2 PR #536 (2026-05-30). Pre-registration sha256=d4ec4680ef21 locked the thresholds before the experiment came on-line.

Not all features are the same size. The framework's normalization model uses a retroactive power-law fit (R²=0.82 across all prior features) to translate raw minutes-to-ship into comparable Complexity-Unit rates, so a ten-minute typo fix and a two-hour new feature sit on the same scale.

HADF Phase 2-bis Sub-experiment 3 uses signature-delta-ratio to test the central HADF falsification claim — that the same model accessed through different routing paths produces measurably different hardware signatures, in units of the intra-anchor noise floor. Compute: (1) anchor pairs of Anthropic-direct calls produce an intra-anchor Mahalanobis-distance distribution (the noise floor); (2) Bedrock-via-AWS calls to the same Anthropic model produce a between-condition Mahalanobis distance vs the same anchor; (3) ratio = between / intra-anchor-median. PASS threshold > 2.0 (distinguishable beyond noise); FAIL < 1.0 (within noise — HADF falsified for this routing pair); inconclusive band in between. Shipped to verdict script at FT2 PR #539 (2026-05-31). Live smoke-tested against Sub-exp 1A openai+anthropic data: ratio=6.62 (correct PASS verdict). Sub-exp 3 launch blocked on operator AWS Bedrock model access as of 2026-05-31.

Silhouette coefficient measures how similar each data point is to its own cluster vs the next-nearest cluster. Score ≈ 1 = well-separated clusters; ≈ 0 = overlapping; < 0 = misassigned. HADF Phase 2-bis Sub-experiment 1A uses silhouette over (ttft_s, tps) features at k=5 to test the hypothesis "cloud responses cluster by provider × model." Pre-registered pass threshold: silhouette ≥ 0.50 at k=5 AND yield ≥ 600 records. Sub-exp 1A shipped 0.5566 at silhouette 0.5566 (PASS, 2026-05-25). Sub-experiment 1B v2 reduces to k=2 because the scope was narrowed to 2 endpoints (anthropic + google) after free-tier rate-limits on mistral + vercel-ai-gateway forced their deferral.

Stacked PRs let a long line of work ship in reviewable chunks. Branch B branches from A, branch C from B, and so on; each PR targets its parent, not main. The stacked-pr-misfire case study (#19) documents how the pattern fails when a mid-stack branch is rebased and downstream branches fall out of sync.

Each Block-B sub-experiment in HADF Phase 2-bis is independently pre-registered (sha256-locked + signed git tag) before any data lands. Each carries its own metric, threshold, yield kill-criterion, and verdict script. The four shipped sub-experiments: **1A** (cloud replication, n=300 of GPT-4o-mini × Claude × Gemini, silhouette ≥ 0.50 at k=5, PASS 2026-05-25 with silhouette 0.5566); **1B v1** (rate-limited Fire 0 returned 114/200 OK 2026-05-30 — mistral + vercel-ai-gateway hit free-tier 429s); **1B v2** (scope reduction to anthropic + google only, k=2 silhouette, ≥ 300 records, earliest start 2026-06-10, sha256-locked 2026-05-31 via FT2 PR #542); **2** (local vs cloud, Ollama-on-MBA vs aggregated cloud samples, KS-distinguishability p < 0.01, LIVE since 2026-05-30 with ~400 records vs 250 yield); **3** (Bedrock vs Anthropic-direct routing, signature-delta-ratio > 2.0, blocked on AWS Bedrock access). Block A (infrastructure hardening, A0–A12) shipped 2026-05-12; Block C (cross-sub-experiment synthesis case study) fills as each sub-experiment lands its verdict.

CLS tracks how much visible content shifts position unexpectedly during page load (e.g. images loading, fonts swapping). Under 0.1 is "good." Low CLS is important for accessibility — moving targets frustrate users with motor impairments.

Conditional UI uses the navigator.credentials.get({ mediation: "conditional" }) API + an input with autocomplete="username webauthn" to render passkeys inside the browser's native autofill dropdown. The user signs in with one tap from autofill rather than clicking through a sign-in page. fitme-story's /control-room/sign-in fires this on page load; the visible button is the manual fallback.

FIDO2 is the FIDO Alliance's umbrella spec for phishing-resistant authentication: WebAuthn (the browser API) + CTAP (the protocol authenticators speak to clients over USB/NFC/BLE). YubiKeys, Touch ID, Face ID, Windows Hello, and Android Google Password Manager are all FIDO2 authenticators. fitme-story's passkey gate works with all of them via @simplewebauthn.

iron-session is a Node.js library that AES-GCM-encrypts a small JSON payload + an integrity tag and packs it into an HttpOnly, SameSite=Strict cookie. fitme-story's passkey gate mints a session this way (24h hard cap, 12h sliding refresh) after a successful WebAuthn assertion; proxy.ts unseals the cookie on every /control-room/* request. The session ID is also allowlisted in Upstash Redis so revoking a credential clears every session for that operator instantly.

One of Google's Core Web Vitals. LCP measures when the largest visible element (often the hero image or headline) finishes rendering. Under 2.5 seconds is "good." This site targets under 1 second on desktop.

A passkey is a public-key credential bound to a specific website and stored on the user's device (iCloud Keychain, Google Password Manager, Windows Hello, or a hardware key like YubiKey). Sign-in is a biometric tap rather than a typed password. The browser refuses to sign for any origin other than the one the passkey was registered with, which makes phishing structurally impossible. fitme-story uses passkeys to gate /control-room/* operator access (replacing shared HTTP basic-auth).

In WebAuthn, the Relying Party ID identifies which site the credential belongs to — typically the apex domain (e.g. fitme-story.vercel.app). The browser embeds the RP ID into every assertion and the server checks it; a phished page at a look-alike domain will not be allowed to use the real passkey. This origin-binding is why passkeys are phishing-resistant by construction.

Rather than render pages on each request (server-side rendering) or only on the client (SPA), SSG pre-computes every page's HTML at build time and serves it as a static file. fitme-story uses Next.js App Router's SSG for all 38 routes — 0ms server work at request time.

UCC_AUTH_MODE is the env var fitme-story's proxy.ts checks on every request to /control-room/*. Three values: `basic` (HTTP basic-auth via DASHBOARD_USER/DASHBOARD_PASS — the legacy mode for ~30 days through 2026-05-16); `passkey` (iron-session cookie required, redirect to /control-room/sign-in on miss — the steady-state target); `both` (accept either, audit-log which path was used — the cutover window). Default when unset = `basic`. Cutover Parts 1-6 shipped 2026-05-16 flipping basic → both; Part 8 (flip both → passkey + drop DASHBOARD_USER/DASHBOARD_PASS) calendar-gated on/after 2026-05-28 per infra-master-plan-2026-05-12 §4.1. Rollback at any phase = PATCH the env back via Vercel REST API in 30 seconds.

WebAuthn is the W3C specification (Level 3 as of 2024) that defines the browser-side API for creating and asserting public-key credentials. Two ceremonies: registration (generates a keypair, signs an attestation, server stores the public key) and authentication (server issues a challenge, authenticator signs it, server verifies the signature and a monotonic counter to defeat replay). fitme-story uses the @simplewebauthn library on both client and server.