v3.0 — MIT relicense (#43)

The methodology is now MIT-licensed (#43). The bespoke source-available LICENSE is replaced with the verbatim standard MIT License. The major version bump marks a deliberate change to the legal terms — not the content: no principle, phase, gate, workstream, or failure-mode is touched, and the failure-mode count stays 26.

• What changed legally. MIT grants the right to use, copy, modify, merge, publish, distribute, sublicense, and sell — with attribution (the copyright and permission notice must be retained in copies). The previous license permitted commercial operational use but forbade selling or productizing the methodology itself; that no-resale restriction is now intentionally dropped. Anyone may sell the methodology or derivatives, attribution retained.
• Why MIT. It adds the standard AS IS warranty/liability disclaimer the bespoke license lacked (reducing the author's residual exposure), removes the interpretive ambiguity around "this methodology itself," and is instantly recognizable and GitHub-auto-detected. The trade-off — losing the no-sell guarantee — was weighed against a hardened-custom alternative (which would have closed the same two defects while keeping the restriction) and MIT was chosen by author decision.
• Lockstep doc updates. LICENSE → verbatim MIT (Copyright (c) 2025-2026 Terrell Deppe (KJ5HST)); README.md §License and the CLAUDE.md license line updated to match.
• Adopter impact: none mechanical. LICENSE is not a bin/sync-distributed file, so installed projects pull no change from this release. If you redistribute or build on the methodology, you are now under MIT terms.

v2.9 — hands-on tutorial track (#38) + reasoning-tier generalization (#39)

A combined minor release of two additive contributions that merged together (#38, #39, rmsharp). No principle, phase, gate, workstream, or failure-mode changes — failure-mode count stays 26.

Hands-on tutorial track (#38)

A new docs/tutorials/ learning layer parallel to the document hierarchy — a progressive, do-one-thing-per-lesson curriculum with a checkpoint at every step, run against your own repo or a bundled sample todo-CLI project.

• Core trio published: Setup (T1) → First Session with a full annotated worked transcript (T2) → Cautionary Use (T5)
• Plus a series index and a reusable tutorial template
• The sample project intentionally leaves one feature unbuilt so a tutorial session implements it end to end (pytest 7/7 green)
• Canonical-only learning aid — the tutorials are not distributed to adopter projects by bin/sync, so the corpus an installed project receives is unchanged

Reasoning-effort convention (#39)

The guidance to raise an agent's reasoning depth on high-stakes work — previously living only in the Research Documentation workstream — is promoted to a cross-cutting rule.

• New brand-neutral core section §Matching Reasoning Effort to Stakes in ITERATIVE_METHODOLOGY.md: set reasoning depth by the work's blast radius × irreversibility × compounding cost (the same risk lens Principles 3 and 9 already use). The inverse holds too — cheap, reversible, mechanical work gets a lighter default.
• Agent-independent: the brand-neutral core says when and why; the new RECOMMENDED_SKILLS.md §Reasoning Effort names concrete example settings as the how.
• The heavy workstreams (Architecture / Audit / Development / Research Documentation), the lighter Design, both campaigns, and SESSION_RUNNER planning sessions cite the rule; the Research-Documentation paragraph is recomposed in place to cite the new owner (cite-don't-restate).
• Anti-erosion clause (cross-references FM #17): a deeper reasoning mode sharpens a phase — it never licenses skipping a gate or widening a session.

Backward compatible

Adopters absorb the reasoning-effort edits to distributed files (ITERATIVE_METHODOLOGY.md, RECOMMENDED_SKILLS.md, SESSION_RUNNER.md, workstreams/*) by re-running bin/sync; the tutorials are not synced and need no adopter action.

v2.8 — Distribution tooling expanded to the full corpus (B1 / #32)

The first non-docs change in several releases (since v2.2's distribution tooling): bin/sync and bin/status now cover the full methodology corpus, not the legacy three files. Resolves the B1 campaign — issue #32 — across four contributor PRs (#33/#34/#35/#37, rmsharp). No principle, phase, gate, workstream, or failure-mode changes — this is tooling.

The gap it closes

bin/sync propagated only SESSION_RUNNER.md, SAFEGUARDS.md, and methodology_dashboard.py; bin/status inspected the same three. Every release since v2.5 also changed files outside that set (RECOMMENDED_SKILLS.md, ITERATIVE_METHODOLOGY.md, workstreams/*…), so adopters who synced "by the book" silently fell behind while status still reported current — false confidence.

Link reconciliation + bin/check-links (Phase 2, #33)

A distributed file's relative cross-references can't be correct in both the canonical repo layout and the adopter layout unless source and target are siblings in both ("the link-topology paradox"). Distributed files now author their cross-references for the adopter layout — extending the convention SESSION_RUNNER.md already followed — and a new bin/check-links validates every relative link against a simulated adopter tree (wired into bin/tests.sh). Tradeoff: those cross-boundary links resolve in an installed project but no longer when the canonical repo is browsed on GitHub.

Expanded bin/sync over a shared manifest (Phase 3, #34)

The flat three-file tuple becomes a (src, dest, disposition) manifest defined once in bin/_manifest.py — the single source of truth now read by sync, status, and check-links. bin/sync produces the full Option-B tree (operating files at the project root, framework under docs/methodology/, subdirectories created as needed) and adds a seed disposition: SESSION_NOTES.md, CHANGELOG.md, and ROADMAP.md are written only when absent and never overwritten afterward — even with --force — because once created they are the adopter's.

Per-file bin/status (Phase 4, #35)

status reports one row per distributed file (Project · File · Disposition · Status) over the shared manifest, so drift in any framework doc — not just the legacy three — is now visible. SEED files report present/absent only, and an absent seed is never miscounted as drift.

Checker hygiene (Phase 5, #37, closes #36)

bin/check-links --tree now validates a real project in place without writing to it — adopter-owned placeholder files (CONTEXT.md, CLAUDE.md, …) are treated as allowed-absent rather than fabricated. The --tree mode added in Phase 3 had created up to 5 empty files in the validated tree; a Test 14 regression assertion now guards against it (suite at 51).

Backward compatible

No methodology-content change; adopters pick up the full corpus by re-running bin/sync. Per-project customizations in CLAUDE.md's Adaptations section are unaffected, locally-edited tracked files stay drift-protected, and seed files are never touched.

v2.7 — Vertical-slice model: "1 and done" redefined under hard gates (issues #20/#21)

The first change to the unit of "1 and done" since the rule was written: one deliverable MAY now be a verified vertical slice — one capability end to end — under hard gates. Adopted from issues #20 (model) and #21 (guardrails).

Vertical-slice redefinition (#20)

The old "one horizontal layer per session" granularity was, in practice, a proxy for verifiability. When a session has high-parallelism verification available, the proxy can relax where the verification fully substitutes. New SESSION_RUNNER.md §Vertical Slice Sessions defines four mandatory gates:

• (a) the full layer set pre-declared in a plan-mode contract before any code — a prior-session approval satisfies this; the implementing session re-verifies it at Orient
• (b) a checkpoint commit at every layer boundary — the 5-file cap is unchanged and now explicitly per-commit (SAFEGUARDS.md)
• (c) the full build/test matrix plus exhaustive grep at each boundary, not once at the end
• (d) per-surface faithful verification — "all tests ran" is not automatically faithful

Evidence-gated, not self-certified: missing per-boundary artifacts revert the session to horizontal scope at the last clean checkpoint. Recoverability — not verifiability — is the ceiling on slice size, and seven boundary types stay non-collapsible. Principle 9 (Session Scope Bounding) extended to match.

Guardrails (#21)

• New failure mode #26 — "Mega-session masquerading as a vertical slice" (appended; FMs 1–25 unchanged) with its own degradation-detection row
• FM #17 (protocol erosion) anti-erosion clause — citing a "deeper dive" to skip an orientation, stub, or close-out step is erosion, not the model; the allowance ADDS a gate, it removes no step
• FM #18 (planning-to-implementation bleed) discriminator — implementing multiple layers of ONE pre-declared slice is not bundling

Also in this release

• The v2.6.2 forward-compatibility note is discharged: RECOMMENDED_SKILLS.md's "Phases spanned" reading guidance now speaks vertical-slice vocabulary, and the "A skill is not a phase" paragraph no longer presupposes the strict horizontal model.

Backward compatible

The allowance is opt-in and gated; the strict horizontal "1 and done" remains the default and the fallback. No phase, gate, or workstream changes. Adopters who never declare a slice operate the methodology exactly as before.

Content commits: 3bc0763 (#20 model) · c457bc3 (#21 guardrails) · 569e7e9 (skills-index restatement) · f130a7e (consistency) · 41b67ef (changelog)

v2.6.2 — Skill phase map + /triage prerequisite resolution (issue #22)

Docs-only dot release resolving issue #22 (Pocock skill enablement gap — investigation by @rmsharp). Strategy decided: C (Reactive) — enablement support happens per-request via the adopter's own CLAUDE.md adaptations (or /grill-with-docs lazy-creation), never via methodology-shipped templates, preserving "methodology recommends; methodology does not reimplement."

Bounding axis: per-skill phase map

New "Phases spanned (compression risk)" column on the external-skills table in starter-kit/RECOMMENDED_SKILLS.md — records, per skill and verbatim-verified at the pinned SHAs, which phases one invocation can cross:

• /grill-with-docs and /improve-codebase-architecture are flagged high (Phase 2 → 3 → 5 in a single invocation, modifying CONTEXT.md/ADRs)
• /diagnose is medium by design — a debugging session is its span
• the rest are low/zero

A reading-guidance paragraph tells adopters to plan the stop point before invoking a high-compression skill, cross-referencing the "A skill is not a phase" principle (v2.6.1). The column carries an explicit forward-compatibility note: if the vertical-slice model proposed in #20/#21 is adopted, it gets restated in that vocabulary in the same pass.

/triage prerequisite contradiction resolved

The skill's body recommends /setup-matt-pocock-skills, which this index declines. Resolution: footnote — the citation stands; a prerequisite note instructs adopters to establish the issue-tracker label mapping themselves per DEVELOPMENT_WORKSTREAM.md §Issue Lifecycle (mapping the canonical states needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix to their tracker's labels), or accept the canonical names as-is.

Compatibility

Backward compatible. No principle, phase, gate, workstream, or FM changes. Issues #20/#21 (vertical-slice model + guardrails) remain open and are not prejudged by this release. Adopters absorb the starter-kit change via bin/sync.

v2.6.1 — Skill-citation completion + adopter docs fixes

Docs-only dot release bundling four external contributions from @rmsharp (PRs #18, #23, #25, #27).

Skill-citation discipline completed (#18)

• The two aspirational citations in RECOMMENDED_SKILLS.md are now real: /init gets an actual helper paragraph in BOOTSTRAP.md Step 4 (with a skip path for projects that already have a CLAUDE.md); /fewer-permission-prompts is dropped from the index (no natural citation site).
• New principle: "A skill is not a phase" in ITERATIVE_METHODOLOGY.md §Recommended Skills — a skill that pulls a session across a hard gate is failure mode #2 (keep-going) wearing a tool costume. Applies whether the skill is indexed or independently installed; the methodology's gates bind every session regardless of which tools are loaded.
• New "Skills not recommended (and why)" subsection in RECOMMENDED_SKILLS.md — 10-row table surfacing the v2.6 audit's deliberate omissions plus two hedged post-audit entries (/handoff, /prototype), each with a one-line rationale.

Adopter docs fixes

• Learnings-routing contradiction fixed (#25, closes #24) — SESSION_RUNNER.md Phase 3C dual-audience recomposition: adopter projects record learnings in their CLAUDE.md Adaptations section; the canonical repo appends to the seed table. False "table starts empty" caption corrected; HOW_TO_USE.md retargeted.
• CLAUDE.md size budget (#27, closes #26) — BOOTSTRAP.md Step 5 gains a ~200-line size-budget rule with an extract-to-PROJECT_LEARNINGS.md overflow valve, plus a plain-link (not @-import) pointer warning.
• Housekeeping (#23) — tools/__pycache__/ gitignored.

Compatibility

Backward compatible. No principle, phase, gate, workstream, or session-type changes; no FM renumbering (count stays 25). Adopters absorb the starter-kit changes via bin/sync.

v2.6 — Skill-recommendation convention

Methodology recommends; methodology does not reimplement.

If a discipline can be expressed as a Claude Code skill — whether a built-in like /verify or /code-review, or a community skill from github.com/mattpocock/skills — methodology cites the skill at the relevant phase or workstream rather than re-documenting the discipline in its own voice. Methodology owns what to do and when (phases, gates, anti-patterns, failure modes, session-type definitions). Skills own how to do it.

What's new

• Skill-recommendation convention — new content layer alongside phases, principles, workstreams, and campaigns. If a discipline can be expressed as a Claude Code skill (built-in like /verify, /code-review; community like Pocock's /grill-me, /diagnose), methodology cites the skill at the relevant phase or workstream instead of re-documenting the discipline in its own voice.
• New starter-kit/RECOMMENDED_SKILLS.md — canonical index of recommended skills with two tables (Pocock community skills + Claude Code built-ins). External entries include per-skill known-good commit SHAs for adopters who want to pin a verified version; Pocock entries carry a "fork for production reliance" note.
• New ITERATIVE_METHODOLOGY.md §Recommended Skills — short principle paragraph + pointer to the index. Inline citations in workstreams and SESSION_RUNNER.md reference skills by slash-command name without re-describing them.
• Conceptual content distilled from a 16-skill audit (docs/audits/2026-05-02-mattpocock-skills-evaluation.md):
  • FM #25 — Horizontal slicing appended to SESSION_RUNNER.md (FMs 1–24 unchanged).
  • Phase 3F / Phase 6 step 8 gain an explicit "remove debug instrumentation before commit" gate, citing /diagnose for the tagged-debug-log convention.
  • New starter-kit/CONTEXT_TEMPLATE.md — project-level domain-glossary template; Phase 2 Research gains a new step 1 ("read CONTEXT.md if present"), citing /grill-with-docs for maintenance.
  • New Issue Lifecycle section in DEVELOPMENT_WORKSTREAM.md — 5-state machine (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix) with transition rules, citing /triage for the workflow.
  • New Debugging Sessions session type in ITERATIVE_METHODOLOGY.md — naming + recognition only; cites /diagnose for the workflow.
  • New Refactor Heuristics section in ARCHITECTURE_WORKSTREAM.md — deepening + deletion-test heuristics from Ousterhout's A Philosophy of Software Design, citing /improve-codebase-architecture for the worked-session shape.
  • New optional Phase 2.5 (Pre-Create Grill) in ITERATIVE_METHODOLOGY.md + matching SESSION_RUNNER.md task-mapping row; cites /grill-me for the grill workflow.
  • starter-kit/BOOTSTRAP.md Step 10 gains a tool-agnostic pre-commit hooks paragraph (cites /setup-pre-commit as one option) plus a mechanical-SAFEGUARDS-enforcement pointer to /git-guardrails-claude-code.
• Refactor of existing content under the principle:
  • SESSION_RUNNER.md §Phase 3E Runtime Smoke Test body shortened to a rule + citation of /verify and /run; intent preserved (the runtime-verify gate stays).
  • AUDIT_WORKSTREAM.md Light citation pass — new "Recommended Skills" callout cites /code-review, /review, /security-review. The 7-Dimension Audit Framework and per-phase audit framing stay as methodology-owned content.
• Future-audit candidates flagged in release (out of scope this release):
  • AUDIT_WORKSTREAM.md Medium/Heavy pass — per-phase citation audit beyond Light.
  • RESEARCH_DOCUMENTATION_WORKSTREAM.md — render-verification could cite /verify.
  • SESSION_RUNNER.md FM mechanical-enforcement column — depends on hook-conversion design.
  • DEVELOPMENT_WORKSTREAM.md citation audit beyond Issue Lifecycle.

Backward compatibility

No principle, phase, or quality-gate change. FM #25 appended (FMs 1–24 unchanged). Phase 2 step renumbered 1→2..7→8; the Phase 2 cross-references in HOW_TO_USE.md all cite by name, never by step number, so the renumber is safe. Adopters who never use the recommended skills continue to operate the methodology as written; the citations are recommendations, not hard dependencies.

v2.5 — Render-dependency completeness discipline

Build success is not asset-use success.

A render can succeed while silently using different assets than configured: a font family resolves to its Regular face but missing Italic / Bold faces fall back to a default; a CSL file resolves but is the wrong style version; a LaTeX template resolves but a missing class option is silently ignored. The output looks valid and the build exits cleanly. The defect is invisible unless something checks for it.

Resolves upstream issue #12.

What's new

• Render-dependency completeness discipline — closes the gap where rendering succeeds while the output silently uses fallback assets instead of the ones configured. Universal principle lands in SAFEGUARDS.md (new "Verify Render-Dependency Completeness" sub-section under "Verify the Build Equivalent"); concrete toolchain commands land in RESEARCH_DOCUMENTATION_WORKSTREAM.md.
• Two-tier check, by trigger:
  • Post-render (e.g., pdffonts confirming all configured font faces actually embedded) — hard rule, part of the build-equivalent step, blocks commit on failure.
  • Pre-render / setup (e.g., fc-list "<family>" returning the expected face count; kpsewhich resolving per-face files) — soft prompt at Phase 0 when render-dep configuration changes.
• Toolchain matrix gains a "Render-Dep Check" column — per-toolchain canonical commands for Quarto, LaTeX, Sphinx, Pandoc, AsciiDoc, and (n/a) vanilla Markdown, listing static and post-render commands side-by-side.
• New research-doc anti-pattern #20: Silent render-dependency fallback — derived from the joy/ project's SBL BibLit case (Regular-only font, italic markup rendered as upright Latin glyphs for 47 sessions before being noticed visually). Mitigation cross-references the new toolchain column and SAFEGUARDS sub-section.
• RESEARCH_EXHAUSTIVE_VERIFICATION_CAMPAIGN.md updated — Render Verification section in the creation-mode REPORT.md template gains a render-dep completeness line so the campaign inherits the discipline.

Backward compatibility

No principle, phase, gate, or workstream changes; no FM renumbering. Existing adopters absorb the new SAFEGUARDS sub-section via bin/sync. Domain-specific commands live in the research-doc workstream and only affect projects that use it.

v2.2 — Sync tooling + customization seam

What's New in v2.2

• bin/sync tool — dual-mode (--mode=commit / --mode=ignore) and dual-source (--source=local / --source=github) sync for starter-kit files. Committed mode is the existing pattern; ignored mode is new, for multi-project operators who want methodology updates to propagate via one command from a sibling methodology/ checkout.
• bin/status tool — drift reporter across one or many projects. Shows current, N versions behind, locally modified, or missing per synced file.
• Drift safety — bin/sync refuses to overwrite files with local modifications (not matching canonical or any historical version). Pass --force to override, or move customizations to CLAUDE.md's Adaptations section first.
• starter-kit/CLAUDE_TEMPLATE.md — new template for project CLAUDE.md files, including the Project-Specific Methodology Adaptations section. This is the canonical seam for per-project customizations (task mappings, Phase 0 steps, project Learnings, project failure modes) — keeping synced files byte-identical to canonical.
• BOOTSTRAP.md rewrite — documents committed vs ignored modes, the customization seam pattern, and the updating workflow (bin/status → bin/sync).
• Backward compatible — existing adopters on v2.1 who copy files manually continue to work unchanged. The scripted workflow is additive.

Upgrade

# External adopters (committed mode, default):
cd path/to/methodology && git pull
methodology/bin/sync your-project/

# Or continue with the manual copy flow from v2.1 — fully supported.

See docs/planning/methodology-as-environment-plan.md for the full design rationale.

v1.6: Runtime Verification

What's New

Runtime verification finding — Two consecutive sessions shipped code that compiled cleanly but broke at runtime due to plugin version collision and registration order. Both noted "no runtime verification" in self-assessment without treating it as a defect.

Changes

• New finding in validation table: "Build success is not runtime verification" (Sessions 151-153)
• Phase 6, step 2 expanded — runtime smoke test guidance for changes involving service registration, plugin loading, dependency injection, config resolution, or handler dispatch
• New Phase 5 anti-pattern — "Treating build success as verification": a successful build proves compilation and dependency resolution, not that services register in the right order or that components don't shadow each other at load time
• CLAUDE.md added (v1.5) — guidance for AI agents editing the methodology repo

Adopter Action

If you use SESSION_RUNNER.md, consider adding a runtime smoke test step to your close-out phase for deliverables that change runtime behavior. The starter kit will be updated in a future release.