PM Framework — Developer Guide (v1.0 → v7.10)

Audience: developers landing in this codebase who need to understand how the PM framework actually works — not the marketing narrative, not the case-study story arc, but the wiring. If you are about to add a new feature, extend a check code, fix a CI workflow, or bump the framework version, start here.

Current version: v7.10 (shipped 2026-06-10 — GATE_COVERAGE_ZERO observability + measurement-layer field-rename closure; 0 new product-facing gates). Current canonical state (reconciled 2026-06-21): 115 features · 28 instrumented gates (17 write-time + 9 cycle-time + 2 W9 hooks), 25 firing · 0 integrity findings — see docs/FRAMEWORK-FACTS.md. The detailed snapshot in §2.0 below is v7.9.1 (the last full-snapshot revision); v7.10 layered gate-self-observability on top of it. Predecessor v7.9.1 (single-day build window 2026-06-04 — 8 ships, 14 PRs, 0 new enforcement gates per Phase E exit discipline). The v7.9 Phase E validation soak exited cleanly on 2026-06-04. v7.9.1 ships observability surfaces + reusable substrates: F16 try-repo harness (a 3rd gate-test layer), F17 last_fired_at index, F2 Phase 0 reality-check, Dev-env Track B lint/coverage CI (CI workflows 8 → 14), observed-patterns W1–W28 → W1–W32. Post-window (2026-06-07) additions: t14 platforms_tested field + PLATFORMS_TESTED gate (shipped advisory 2026-06-07; promoted to enforced 2026-06-21 via FT2 PR #781 after the clean 14-day B15 window), tracking-drift-check, contract-fixture sampling, and the prereg lock-introducing-commit permit fix. Enforcement total: 38 mechanical gates + 4 advisories (the v7.9 baseline was 37 + 5; PLATFORMS_TESTED moved from the advisory bucket to enforced on 2026-06-21). Shipped via FT2 PR #417 (v7.9) → v7.9.1 PRs #607–#628. For prior versions, see §12 timeline. For the full v7.9.1 outcome, see §2.0. Filename note: the source file stays dev-guide-v1-to-v7-7.md (this page mirrors it) for ref-stability across 16+ cross-references in FT2 + fitme-story. Content tracks the latest framework version (v7.10). Companion docs: docs/architecture/feature-lifecycle-event-catalog.md (event/log/gate catalog with mermaid flow diagrams), docs/skills/architecture.md (skill-by-skill anatomy), docs/skills/evolution.md (full version-by-version history), CLAUDE.md (project rules, fastest reference). Reading order: §0 is a 90-second tour. §1 is audience and reading hints. §1.5 is the glossary. §§ 2–3 give you the mental model. §§ 4–8 are the schemas and contracts you'll edit against. §§ 9–11 are the integrity layer (where failures get caught). § 12 is the compressed timeline. §§ 13–15 are operational walkthroughs.

Table of Contents

• §0. Overview — 90-second tour
• §1. Audience and how to read
• §1.5 Glossary
• §2. Big picture (current state — v7.9.1, Phase E exited)
• §3. Where the code lives
• §4. The skill ecosystem (hub + 11 spokes)
• §5. state.json — the canonical per-feature contract
• §6. Phase lifecycle (9 phases × 4 work types)
• §7. Dispatch model — how skills get invoked
• §8. Cache architecture (L1 per-skill, L2 shared, L3 project)
• §9. Measurement protocol (CU formula, cache_hits, timing)
• §10. Integrity layer — write-time + per-PR + cycle-time + weekly
• §11. Pre-commit hooks and GitHub Actions
• §12. Compressed evolution timeline (v1.0 → v7.9.1)
• §13. Operational walkthrough — adding a new feature
• §14. Operational walkthrough — extending an integrity check code
• §15. Operational walkthrough — bumping the framework version
• §16. References

0. Overview — 90-second tour

What this framework does. Every feature passes through a 9-phase lifecycle (Research → PRD → Tasks → UX → Implement → Test → Review → Merge → Docs) and is gated by automated checks at four cadences. Drift between code and documentation is caught fast.

The 4 enforcement layers (§2.2):

The 1 file you touch most. .claude/features/<name>/state.json — your feature's lifecycle contract. Schema is enforced at write-time.

The 1 command you run most. /pm-workflow <feature-name> — creates state.json, drives phase transitions, dispatches the right skill per phase, gates each transition.

Where to next.

• New to the framework? → §1 (audience) → §1.5 (glossary) → §2 (big picture) → §3 (where the code lives)
• Writing a feature? → §13 walkthrough
• Adding a check code? → §14 walkthrough
• Bumping the framework version? → §15 walkthrough (and: don't forget to bump THIS doc — see §15's "what NOT to skip" callout)

1. Audience and how to read

This guide is for developers. If you are a PM looking for product workflow, read docs/skills/pm-workflow.md. If you are reading the project as evidence of an AI workflow approach, start with docs/case-studies/ (start at 01-onboarding-pilot.mdx on the fitme-story showcase).

The framework is not a single library you import. It is a set of conventions implemented across:

• Markdown documents that describe each skill (.claude/skills/<name>/SKILL.md) and shared state (.claude/shared/*.json).
• Python scripts that enforce or measure invariants (scripts/*.py).
• GitHub Actions workflows that run the scripts on schedules and on every PR (.github/workflows/*.yml).
• A pre-commit hook that runs the same scripts locally before any commit lands (.githooks/pre-commit).
• Per-feature state files that track each in-flight feature's lifecycle (.claude/features/<name>/state.json).

There is no compiled binary. The framework is the union of the conventions above, the scripts that enforce them, and the agents (Claude Code, Claude Desktop, Codex, etc.) that follow them.

1.5 Glossary

Cross-cutting terms used throughout this guide and in commit messages, PR descriptions, and case studies. If a term is unfamiliar in §§ 2–15, look it up here first.

2. Big picture (current state — v7.9.1, Phase E exited)

2.0 Current version snapshot (v7.9.1, 2026-06-04)

v7.9.1 — single-day build window (2026-06-04). Opened at v7.9 Phase E exit and closed the same day: 8 ships across 14 PRs with 0 new enforcement gates (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:

• F16 try-repo harness (PRs #607–#612) — a 3rd gate-test layer: spawns a throwaway git repo and runs the real .githooks/pre-commit against canonical positive/negative fixtures, catching integration-surface bugs the in-process dispatch tests can't see.
• F17 last_fired_at index (#617) — gate-last-fired.json, a derived per-gate index of Mechanism A telemetry (AWS-Config-Rules pattern) so the planned v7.10 GATE_COVERAGE_ZERO meta-check runs O(1) per gate.
• F2 Phase 0 reality-check (#618) — make phase-0-reality-check cross-checks pending tasks vs the last 30 days of git/PR/log evidence, surfacing post-squash-merge state drift before Phase 0 schedules stale work.
• Dev-env Track B + batch (#619, #626, #627) — SwiftLint + ruff + markdownlint + coverage + gitleaks + pip-audit + SBOM + commitlint + shellcheck wired warn-only into CI (workflows 8 → 14).
• F-LAUNCHD-DRIFT-EXTENSION (#621–#624) — cron-context phantom-finding suppression + plist path-resolution health checks.
• Observed-patterns W29–W32 (#620) + F-PHASE-E-ADOPTION-FREEZE-DISCIPLINE (#625) + F-DEPLOYED-URL-PROBE FT2 substrate (#628).

Post-window additions (2026-06-07): t14 platforms_tested field + PLATFORMS_TESTED gate (FT2 #662 / #665 — shipped advisory, promoted to enforced 2026-06-21 via FT2 #781); tracking-drift-check (#659); the prereg lock-introducing-commit permit fix (#660); contract-fixture sampling consumer adoption (fitme-story #209). Shipped advisory/observability; PLATFORMS_TESTED later promoted to enforced (2026-06-21, cadence B15).

Predecessor — v7.9 promotion (2026-05-21): the enforcement-flip release. A single-line edit at scripts/check-state-schema.py:138 flipped BRANCH_ISOLATION_ADVISORY_MODE from True to False, promoting 3 v7.8.1 advisory gates simultaneously to enforced.

Gates promoted (3 advisory → 3 enforced):

All four §2.2 promotion criteria (coverage ≥ 7d, no false positives, no silent skips, reversibility < 5 min) were met. Phase E validation soak runs 2026-05-21 → 2026-06-04.

Gates that stay advisory by design (NOT promoted at v7.9):

Reversibility: single-line revert + commit + merge to main = < 5 min.

Full lineage: v7.9 case study | v7.9 entrypoint | FT2-FH-003 honesty ledger entry.

2.1 What the framework does, in one sentence

It enforces that every feature passes through a defined lifecycle (Research → PRD → Tasks → UX → Implement → Test → Review → Merge → Docs), records its state and timing in a machine-readable file, and is gated by automated checks at write-time, per-PR, and on a 72h schedule so that drift between code and documentation is caught fast.

2.2 The four enforcement layers (v7.9 — 3 advisories promoted to enforced 2026-05-21)

┌─────────────────────────────────────────────────────────────────────┐
│  Layer 1 — WRITE-TIME (pre-commit hooks, ~3-5s)                     │
│  Fires on every `git commit`. Blocks the commit if it fails.        │
│  Scripts: scripts/check-state-schema.py + check-case-study-preflight │
│  Check codes: SCHEMA_DRIFT, PR_NUMBER_UNRESOLVED,                    │
│               PHASE_TRANSITION_NO_LOG, PHASE_TRANSITION_NO_TIMING,   │
│               BROKEN_PR_CITATION (write-time),                       │
│               CASE_STUDY_MISSING_TIER_TAGS                           │
└─────────────────────────────────────────────────────────────────────┘
              │                                     ▲
              │ commit lands                        │ also runs as
              ▼                                     │ rear-guard
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 2 — PER-PR (GitHub Actions, ~1-3min per push)                │
│  Workflow: .github/workflows/pr-integrity-check.yml                 │
│  Compares PR HEAD findings vs origin/main baseline (worktree).      │
│  Status check: pm-framework/pr-integrity → required for merge.      │
└─────────────────────────────────────────────────────────────────────┘
              │ PR merges to main
              ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 3 — 72h CYCLE (GitHub Actions cron, every 3 days at 04:00Z)  │
│  Workflow: .github/workflows/integrity-cycle.yml                    │
│  Script: scripts/integrity-check.py (13 cycle-time + 1 advisory)    │
│  Snapshots ledger to .claude/integrity/snapshots/.                  │
│  Opens issue on regression vs prior snapshot.                       │
└─────────────────────────────────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 4 — WEEKLY (GitHub Actions cron, Mondays 05:00Z)             │
│  Workflow: .github/workflows/framework-status-weekly.yml            │
│  Snapshots measurement-adoption-history.json + documentation-debt.  │
│  Opens issue on adoption regression. OBSERVATIONAL (does not block).│
└─────────────────────────────────────────────────────────────────────┘

2.3 The 4 mechanically unclosable Class B gaps (v7.8 closed Gap 1 in advisory; v7.9 promoted it to enforced)

The four layers above catch what a deterministic script can catch. Five gaps remained Class B (agent-attention, judgment, or external-dependency) at v7.7. v7.8 closed Gap 1 (cache_hits[] writer-path) in advisory mode via Mechanism C — capture is automatic, but writer-path adoption was not yet enforced. v7.9 (2026-05-21) promoted Gap 1 to enforced via CACHE_HITS_AUTO_INSTRUMENTATION_DRIFT (cycle-time gate, advisory → enforced once 14-day Mechanism A telemetry showed 0 zero-candidate firings). Same release also promoted 2 v7.8.1 branch-isolation advisories — BRANCH_ISOLATION_VIOLATION Mode B (infra commit-level) + Mode C (per-state.json mutation) + FEATURE_CLOSURE_COMPLETENESS (write-time). The list is documented in docs/case-studies/meta-analysis/unclosable-gaps.md:

1. cache_hits[] writer-path adoption — ✅ CLOSED at v7.9 (was issue #140, agent-must-remember-to-log-hits, the original Class B gap). Closed via the v7.8 advisory PostToolUse:Read hook (Mechanism C) → promoted to enforced at v7.9 via CACHE_HITS_AUTO_INSTRUMENTATION_DRIFT. Pre-Mechanism-C features (created_at < 2026-05-02) remain exempt from CACHE_HITS_EMPTY_POST_V6.
2. cu_v2 factor correctness — magnitudes are judgment-based.
3. T1/T2/T3 tag correctness — preflight checks presence, not whether the tag is right.
4. Tier 2.1 real-provider auth — physical device required.
5. Tier 3.3 external replication — external operator required.

If you are a developer reading this guide, your code rarely needs to reason about Class B gaps directly — they exist as documented exceptions to the "everything is mechanical" framing. But if you are adding a check code, ask: "is what I'm checking deterministic, or am I trying to mechanize a judgment?" The latter belongs in the Class B inventory, not in check-state-schema.py.

2.4 The v7.8 bridge mechanisms (A–F)

v7.8 (shipped 2026-05-04 across 9 PRs: #173 + #185–#189 + #193–#195) added six cooperating mechanisms that close silent-pass and inter-agent context-handoff gaps without yet promoting them to Class A. All ship advisory; v7.9 (measurement window opens 2026-05-11) promotes the proven ones to enforced.

Full design: docs/superpowers/specs/2026-05-02-framework-v7-8-and-v7-9-bridge-design.md. Live append-only journal: docs/case-studies/framework-v7-8-bridge-case-study.md.

The v7.8 design principle: every new mechanism ships with a coverage ledger (Mechanism A) so we can measure its effective coverage before promoting to enforced. v7.7's CACHE_HITS_EMPTY_POST_V6 shipped at 0/46 effective coverage for 4 days because the gate read created_at while 43/46 features used the legacy created key — a silent-pass that Mechanism A would have caught immediately. v7.8's lesson is that we don't trust a gate until its coverage ledger says it's actually firing.

3. Where the code lives

FitTracker2/
├── .claude/
│   ├── features/<feature-name>/state.json   ← per-feature state (1 per feature)
│   ├── logs/<feature-name>.log.json         ← per-feature contemporaneous log
│   ├── shared/                              ← shared cross-feature state
│   │   ├── framework-manifest.json           ← framework version + capabilities
│   │   ├── feature-registry.json             ← list of all features
│   │   ├── change-log.json                   ← cross-feature change events
│   │   ├── measurement-adoption.json         ← v6.0 adoption ledger (current)
│   │   ├── measurement-adoption-history.json ← v6.0 adoption (append-only)
│   │   ├── documentation-debt.json           ← Tier 3.2 debt ledger
│   │   ├── case-study-monitoring.json        ← case-study health
│   │   ├── skill-routing.json                ← skill phase routing config
│   │   └── … (~24 shared state files total)
│   ├── skills/<skill-name>/SKILL.md         ← agent-facing skill prompt (12 skills since 2026-05-14; was 11 through v7.8.4)
│   ├── integrations/<service>/              ← per-service adapters (ga4, sentry…)
│   ├── cache/                                ← learning cache (L1 + L2 _shared/ + L3 _project/)
│   └── integrity/
│       ├── README.md                         ← integrity layer canonical entry
│       ├── observed-patterns.md              ← gate-firing pattern catalog (v7.8.5; make observed-patterns)
│       └── snapshots/                        ← 72h cycle snapshots (committed)
├── scripts/
│   ├── check-state-schema.py                 ← write-time + cycle (state.json + branch-isolation + state_owner gates)
│   ├── check-case-study-preflight.py         ← write-time (case studies)
│   ├── integrity-check.py                    ← cycle-time check codes + advisories
│   ├── ensure-pr-cache-fresh.py              ← PR_CACHE_STALE auto-refresh (v7.8.4)
│   ├── observe-cache-hit.py                  ← Mechanism C PostToolUse:Read capture (v7.8)
│   ├── check-branch-drift.py                 ← W9 branch-drift PostToolUse:Bash alert (v7.8.5)
│   ├── check-ssh-agent.sh                    ← W1 ssh-agent SessionStart preflight (v7.8.6)
│   ├── membrane-status.py                    ← Mechanism F membrane readout
│   ├── preflight.py                          ← unified pre-work aggregator (v7.8.6)
│   ├── cross-layer-freshness.py              ← W20 freshness scan (v7.8.6)
│   ├── daily-integrity-checkpoint.py         ← daily launchd cron job
│   ├── integrity-diff.py                     ← diff vs baseline anchor (v7.8.6)
│   ├── snapshot-phase-completion.sh          ← per-phase off-SSD backup (v7.8.3)
│   ├── measurement-adoption-report.py        ← Tier 1.1 ledger generator
│   ├── append-feature-log.py                 ← contemporaneous log writer
│   ├── documentation-debt-report.py          ← Tier 3.2 ledger generator
│   ├── runtime-smoke-gate.py                 ← Tier 2.1 smoke runner
│   └── test-v7-5-pipeline.sh                 ← mechanical-enforcement regression test
├── .githooks/pre-commit                       ← orchestrates write-time checks
├── .github/workflows/
│   ├── ci.yml                                ← Xcode build + test
│   ├── integrity-cycle.yml                   ← 72h cycle (cron 0 4 */3 * *)
│   ├── pr-integrity-check.yml                ← per-PR (v7.6 Phase 2a)
│   └── framework-status-weekly.yml           ← weekly cron (v7.6 Phase 2c)
├── docs/
│   ├── architecture/
│   │   └── dev-guide-v1-to-v7-7.md          ← THIS FILE
│   ├── skills/
│   │   ├── architecture.md                   ← skill-by-skill anatomy
│   │   ├── evolution.md                      ← full version-by-version history
│   │   └── pm-workflow.md                    ← user-facing PM workflow doc
│   ├── case-studies/                         ← all shipped case studies
│   │   ├── data-integrity-framework-v7.5-case-study.md
│   │   ├── mechanical-enforcement-v7-6-case-study.md
│   │   └── meta-analysis/unclosable-gaps.md
│   ├── process/                              ← process docs (Tier groundwork)
│   ├── product/                              ← PRDs, metrics, backlog
│   └── design-system/                        ← UX foundations + component memory
├── trust/
│   └── audits/2026-04-21-gemini/             ← independent audit + remediation
└── CLAUDE.md                                 ← project rules (fastest reference)

Companion repo (separate git): /Volumes/DevSSD/fitme-story — Next.js showcase site. Trust page (/trust/audits/2026-04-21-gemini) and case-studies index live there. The fitme-story repo cross-links to the main repo's case studies via raw GitHub URLs.

4. The skill ecosystem (hub + 11 spokes)

The framework runs as 12 skills (since 2026-05-14; was 11 through v7.8.4) following a hub-and-spoke pattern:

• Hub: pm-workflow — owns the lifecycle, dispatches work to spokes, gates phase transitions.
• Spokes (11): brainstorm-pm (added 2026-05-14, P1.0b — Phase 0 default new-feature entry point), research, ux, design, dev, qa, analytics, cx, marketing, release, ops — each owns a phase or cross-cutting responsibility.

Each skill has:

• An agent-facing prompt at .claude/skills/<name>/SKILL.md. The agent reads this when the skill is loaded.
• A markdown doc at docs/skills/<name>.md for human reference.
• A routing config entry in .claude/shared/skill-routing.json declaring which phases load this skill on demand (v5.0 skill-on-demand optimization).

4.1 Skill loading model (v5.0+)

Before v5.0, all 11 skills (the v2.0–v7.8.4 baseline) loaded into context on every session. After v5.0:

• The pm-workflow hub always loads.
• Spokes load on demand based on phase_skills in skill-routing.json.
• Each spoke has a compressed_view field in its cache entry (~200 words) loaded by default; full expansion happens when the agent calls the skill.
• Net savings: ~54K tokens per session vs. v4.x.

4.2 Adding a new skill

1. Create .claude/skills/<name>/SKILL.md with the agent-facing prompt.
2. Create docs/skills/<name>.md for human reference.
3. Add an entry to .claude/shared/skill-routing.json:

   {
     "phase_skills": {
       "<phase>": ["<existing-skills>", "<name>"]
     },
     "compressed_views": {
       "<name>": "≤200-word summary of what the skill does"
     }
   }

4. Bump framework-manifest.json.structure.spoke_skills (currently 10).

5. state.json — the canonical per-feature contract

Every feature has a .claude/features/<name>/state.json file. This file is the single source of truth for that feature's lifecycle state. The integrity layer reads it; the dashboard reads it; the case study links to it.

5.1 Required top-level fields

5.2 Phase-specific sub-fields

Each entered phase typically also has:

• phases.<phase>.completed_at — when the phase finished (set on transition out)
• phases.<phase>.gate_passed — boolean if a hard gate (e.g., review approval) was required
• phases.merge.pr_number — set during the merge phase; verified by the PR_NUMBER_UNRESOLVED check

5.3 Schema enforcement

scripts/check-state-schema.py reads each staged state.json (or, with --all, every state.json in the repo) and emits findings:

• SCHEMA_DRIFT — legacy phase key present
• NO_PHASE — neither current_phase nor phase present
• INVALID_JSON — file does not parse
• PHASE_TRANSITION_NO_LOG (v7.6) — phase changed but no log entry within last 15 min
• PHASE_TRANSITION_NO_TIMING (v7.6) — phase changed but no timing.phases.<new>.started_at and/or old-phase ended_at update

The --staged flag scopes the check to staged files (used by the pre-commit hook). The FORCE_TRANSITION_CHECKS=1 env var unscopes for testing.

6. Phase lifecycle (9 phases × 4 work types)

The PM framework defines a 9-phase pipeline for full features. Smaller work types skip subsets of phases.

6.1 Work types

Defined in CLAUDE.md (Work Item Types section):

• Feature — full 9-phase. New capabilities. Weight 1.0 in CU formula.
• Enhancement — 4-phase (Tasks → Implement → Test → Merge). Improvements to shipped features. Weight 0.8.
• Fix — 2-phase (Implement → Test). Bug fixes. Weight 0.5.
• Chore — 1-phase (Implement). Docs, config. Weight 0.3.
• Refactor (v2) — like Feature but v1 exists as reference. Weight 0.9.
• Framework — internal infrastructure (e.g., this dev guide, v7.6 itself). No fixed weight; choose nearest analog.

6.2 The "v2/" subdirectory rule

When refactoring a UI screen, the v2 file lives at <parent>/v2/<ScreenName>.swift. Same Swift type name; v1 stays in repo as historical artifact (removed from build target via project.pbxproj). Full rule: CLAUDE.md → "## UI Refactoring & V2 Rule".

7. Dispatch model — how skills get invoked

The agent (Claude Code, Codex, etc.) interacts with the framework primarily via slash commands that invoke skills:

/pm-workflow <feature-name>      ← hub: starts/resumes a feature
/dev                              ← spoke: implementation work
/qa                               ← spoke: test work
/design / /ux                     ← spoke: design + UX
/analytics / /cx / /research      ← spoke: cross-cutting
/marketing / /release / /ops      ← spoke: support

When the user types a slash command, the runtime looks up the corresponding SKILL.md and loads its content into the agent's context. The agent then follows the skill's instructions.

7.1 Routing logic (v5.2 Dispatch Intelligence)

scripts/dispatch-intelligence.py and .claude/shared/dispatch-intelligence.json define a 3-stage dispatch pipeline:

1. Tool budget check — does the requested skill fit within the per-session tool budget?
2. Hardware affinity (v7.0 HADF) — does the current device profile favor a particular skill variant?
3. Skill execution — invoke the skill with appropriate cache pre-load.

For most local Claude Code sessions, the dispatch pipeline is invisible — it just makes routing decisions before the agent picks up the work.

7.2 Concurrent dispatch hygiene

Per CLAUDE.md "## Concurrent Dispatch Hygiene": parallel subagent dispatch is currently blocked at the framework layer (F6–F9 framework bugs). Default to serial. Re-validation gate after upstream patches: docs/superpowers/plans/f6-f9-reproducer/proof-of-fix-tests.md.

8. Cache architecture (L1 per-skill, L2 shared, L3 project)

The framework treats agent reasoning as a cache hierarchy:

8.1 Cache hits — the writer path

When an agent reuses a piece of prior knowledge (a skill output, a doc snippet, a prior plan, a memory entry) instead of re-deriving it, that's a cache hit. The agent logs it via:

python3 scripts/append-feature-log.py \
  --feature <feature-name> \
  --event-type code_change \
  --summary "<what changed>" \
  --artifact "<file>" \
  --cache-hit L2 \
  --cache-key "<a stable key>" \
  --cache-hit-type {adapted,exact,miss} \
  --cache-skill "<source skill or pattern reused>"

The script writes the entry to .claude/logs/<feature>.log.json AND appends to state.json.cache_hits[]. The dual-write is intentional: logs are flat-file event streams, state.json is the canonical roll-up.

8.2 What the framework can and cannot mechanize

• Mechanizable: the writer path (CLI accepts the flags, schema validates the entry, count rolls up to measurement-adoption.json).
• Not mechanizable: the recognition that something is a cache hit. This is Class B Gap 1. The framework provides the infrastructure; the agent must remember to use it.

9. Measurement protocol (CU formula, cache_hits, timing)

Shipped at v6.0 (2026-04-16). Hardened across v7.5 → v7.6. Canonical doc: docs/case-studies/normalization-framework.md.

9.1 The CU formula (v6.0)

CU = Tasks × Work_Type_Weight × (1 + sum(Complexity_Factors))

Work-type weights:

Complexity factors (additive):

The agent declares factors in state.json.complexity.factors_applied[] with a reason string per factor. The script does not auto-derive magnitudes — that's Class B Gap 2.

9.2 Velocity reporting

After phase completion, state.json.timing.total_wall_time_minutes should be set. Velocity = total_wall_time_minutes / CU. The v6.0 protocol requires three baseline comparisons:

• vs Historical (Onboarding v2 = 15.2 min/CU)
• vs Rolling (mean of last 5 features)
• vs Same-Type (mean of last 3 same work_type)

scripts/measurement-adoption-report.py reports per-feature adoption status across 4 dimensions: timing_wall_time, per_phase_timing, cache_hits, cu_v2. A feature is "fully adopted" only when all 4 dimensions are populated.

9.3 Tier tags (T1/T2/T3)

Every quantitative claim in a case study, PRD, or meta-analysis should carry a tier tag:

• T1 (Instrumented) — pulled from a JSON file or deterministic command output.
• T2 (Declared) — declared by the author from a non-instrumented source (e.g., human-counted from git log).
• T3 (Narrative) — narrative inference; should be avoided in v7.6+ case studies.

Forward-only: case studies dated >= 2026-04-21 get file-level tag-presence enforcement at write-time (CASE_STUDY_MISSING_TIER_TAGS). The preflight checks that at least one T1/T2/T3 tag exists in the scoped file. Tag exhaustiveness and correctness are Class B Gap 3 — code review still checks whether each metric has the right tag.

10. Integrity layer — write-time + per-PR + cycle-time + weekly

10.1 Check codes (38 mechanical + 4 advisories — PLATFORMS_TESTED promoted advisory → enforced 2026-06-21, FT2 PR #781)

v7.9 promotion (2026-05-21): 3 v7.8.1 advisories promoted to enforced: BRANCH_ISOLATION_VIOLATION Mode B (infra commit-level) + Mode C (per-state.json mutation) + FEATURE_CLOSURE_COMPLETENESS (write-time). Single-flag flip at scripts/check-state-schema.py:138 (BRANCH_ISOLATION_ADVISORY_MODE = True → False). All 4 §2.2 promotion criteria met against 14-day Mechanism A telemetry (18 + 13 + 13 firings, 0 zero-candidate, 0 false positives). Phase E validation soak runs 2026-05-21 → 2026-06-04. Reversibility: single-line revert.

When a gate fires, check the Observed Patterns Catalog (§10.5) FIRST — most fire-patterns are documented there with a signal-vs-noise rule and a silence path.

10.2 The 72h cycle

Defined in .github/workflows/integrity-cycle.yml. Cron: 0 4 */3 * * (every 3 days at 04:00 UTC). Steps:

1. Checkout repo with fetch-depth: 0.
2. Run integrity-check.py --snapshot <new> --compare-to <prev> --snapshot-trigger scheduled_cycle.
3. Commit the new snapshot to .claude/integrity/snapshots/.
4. If a regression is detected, open a regression-labeled issue.

10.3 The per-PR layer

Defined in .github/workflows/pr-integrity-check.yml (v7.6 Phase 2a). Steps:

1. Checkout PR HEAD.
2. Run schema check + integrity check + measurement-adoption against PR HEAD.
3. Capture origin/main baseline via git worktree add /tmp/main-tree origin/main.
4. Compute delta = pr_findings - main_findings.
5. Set pm-framework/pr-integrity commit status to failure if any required command exits non-zero or if delta > 0.
6. Sticky comment with marker <!-- pm-framework-pr-integrity-bot --> updates in place and reports command exit codes.
7. try-repo-harness job (v7.9.1, F16): spawns throwaway git repos and runs the real .githooks/pre-commit against canonical per-gate fixtures (15/16 write-time gates + the gate-coverage contract test). ~15s; catches integration-surface bugs the in-process dispatch tests can't see.

10.4 The weekly cycle

Defined in .github/workflows/framework-status-weekly.yml (v7.6 Phase 2c). Cron: 0 5 * * 1 (Mondays 05:00 UTC, 1h after the 72h cycle to avoid runner queue contention). Steps:

1. Snapshot measurement-adoption history with --snapshot-trigger weekly_status.
2. Compare current vs prior history snapshot.
3. Open issue if fully_adopted or any_adopted decreased.
4. Observational only — never blocks merges.

10.5 Observed Patterns Catalog (v7.8.5)

When a gate fires, the finding alone does not tell you whether it is a real problem or an expected artifact (a squash-merge leaving no branch attribution, an empty PR cache, a heuristic over-trigger, etc.). The Observed Patterns Catalog at .claude/integrity/observed-patterns.md is the canonical manifest of every recognized fire-pattern. Each entry carries a trigger, a why-expected classification (by-design / cleanup-artifact / silent-pass-then-fixed / heuristic-FP / schema-drift), a distinguishing-real-signal rule, and a silence path.

• Coverage (current): 23 gate-firing patterns (Section 1, #1–#23) + 32 workflow/operational patterns (Section 2, W1–W32; W29–W32 added at v7.9.1).
• CLI: make observed-patterns.
• Preflight-loaded by /pm-workflow and referenced by all spoke skills.
• Operator obligation (mandatory): when any framework gate or advisory fires, the FIRST step is to consult this catalog. Apply the documented remediation if the pattern matches; investigate only if novel; and append a new entry to the catalog before the feature that surfaced the novel pattern is closed. The catalog is append-only-by-default.

The catalog is the human-facing companion to the Mechanism A coverage ledger (§2.4): Mechanism A tells you a gate fired; the catalog tells you what the firing means.

10.6 Real-time + daily observability surfaces (v7.8.5 → v7.8.6)

Beyond the four scheduled enforcement layers, the framework runs several lightweight read/warn surfaces:

11. Pre-commit hooks and GitHub Actions

11.1 Installing the pre-commit hook

make install-hooks   # symlinks .githooks/pre-commit to .git/hooks/pre-commit

11.2 What the hook runs

python3 scripts/check-state-schema.py --staged || exit 1
python3 scripts/check-case-study-preflight.py --staged || exit 1

Both scripts exit non-zero on findings. Emergency bypass: git commit --no-verify. The cycle layer still catches the issue 0–72h later, so bypass is not silent.

11.3 GitHub Actions inventory

v7.9.1 grew the CI workflow count from 8 → 14 baseline (the 7 dev-env additions above; all warn-only per Phase E exit discipline). pr-integrity-check.yml also gained the F16 try-repo-harness job (§10.3).

Local (launchd) cron — not a GitHub Action:

11.4 Security note for workflow files

All dynamic values used inside run: blocks MUST be routed through the env: block, never via ${{ }} interpolation directly into shell. This prevents the GitHub Actions injection vector (see github.blog reference). The pre-commit hook for workflow files (security_reminder_hook.py) blocks writes that violate this. Both v7.6 workflows (pr-integrity-check.yml, framework-status-weekly.yml) follow this pattern.

12. Compressed evolution timeline (v1.0 → v7.9.1)

Full per-version detail: docs/skills/evolution.md. This section is the compressed dev-only summary — what each version changed structurally.

| v7.9.1 | 2026-06-04 | Single-day build window — 8 ships / 14 PRs / 0 new enforcement gates (Phase E exit discipline). Observability + substrates only: F16 try-repo harness (3rd gate-test layer — throwaway repo + real pre-commit; PRs #607–#612), F17 gate-last-fired.json derived index (#617), F2 make phase-0-reality-check (#618), Dev-env Track B + batch (SwiftLint/ruff/markdownlint/coverage/gitleaks/pip-audit/SBOM/commitlint/shellcheck warn-only; CI workflows 8 → 14; #619/#626/#627), F-LAUNCHD-DRIFT-EXTENSION (#621–#624), observed-patterns W29–W32 (#620), F-PHASE-E-ADOPTION-FREEZE-DISCIPLINE (#625), F-DEPLOYED-URL-PROBE substrate (#628). Post-window (2026-06-07): t14 platforms_tested field + advisory PLATFORMS_TESTED gate (#662/#665 — promoted to enforced 2026-06-21 via FT2 #781, cadence B15), tracking-drift-check (#659), prereg lock-introducing-commit permit (#660), contract-fixture sampling (fitme-story #209). | The current state. What's new for a dev: a 3rd test layer (try-repo) runs on every PR; platforms_tested is a new state.json field whose gate shipped advisory at complete and was promoted to enforced 2026-06-21; 7 new warn-only CI workflows; make phase-0-reality-check + make tracking-drift-check are available. As of 2026-06-21, PLATFORMS_TESTED now blocks a complete transition with no platform set, in addition to the v7.9 gate set. |

12.1 Version-bump policy

A major-version bump (e.g., v7.6 → v7.7) requires:

1. A new structural capability — not just code changes within an existing capability.
2. A propagated update across surfaces — manifest, CLAUDE.md, evolution doc, case study, and trust-page integration where relevant.
3. A measurement that the change is real — pipeline test, integrity check, or instrumented data.

Minor bumps (e.g., v7.5 hardening commits) extend an existing capability without introducing a new layer.

13. Operational walkthrough — adding a new feature

You are adding a new feature called widget-customization. Here's the full sequence.

13.0 Preflight (Phase 0.0, mandatory since v7.8.6)

Before any work, run the unified preflight aggregator:

make preflight WORK_TYPE=feature FEATURE=widget-customization

This runs every pre-work check (W1 ssh-agent, PR-cache freshness, branch isolation, integrity findings, drift-vs-anchor, doc-debt, adoption baseline) and auto-chains make freshness-check (W20 — confirms your mental model isn't stale vs origin/main). Results land in .claude/shared/preflight-cache.json, which every spoke skill reads. If preflight surfaces a blocker (e.g., you're on main and about to touch infra paths, which trips branch-isolation), resolve it before starting.

13.1 Bootstrap

/pm-workflow widget-customization

The hub creates .claude/features/widget-customization/state.json with:

{
  "name": "widget-customization",
  "work_type": "feature",
  "current_phase": "research",
  "created": "<now ISO>",
  "phases": {"research": {"started_at": "<now>"}},
  "tasks": [],
  "complexity": {"cu_version": 2, "view_count": 0, "factors_applied": []},
  "timing": {"session_start": "<now>", "phases": {"research": {"started_at": "<now>"}}},
  "cache_hits": []
}

It also creates .claude/logs/widget-customization.log.json with a phase_started event.

13.2 Phase progression

For each phase transition (e.g., research → prd):

1. Run the phase-specific work (research → write docs/product/research/widget-customization.md).
2. Update state.json: set phases.research.completed_at, set current_phase = "prd", add phases.prd.started_at.
3. Append a phase_transition log event via append-feature-log.py.
4. Commit. The pre-commit hook will:
   • Verify current_phase (not phase) — SCHEMA_DRIFT.
   • Verify the log entry exists within 15 min — PHASE_TRANSITION_NO_LOG.
   • Verify phases.prd.started_at is set — PHASE_TRANSITION_NO_TIMING.

13.3 During implementation

Log cache hits as you go:

python3 scripts/append-feature-log.py \
  --feature widget-customization \
  --event-type code_change \
  --summary "<what>" \
  --artifact "<file>" \
  --cache-hit L2 \
  --cache-key "<stable key>" \
  --cache-hit-type adapted \
  --cache-skill "<source>"

Update state.json.complexity.factors_applied[] as factors become known (e.g., when you add a new view, set view_count; if you discover a new model is needed, set new_types_count).

13.4 Merge phase

1. PR opens. The per-PR bot fires automatically.
2. If the bot fails the pm-framework/pr-integrity status check, fix the new findings before requesting review.
3. After merge, set state.json.phases.merge.pr_number to the merged PR number. The pre-commit verifies it against a cached gh pr list result when gh is available (PR_NUMBER_UNRESOLVED).

13.5 Docs phase + close

1. Write docs/case-studies/widget-customization-case-study.md.
2. The pre-commit will scan it for:
   • PR citations (PR #N or pull/N) — BROKEN_PR_CITATION.
   • Missing file-level T1/T2/T3 tag in scoped post-2026-04-21 case studies — CASE_STUDY_MISSING_TIER_TAGS.
3. Set current_phase = "complete". Set phases.docs.completed_at. Set timing.total_wall_time_minutes (sum of per-phase elapsed).
4. Add the case study to feature-registry.json and to fitme-story content/04-case-studies/<NN>-<slug>.mdx if it's showcase-worthy.

14. Operational walkthrough — extending an integrity check code

You want to add a new check code, e.g., MISSING_METRIC_BASELINE (a feature in complete phase whose PRD has no baseline number set). Here's the sequence.

14.1 Decide the layer

• Should it block at write-time? (Cheap and immediate; agent corrects mid-session.)
• Should it run only on the cycle? (More expensive to surface, but catches cross-session drift.)
• Should it run per-PR? (Catches before merge; status-check enforced.)

Most checks should be cycle-time first; promote to write-time once the false-positive rate is < 1%.

14.2 Add the cycle-time check

1. Open scripts/integrity-check.py.
2. Add a new function:

   def check_missing_metric_baseline(state: dict, name: str) -> list[Finding]:
       if state.get("current_phase") != "complete":
           return []
       prd_path = REPO_ROOT / "docs" / "product" / "prd" / f"{name}.md"
       if not prd_path.exists():
           return []
       prd = prd_path.read_text()
       if not re.search(r"baseline:\s*\d", prd, re.IGNORECASE):
           return [Finding("MISSING_METRIC_BASELINE", name, f"PRD has no baseline number")]
       return []

3. Call it from the main loop alongside other check fns.
4. Add a row to the check-code table in CLAUDE.md "Data Integrity Framework" section.

14.3 Add a synthetic-violation test

Open scripts/test-v7-5-pipeline.sh. Add a new assertion:

# Test N: MISSING_METRIC_BASELINE fires on PRD without baseline
echo "test N: MISSING_METRIC_BASELINE fires"
mkdir -p docs/product/prd
echo "# fake PRD without baseline" > docs/product/prd/widget-customization.md
out=$(python3 scripts/integrity-check.py --findings-only)
if echo "$out" | grep -q "MISSING_METRIC_BASELINE"; then
  echo "  ✓ fired"
else
  echo "  ✗ did not fire"; exit 1
fi
rm docs/product/prd/widget-customization.md

14.4 Promote to write-time later

Once the cycle-time check is stable, copy the check function into scripts/check-state-schema.py's validate_file() (with enforce_transition semantics if appropriate), add the --staged invocation to .githooks/pre-commit, and add a write-time test assertion.

15. Operational walkthrough — bumping the framework version

You shipped a structural capability that meets §12.1 criteria. The checklist below is the full propagation sequence. Run it top-to-bottom; if you skip a step, the framework will drift between surfaces and the next operator (often you, two weeks later) will hit a confusing inconsistency.

15.1 The checklist (10 steps)

1. Bump the manifest. Edit .claude/shared/framework-manifest.json: bump framework_version (e.g., 7.6 → 7.7); update description; add new capability flags to capabilities; add a new top-level block v<X>_<name> mirroring the v7_6_mechanical_enforcement shape.
2. Update CLAUDE.md. Update the "## Data Integrity Framework" header. Add new check codes to the Write-time gates list. Add new defenses to the appropriate block. Update "## Known Mechanical Limits" if Class B gaps changed.
3. Update docs/skills/evolution.md. Update the > **Status:** v<X> line. Add a new dated note. Add a new row to the version table at the bottom.
4. Update the FT2 canonical dev guide. Bump the title (v1.0 → v<X>) in docs/architecture/dev-guide-v1-to-v7-7.md. Bump the "Current version" callout at the top. Add a new row to the §12 timeline table. If the change introduced new gates, update the §10.1 check-code table AND the §2.2 layer diagram. If you promoted advisories to enforced, add an §2.0 snapshot block.
5. Update THIS page. Mirror the same changes into fitme-story/content/framework/dev-guide.md (the Next.js render source). The FT2 → fitme-story sync script handles src/data/docs/docs/architecture/dev-guide-v1-to-v7-7.md automatically, but THIS file is independent.
6. Write the case study. Create docs/case-studies/<slug>-v<X>-case-study.md. Follow mechanical-enforcement-v7-6-case-study.md as the format reference. T1/T2/T3 tier tags are required forward of 2026-04-21 — the pre-commit hook will block the commit otherwise.
7. Update memory + mirrors. Update repo-root project_*.md mirror files where relevant. Add a memory entry under ~/.claude/projects/.../memory/project_<slug>.md. Update MEMORY.md index.
8. Cross-repo. If user-visible, add a new MDX case study slot in fitme-story/content/04-case-studies/. If it relates to the trust page, append a section to the appropriate trust subroute.
9. Commit + push. Pre-commit hooks catch tier-tag gaps in the case study and phase-transition discipline failures. Fix and re-commit if any fire.
10. Verify. Run bash scripts/test-v7-5-pipeline.sh — all assertions should pass. If you added a new check code (per §14), the count line in the script header updates.

15.2 What NOT to skip — the dev-guide drift trap

The most common failure mode is finishing steps 1–3 (manifest, CLAUDE.md, evolution doc) and then forgetting steps 4 + 5 (the dev guide canonical + this page). The result: CLAUDE.md says "current version v7.9," framework-manifest.json says "framework_version": 7.9, and yet the FT2 canonical dev-guide still says "v1.0 → v7.8.6" in its title. Operators landing on it think the framework is days behind reality.

Concrete example. The v7.9 promotion (shipped 2026-05-21 via FT2 PR #417) bumped CLAUDE.md, the manifest, and THIS page. It missed the FT2 canonical dev-guide and its sync mirror. The drift was caught + fixed 3 days later in the same PR that introduced this callout.

Pre-flight check (do this before pushing the bump):

grep -nE '^# .* \(v1\.0 → ' \
  /Volumes/DevSSD/FitTracker2/docs/architecture/dev-guide-v1-to-v7-7.md \
  /Volumes/DevSSD/fitme-story/content/framework/dev-guide.md

Both files should show the same v<X> in their H1. If they diverge, finish step 4 + 5 before pushing.

15.3 Version-bump criteria (when does a change qualify?)

A major bump (e.g., v7.6 → v7.7) requires:

1. A new structural capability — not just code changes within an existing capability.
2. A propagated update across surfaces — manifest, CLAUDE.md, evolution doc, case study, both dev guides, trust-page integration where relevant.
3. A measurement that the change is real — pipeline test, integrity check, or instrumented data.

Minor bumps (e.g., v7.5 → v7.5.1) extend an existing capability without introducing a new layer.

16. References

Canonical docs

• CLAUDE.md — project rules (always loaded; fastest reference)
• docs/architecture/feature-lifecycle-event-catalog.md — companion to this guide; the event/log/gate catalog (artifact stack, trigger stack, gate stack, phase-by-phase event matrix, mermaid flow diagrams, worked example)
• docs/skills/architecture.md — skill-by-skill anatomy
• docs/skills/evolution.md — full version-by-version history
• docs/skills/pm-workflow.md — user-facing PM workflow
• .claude/integrity/README.md — integrity layer canonical entry
• .claude/integrity/observed-patterns.md — Observed Patterns Catalog (gate-firing pattern manifest; consult FIRST when a gate fires; make observed-patterns)

Case studies (most relevant for this guide)

• docs/case-studies/data-integrity-framework-v7.5-case-study.md — v7.5 narrative
• docs/case-studies/mechanical-enforcement-v7-6-case-study.md — v7.6 narrative + comprehensive CU + workload analysis
• docs/case-studies/framework-v7-7-validity-closure-case-study.md — v7.7 narrative
• docs/case-studies/framework-v7-8-bridge-case-study.md — v7.8 live append-only journal (silent-pass prevention + inter-agent awareness)
• docs/case-studies/meta-analysis/unclosable-gaps.md — 5 mechanically unclosable Class B gaps (Gap 1 closed in v7.8 advisory)
• docs/case-studies/normalization-framework.md — CU formula reference
• docs/case-studies/data-quality-tiers.md — T1/T2/T3 convention

Audit artifacts

• docs/case-studies/meta-analysis/independent-audit-2026-04-21-gemini.md — verbatim Gemini audit
• trust/audits/2026-04-21-gemini/remediation-plan-2026-04-23.md — remediation tracker
• docs/master-plan/codex-ssd-audit-2026-04-19.md — Codex SSD audit (pre-v7.5 context)

Implementation plans + specs

• docs/superpowers/plans/2026-04-25-v7-6-mechanical-enforcement-phases-2-4.md — v7.6 plan agent output
• docs/superpowers/specs/2026-04-27-framework-v7-7-validity-closure-design.md — v7.7 spec
• docs/superpowers/plans/2026-04-27-framework-v7-7-validity-closure.md — v7.7 plan
• docs/superpowers/specs/2026-05-02-framework-v7-8-and-v7-9-bridge-design.md — v7.8 + v7.9 bridge design

Scripts (alphabetical)

• scripts/append-feature-log.py — contemporaneous log writer
• scripts/check-branch-drift.py — W9 branch-drift PostToolUse:Bash alert (v7.8.5)
• scripts/check-case-study-preflight.py — write-time case study checks
• scripts/check-ssh-agent.sh — W1 ssh-agent SessionStart preflight (v7.8.6)
• scripts/check-state-schema.py — write-time + cycle state.json checks (incl. branch-isolation + state_owner gates)
• scripts/create-isolated-worktree.py — branch-isolation auto-isolation (v7.8.1)
• scripts/cross-layer-freshness.py — W20 cross-layer freshness scan (v7.8.6)
• scripts/daily-integrity-checkpoint.py — daily launchd checkpoint
• scripts/documentation-debt-report.py — Tier 3.2 ledger
• scripts/ensure-pr-cache-fresh.py — PR_CACHE_STALE auto-refresh (v7.8.4)
• scripts/integrity-check.py — cycle-time integrity check
• scripts/integrity-diff.py — diff vs baseline anchor (v7.8.6)
• scripts/measurement-adoption-report.py — Tier 1.1 ledger + history
• scripts/membrane-status.py — Mechanism F membrane readout
• scripts/merge-driver-dedup.py — Mechanism E append-only-ledger merge driver
• scripts/observe-cache-hit.py — Mechanism C PostToolUse:Read capture (v7.8)
• scripts/preflight.py — unified pre-work aggregator (v7.8.6)
• scripts/runtime-smoke-gate.py — Tier 2.1 smoke runner
• scripts/snapshot-phase-completion.sh — per-phase off-SSD backup (v7.8.3)
• scripts/test-v7-5-pipeline.sh — mechanical-enforcement regression test
• scripts/weekly-trend-scan.py — weekly gate-coverage + adoption trend scan (v7.8.6)

Workflows (full inventory in §11.3)

• .github/workflows/ci.yml — Xcode build + test + tokens-check + ui-audit
• .github/workflows/ci-docs-skip.yml — skips iOS build for docs-only PRs
• .github/workflows/integrity-cycle.yml — 72h cycle (v7.1 → v7.5), cron 0 4 */3 * *
• .github/workflows/pr-integrity-check.yml — per-PR (v7.6 Phase 2a)
• .github/workflows/framework-status-weekly.yml — weekly cron 0 5 * * 1 (v7.6 + v7.8.6 trend scans)
• .github/workflows/dependency-audit-weekly.yml — weekly npm audit, cron 0 6 * * 1 (v7.8.6)
• .github/workflows/audit-prompts-weekly.yml — external-audit prompt substrate, cron 0 6 * * 1
• .github/workflows/audit-bundle-on-tag.yml — deterministic audit bundle on tag push
• .github/workflows/ucc-audit-log-sync.yml — UCC audit-log sync, cron 17 5 * * *
• .github/workflows/weekly-backup.yml — weekly off-repo backup, cron 0 2 * * 0
• .github/workflows/figma-code-connect-publish.yml — Code Connect publish
• Local launchd: com.fittracker.daily-integrity-checkpoint.plist — daily checkpoint (make install-daily-cron)

External reference

• GitHub Actions injection guide — security pattern referenced in workflow files

This guide is updated whenever the framework's structural shape changes. If you find an inaccuracy or a stale reference, file a PR — the pre-commit hook will tell you immediately if the doc is out of sync with the code.