feat: protocols as first-class methodology layer (v2.4) by rmsharp · Pull Request #11 · KJ5HST/methodology

rmsharp · 2026-05-12T18:46:07Z

Summary

Promotes protocols to a first-class layer in the methodology hierarchy, alongside the existing workstreams layer. A protocol is a multi-session campaign template that extends a workstream when per-session work cannot complete the deliverable cleanly (paper-wide verification, repository-wide hardening, multi-module familiarization).

No new principles, phases, gates, or workstreams. This is structural-vocabulary only — it names the campaign layer that already exists in practice and gives it a documented home.

What's added

Layer-defining changes:

ITERATIVE_METHODOLOGY.md — new section §Protocols and Multi-Session Campaigns (~34 lines)
starter-kit/SESSION_RUNNER.md — new Phase 1 multi-session campaign check (~2 lines)
CLAUDE.md, README.md, HOW_TO_USE.md — hierarchy table updated from 3 layers → 4 layers; v2.4 entries in Versioning / What's New

Template + concrete protocols:

workstreams/TEMPLATE_PROTOCOL.md (~279 lines) — blank skeleton parallel to TEMPLATE_WORKSTREAM.md
workstreams/RESEARCH_EXHAUSTIVE_VERIFICATION_PROTOCOL.md (~561 lines) — first realized protocol; extends the Research Documentation workstream for exhaustive primary-source verification. Supports creation mode (writing) and audit mode (reviewing).
workstreams/INHERITED_CODEBASE_FAMILIARIZATION_PROTOCOL.md (~594 lines) — second realized protocol; extends the Audit workstream for taking over an unfamiliar codebase, feeds the Development workstream via a prioritized backlog. Supports interview mode (departing owner available) and archaeology mode (owner gone).

Workstream cross-reference:

workstreams/RESEARCH_DOCUMENTATION_WORKSTREAM.md (~4 lines) — points to RESEARCH_EXHAUSTIVE_VERIFICATION_PROTOCOL.md for campaigns that exceed Phase 6's per-session audit budget.

Rebased onto `main`; stacked on #10

#9 has merged. This branch has been rebased onto current upstream/main, then onto PR #10's rebased HEAD. The 3 v2.4 commits now apply cleanly:

b1ba27e docs: propose protocols as first-class methodology layer (v2.4 design)
b8599b7 feat: implement v2.4 — protocols as first-class methodology layer
b477a29 feat: add Inherited-Codebase Familiarization Protocol

The PR currently shows 7 commits relative to main: 4 from PR #10 + 3 from this PR. Once #10 merges, GitHub will collapse the diff to just the 3 v2.4 commits.

No LICENSE, license-text, or other upstream content is touched.

Design notes

Naming convention. Filename pattern *_PROTOCOL.md parallels *_WORKSTREAM.md. Glob discoverability matches the existing pattern.
No workstream changes. Protocols extend workstreams, not replace them. A protocol session is still one session in one workstream — protocols just sequence multiple such sessions toward a campaign goal.
Realized first. The framework is shipped with two concrete protocols already in use (RESEARCH_EXHAUSTIVE_VERIFICATION and INHERITED_CODEBASE_FAMILIARIZATION) so the abstract layer is grounded in practice, not aspiration.
Internal planning artifacts excluded. docs/planning/protocols-as-first-class.md, protocols-integration-design.md, and protocols-integration-session-plan.md exist in my fork but are deliberately omitted from this PR — they're working artifacts, not framework deliverables.

Test plan

CLAUDE.md Document Hierarchy table has 4 rows (Cockpit / Flight manual / Mission procedures / Campaign templates)
CLAUDE.md Protocols section lists all 3 new protocol files
CLAUDE.md v2.4 entry present under Versioning
README.md What's New in v2.4 section present
ITERATIVE_METHODOLOGY.md §Protocols and Multi-Session Campaigns section present
starter-kit/SESSION_RUNNER.md Phase 1 references the multi-session campaign check
All 3 new files render cleanly as Markdown

🤖 Generated with Claude Code

Three small clarifications to workstreams/RESEARCH_DOCUMENTATION_WORKSTREAM.md suggested by KJ5HST in the PR #9 review. 1. Anti-pattern <-> canonical FM cross-references: one-line note above the anti-pattern list noting that anti-patterns #9 (Edit from memory), #10 (Greenfield framing), and #11 (Overwriting user edits) are domain specializations of canonical Failure Modes #20, #21, and #22 respectively. Prevents future readers from treating them as redundant. 2. Calibrate-to-domain hedge on the ~22%/~12% baseline numbers: clarify that the figures are from one project's corpus and should be treated as a starting point, with each project's own running baseline as the reference thereafter. 3. Phases-covered note near the top: explicit statement that the workstream adapts Phases 2, 3, 4, and 6, with Phase 1 (Pre-Flight) following the generic SESSION_RUNNER orientation procedure and Phase 5 (Implement) subsumed into Phase 3 because writing IS implementing for documents. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Anti-patterns 14-19 surfaced during an editorial audit of a 16-paper, ~5,930-line research-documentation corpus that applied the workstream's Audit Mode. Each is grounded in concrete findings from that audit; the audit report is preserved in the originating project (rmsharp/model_governance:docs/audits/20260425_qmd_corpus_audit.qmd). Each new anti-pattern is in the same "name — symptom — mitigation" form as the existing 13. None overlap the existing list: 14. Companion-paper drift — extracts diverge from sources over time. Distinct from KJ5HST#9 (edit from memory, within-session); this drift is across-time. 15. Stale verification artifact — verification reports and pending-changes documents lose coverage as their target documents accumulate new content. 16. Date-anchored prose without timestamp — phrases like "as of early 2025" silently age. Distinct from #1 (citation drift); this is narrative tense. 17. Multiple-bibliography drift — per-cluster .bib files diverge from the canonical project bibliography. Names the failure of the existing Phase 3 "use a single bibliography" rule. 18. Verification-flag / body-text divergence — a claim is correctly flagged in Verification Flags but the body text presents it without caveat. Distinct from #6 (descriptive-page substitution); the flag exists, it just doesn't propagate to the body. 19. Scope-overlap silence between sibling papers — two papers share evidence with no cross-reference. Distinct from KJ5HST#12 (redundant restatement, within-paper); this is across-paper. The Audit Mode "Severity calibration" table (Critical/Moderate/Minor) is updated to reference the new anti-patterns by number. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The Audit Mode "Map this workstream's machinery into audit deliverables" table referenced "The 13 anti-patterns" — a stale count from before this PR added patterns 14-19. Update to "The 19 anti-patterns" to match the new total. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The 6 anti-patterns added in the previous commits (14-19) extend the research-documentation workstream's anti-pattern catalog. Update the v2.3 What's New summary in README.md and CLAUDE.md to reflect the new total. Also fixes the README Audit Mode bullet that referenced "the 13 anti-patterns as finding categories" — same drift, same fix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The audit-mode mapping table at line 49 was updated to "19" when anti-patterns 14-19 landed, but the audit-report template body at line 57 still said "all 13". Same drift, same fix. Caught by an audit agent using this workstream on a downstream project. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Introduces "protocol" as a methodology-level vocabulary item: a multi-session campaign template that extends a workstream when a deliverable cannot be produced in one session even after correct decomposition. Adds: - workstreams/RESEARCH_EXHAUSTIVE_VERIFICATION_PROTOCOL.md — first realized protocol; campaign template for exhaustive primary-source verification with creation and audit modes - docs/planning/protocols-as-first-class.md — argument that the protocol layer deserves first-class status in the methodology - docs/planning/protocols-integration-session-plan.md — brief for the follow-on planning session - docs/planning/protocols-integration-design.md — Phase 3 design with exact text and insertion points for the v2.4 implementation session Updates: - CLAUDE.md — adds Protocols subsection to the document hierarchy - workstreams/RESEARCH_DOCUMENTATION_WORKSTREAM.md — adds escalation links to the new protocol from Audit Mode and Phase 6 sections Methodology files (ITERATIVE_METHODOLOGY.md, SESSION_RUNNER.md, TEMPLATE_PROTOCOL.md, README.md, HOW_TO_USE.md) are NOT modified in this commit. Their edits are specified in the design plan and execute in a follow-on implementation session after lead approval. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Applies the edits specified in docs/planning/protocols-integration-design.md §3, producing a reviewable working version of the v2.4 change. - ITERATIVE_METHODOLOGY.md — new §Protocols and Multi-Session Campaigns section (after Session Types). Defines protocols, when to invoke, where they live, and disambiguates the new technical sense from the longstanding "the protocol = the methodology" usage. - starter-kit/SESSION_RUNNER.md — new ⚠ Multi-session campaign check paragraph in Phase 1 (parallel in style to the Plan Mode exit trap). - workstreams/TEMPLATE_PROTOCOL.md — new blank skeleton for authoring protocols, parallel to TEMPLATE_WORKSTREAM.md. - CLAUDE.md — split Mission procedures row into _WORKSTREAM and _PROTOCOL rows, added TEMPLATE_PROTOCOL.md row to Protocols subsection, bumped current version to v2.4, added v2.4 versioning entry. - README.md — split top hierarchy table to surface Campaign templates, added repo-tree entries for the protocol and template, added a protocols paragraph after the Workstreams table, inserted "What's New in v2.4" section. - HOW_TO_USE.md — new "Protocols" subsection in Core Concepts, with three example campaigns and a pointer to the formal definition. No new principles, phases, gates, workstreams, or failure modes. The realized protocol (workstreams/RESEARCH_EXHAUSTIVE_VERIFICATION_PROTOCOL.md) is unchanged — its terminology was authored consistently with the new methodology vocabulary and required zero migration edits. Verification: - grep "workstreams/\*\.md" CLAUDE.md README.md → no results (both hierarchy tables updated) - All EXHAUSTIVE_VERIFICATION cross-references still resolve - TEMPLATE_PROTOCOL.md referenced in CLAUDE.md, README.md, HOW_TO_USE.md, and ITERATIVE_METHODOLOGY.md (all four user-facing docs) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Second realized protocol under the v2.4 layer. Multi-session campaign template for taking over an unfamiliar codebase from a departing owner, an acquired team, or a neglected subsystem. Decomposes into planning (operational-responsibility definition, module map, scoping unit, deliverable contract, exit criteria), N execution sessions (one per module/coupling-cluster: API surface, data flow, owned state, gotcha catalog, falsifiable exit predicates), and consolidation (cross-module architecture, risk map, residual unknowns, prioritized backlog feeding follow-on Development sessions). Two modes: interview (departing owner available — scheduled question rounds, owner-bias check) and archaeology (owner gone — git log/blame, PR history, runtime tracing, documentation skepticism). Same campaign shape, schema, and exit criteria; different evidence sources and dominant failure modes. Parent workstream: AUDIT (audit-style read of unfamiliar code → evidence-backed finding report). Cross-references DEVELOPMENT for the consolidation backlog's destination. Also updates CLAUDE.md's protocols index to list the new file. Content addition under v2.4 — does not bump version. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The v2.4 What's New entries in CLAUDE.md and README.md were authored in commit b8599b7 (when only RESEARCH_EXHAUSTIVE_VERIFICATION existed) and not updated when commit b477a29 added the second realized protocol (INHERITED_CODEBASE_FAMILIARIZATION). Same omission in the README's project dir-tree. The Protocols *table* in CLAUDE.md already listed all three correctly — these edits bring the prose entries in line. - CLAUDE.md v2.4 entry: "Realized example: <one>" → "Realized examples: <RESEARCH_EXHAUSTIVE> (extends Research Documentation) and <INHERITED_CODEBASE> (extends Audit)." - README.md dir tree: add INHERITED_CODEBASE_FAMILIARIZATION_PROTOCOL row. - README.md v2.4 What's New: single "Realized example" bullet expanded into "Realized examples" with two sub-bullets, parallel structure (extends + behavior + modes). No principle, phase, gate, file-rename, or framework-content changes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Brings in upstream's 4 new commits: - a85febe feat: add Research Documentation workstream (v2.3) - 0a2e669 docs: address PR KJ5HST#9 review feedback - 31fdb79 docs: add LICENSE — custom attribution / non-commercial-resale terms - a10baae Merge pull request KJ5HST#9 Conflict resolution: 3 files (CLAUDE.md, README.md, workstreams/RESEARCH_DOCUMENTATION_WORKSTREAM.md) replaced with the versions on origin/feature/protocols-as-first-class-upstream (PR KJ5HST#11 branch HEAD 532b668). That branch is rebased on current upstream/main and contains PR KJ5HST#10's anti-patterns 14-19 + PR KJ5HST#11's v2.4 protocols layer + the v2.4 consistency follow-up — i.e., the post-merge target state. Then re-added the local `## Session Startup` section to CLAUDE.md (the `go` mapping, from commit a2738a7). Net effect on local main: - LICENSE file added; license-text phrasing in CLAUDE.md/README.md matches upstream's authoritative version. - v2.3 'What's New' adopts upstream's fuller wording (mentions FMs unchanged, references rad-con audit #6/KJ5HST#7). - v2.4 entries adopt the 'Realized examples' plural form referencing both protocols; README dir-tree lists all three protocol files. - All local-only content preserved: planning docs, `go` startup section, dashboard test infra. PRs KJ5HST#10 and KJ5HST#11 remain open and unaffected (they merge to KJ5HST/main). After they merge upstream, the next sync will fast-forward cleanly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

KJ5HST

Request Changes — Rename "Protocol" → "Campaign"

Thanks for the PR. The gap is real and the work is well-designed; the two realized examples are proven (in use at USAA) so the realized-first framing is appropriate as-is. One blocking change before merge.

Vocabulary collision with existing framework discipline

SESSION_RUNNER.md and the broader framework already use "protocol" in a load-bearing generic sense:

Protocol Erosion is FM #17 — one of the core failure modes the methodology defends against.
The Degradation Detection table refers to "the protocol" multiple times as the methodology itself.
"protocol violation" is established idiom (minimum handoff requirements, Phase 3D).

Adding "a protocol" / "the [Name] Protocol" as a different first-class noun in the same documents costs more in reader confusion than the new §Terminology paragraph recovers. The disambiguation rides on article choice and named referents — fragile in skimming, and especially risky in a framework whose own FM #17 is named Protocol Erosion.

Proposed rename: Protocol → Campaign

*_PROTOCOL.md → *_CAMPAIGN.md.

The PR body and the new files themselves already use "campaign" 50+ times to describe what a protocol is — "multi-session campaign template", "the campaign as a whole", "campaign-level halt conditions". The new section in ITERATIVE_METHODOLOGY.md is titled "Protocols and Multi-Session Campaigns" — the second half of that title is what the artifact already wants to be called. With "campaign" as the single name, the §Terminology disambiguation paragraph can be deleted entirely.

Rename scope (mechanical)

Files:

workstreams/TEMPLATE_PROTOCOL.md → workstreams/TEMPLATE_CAMPAIGN.md
workstreams/RESEARCH_EXHAUSTIVE_VERIFICATION_PROTOCOL.md → workstreams/RESEARCH_EXHAUSTIVE_VERIFICATION_CAMPAIGN.md
workstreams/INHERITED_CODEBASE_FAMILIARIZATION_PROTOCOL.md → workstreams/INHERITED_CODEBASE_FAMILIARIZATION_CAMPAIGN.md

Text:

New technical noun "protocol" → "campaign" everywhere it refers to the new layer.
File-name pattern *_PROTOCOL.md → *_CAMPAIGN.md in all references (CLAUDE.md, README.md, HOW_TO_USE.md, starter-kit/SESSION_RUNNER.md, ITERATIVE_METHODOLOGY.md, cross-refs in RESEARCH_DOCUMENTATION_WORKSTREAM.md).
Section title and v2.4 changelog entries renamed accordingly ("§Multi-Session Campaigns" or similar).
Preserve the existing protocol-discipline language — FM #17 "Protocol Erosion", "session protocol", "protocol violation" stay as-is.
The §Terminology disambiguation section in ITERATIVE_METHODOLOGY.md can be removed; the collision is gone.

No other changes requested.

rmsharp · 2026-05-24T19:57:48Z

Concur with the rename. Walking the artifacts on the branch made the case stronger than the comment lays out — sharing the read so we're on the same page.

The asymmetry inside SESSION_RUNNER.md is severe. The runner uses the old sense of "protocol" 12+ times on the v2.4 branch — FM #17's name, the Degradation Detection table's "the protocol is eroding" and "reset to full protocol", Phase 1B's "structural control / protocol step", Phase 3D's "protocol violation", the v2.2 learning row's "follow the protocol" — and the new sense exactly once (line 59, the multi-session campaign check). A reader skimming the cockpit document hits "protocol" with an overwhelming statistical prior on the old meaning. Disambiguation-by-article doesn't survive that ratio.

The §Terminology paragraph at ITERATIVE_METHODOLOGY.md:334 is the giveaway. When operational documentation needs a paragraph teaching readers that indefinite article = new noun, definite article = methodology itself, the noun choice was wrong. Disambiguation-by-article is grammar-reference territory; it doesn't belong in a runner-adjacent doc. With "campaign" the paragraph deletes cleanly.

The artifact is already half-converted. CLAUDE.md:22's hierarchy row is already labeled "Campaign templates" in the column header. Every place the new files explain what a "protocol" does, they switch to "campaign" — "multi-session campaign template", "campaign as a whole", "campaign-level halt conditions". The descriptive load is on "campaign" already; "protocol" is glued on as a label. The rename completes a conversion the PR started internally.

One counter I considered and discarded. There's a useful distinction between template (reusable artifact) and instance (a particular run); under "protocol" we loosely tried to carry that ("a protocol" = template, "a campaign" = run). Under "campaign" that distinction is carried by qualifier — *_CAMPAIGN.md is the template, "the campaign" is the run — mirroring the existing *_WORKSTREAM.md / "the workstream" pattern. Same idiom, no precision lost.

Two small amendments to the rename scope, both subtractions:

Section title: drop "Protocols and" from §Protocols and Multi-Session Campaigns → just §Multi-Session Campaigns. The "Protocols and" half existed to introduce the new noun; with the noun gone, the title can shrink.
docs/planning/ working artifacts (protocols-as-first-class.md, protocols-integration-design.md, protocols-integration-session-plan.md): excluded from this PR per its body, but they're real files in my fork. I'll handle their rename in a follow-up commit on my fork so they don't drift into stale-reference territory. Doesn't block upstream merge.

Execution plan. Rebase the branch onto current upstream/main, then push the rename as one commit on top of the existing v2.4 commits. git mv for the three *_PROTOCOL.md → *_CAMPAIGN.md files (preserves blame). Text replacement scoped to the new noun only — FM #17 "Protocol Erosion", "protocol violation", "session protocol", "re-internalize the protocol", and the erosion-table language stay untouched. Small, reviewable diff.

One sequencing question. PR #13 (render-dependency completeness, closes #12) is also open and currently rebase-conflicting against main. Either order works mechanically, but #11 first means #13 rebases over a stable surface — the campaign-layer changes don't touch the SAFEGUARDS / research-doc-workstream surfaces that #13 modifies, so it's a clean stack. Preference?

Per KJ5HST's CHANGES_REQUESTED review on PR KJ5HST#11: the "Protocol" noun introduced in v2.4 for multi-session campaign templates collides with the framework's existing load-bearing "protocol" usage (FM KJ5HST#17 Protocol Erosion, "protocol violation" idiom, "session protocol" referring to the methodology itself, SESSION PROTOCOL blocks). Asymmetry that motivates the rename: SESSION_RUNNER.md uses the existing-sense "protocol" 12+ times (FM KJ5HST#17, Degradation Detection table, "the protocol is eroding", "reset to full protocol", "re-internalize the protocol") and the new-sense exactly once (line 59 multi-session campaign check). Reader-confusion cost exceeds the §Terminology disambiguation paragraph's recovery. Rename scope (mechanical): - workstreams/TEMPLATE_PROTOCOL.md → TEMPLATE_CAMPAIGN.md - workstreams/RESEARCH_EXHAUSTIVE_VERIFICATION_PROTOCOL.md → RESEARCH_EXHAUSTIVE_VERIFICATION_CAMPAIGN.md - workstreams/INHERITED_CODEBASE_FAMILIARIZATION_PROTOCOL.md → INHERITED_CODEBASE_FAMILIARIZATION_CAMPAIGN.md - ITERATIVE_METHODOLOGY.md — rewrite §Multi-Session Campaigns (was §Protocols and Multi-Session Campaigns); delete §Terminology disambiguation paragraph (the collision is gone with the rename). - CLAUDE.md — hierarchy row, Campaigns section header, file rows, v2.4 entry. - README.md — hierarchy row, narrative, dir tree, Campaigns paragraph, What's New v2.4 entries. - HOW_TO_USE.md — Campaigns section (renamed from Protocols). - starter-kit/SESSION_RUNNER.md — line 59 multi-session campaign check. - workstreams/RESEARCH_DOCUMENTATION_WORKSTREAM.md — 2 cross-refs. Section title shortened per amendment in PR-11 comment thread: §Protocols and Multi-Session Campaigns → §Multi-Session Campaigns (the "Protocols and" half existed to introduce the now-removed noun). Preserved (existing-sense "protocol", ~39 occurrences across SESSION_RUNNER, ITERATIVE_METHODOLOGY, README, HOW_TO_USE, CLAUDE, BOOTSTRAP, CLAUDE_TEMPLATE, SAFEGUARDS): FM KJ5HST#17 Protocol Erosion, "protocol violation", "session protocol", "the protocol" (= methodology), v1.1 changelog entries, SESSION PROTOCOL blocks, "## Session Recovery Protocol" header. No principle, phase, gate, or workstream changes. No FM renumbering. v2.4 deliverable unchanged in substance — vocabulary-only refactor.

KJ5HST

Rename verified. git mv preserved blame on all three files; section title shortened to §Multi-Session Campaigns per your amendment; §Terminology disambiguation paragraph deleted; discipline-sense "protocol" preserved across SESSION_RUNNER, CLAUDE, BOOTSTRAP, README, ITERATIVE_METHODOLOGY (FM #17, "protocol violation", "session protocol", "the protocol is eroding", "Protocol discipline is perishable" learning row, "## Session Recovery Protocol" header). Cumulative diff still 9 files, no scope creep. Merging now — PR #13 unblocked to rebase.

…s to be computed Adds one row to the starter-kit/SESSION_RUNNER.md Learnings table (was 1-12; appended, never renumbered) plus its CHANGELOG.md ledger entry. A forward-looking claim cannot be checked by re-reading a file — it has to be computed. Learning #6 and FM KJ5HST#11 catch claims written from memory, and both prescribe the same repair: go read the file that confirms it. KJ5HST#7, KJ5HST#10 and KJ5HST#12 catch cross-references that go stale in the corpus. Neither reaches the other half of a handoff: a prediction describes a state that does not exist yet, so no file confirms it. The motivating case is this repository's own, and it refutes the tempting diagnosis that such claims merely "decay": git log -S 'expect one CHANGELOG union conflict' -- HANDOFFS.md -> bec4095 git show --stat bec4095 -> 7 files The receipt predicting one conflicting file was written into a commit that itself changed all seven of the files the later merge collided in. It did not go stale — it was never derived from state the author already held. Verified: bin/tests.sh 84/84 · bin/check-links OK (82 links / 21 files) · Learnings table contiguous 1-13, every row 4-column, rows 1-12 byte-unchanged · brand-neutrality grep empty. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The "## Learnings (added by sessions)" table leaves starter-kit/SESSION_RUNNER.md for a new distributed sibling, starter-kit/FRAMEWORK_LEARNINGS.md -> adopter root FRAMEWORK_LEARNINGS.md, TRACKED. The runner keeps a one-paragraph pointer; Phase 3C's two routing bullets name the sibling. The learnings are reference, not procedure: a session needs them when a learning applies, not to run a session. WHAT IT BUYS, MEASURED ON BOTH FILES AND METERED, NOT ARGUED. The Phase 0 mandatory read (SESSION_RUNNER.md + SAFEGUARDS.md) goes 80,526 -> 67,581 B (-12,945, -16.1%); SESSION_RUNNER.md alone 65,140 -> 52,195 B; SAFEGUARDS.md untouched (same blob f096419 as before). METERED against the 25,000-token agent Read cap by the doubled-file method: 28,234 tok = 112.9% of one read -> 23,902 tok = 95.6%. The mandatory read stops being a read that does not fit, with 1,098 tokens spare. On the deliberately conservative 56,750 B floor the pair is still over -- by 23,776 B before and 10,831 after, a 54.4% cut -- and the two measures disagree because that floor's 2.27 B/token is 26% conservative for this content (metered here: 2.852 and 2.827). Both figures are reported rather than the flattering one. NOTHING IS LOST; THE ROWS MOVE, AND THEN SOME. The 13 rows that lived inline arrive as rows #1-#13 of a 46-row table. Rows #1-#11 are byte-identical. #12 and #13 arrive COMPACTED (2,401 -> 1,451 B and 1,573 -> 1,447 B) under the 1,500 B per-row budget the new file publishes -- said shorter without saying less, every mechanism, figure and citation kept, each compacted row read back by an independent reader asked only what was lost. #14 IS DELIBERATELY ABSENT AND MUST STAY ABSENT. It is reserved by docs/operator-gated-review-plan's D3; the table numbers 1..47 with 14 reserved. Renumbering would break every Learning #N citation, which is what "append only, never renumber" exists to prevent. check-learnings parses the file's own prose for reserved numbers, so the gap is not reported as a missing row. TOOLING FOLLOWS THE TABLE, BECAUSE THE FILE PUBLISHES RULES THAT MUST BE TRUE. Its front matter says "1,500 B, checked by bin/check-learnings" and declares the #14 reservation, so shipping the file without the checker's budget arm and reserved-number handling would ship two false claims. check-learnings therefore locates the table by its HEADER ROW rather than a "## Learnings" heading -- portable across both layouts -- honours the reserved gap, and holds the budget against EVERY row, not only the row being written. bin/tests.sh Test 23 retargets to the new file and now asserts each mutation's SPECIFIC finding text instead of the exit code: that code is a union over every check, so the new budget arm would otherwise satisfy all four mutation assertions whether or not they caught their own defect. SCANNER. FRAMEWORK_LEARNINGS.md joins FRAMEWORK_AMBIGUOUS_DOCS -- the ambiguous root-name set grows 6 -> 7, a behaviour change, hence DASHBOARD_VERSION 2.10.6 -> 2.10.7 on both byte-identical twins -- and gains a CHECKLIST_EXEMPT entry rather than a METHODOLOGY_ITEMS row: METHODOLOGY_MAX is a derived denominator, so scoring it would move every already-compliant adopter's percentage for a change they did not make. DRIVEN RED FIRST: with the exemption removed, test_every_distributed_adopter_root_file_is_scored_or_exempt fails on exactly ['FRAMEWORK_LEARNINGS.md']. ONE PRE-EXISTING COUNT CORRECTED IN PASSING, DISCLOSED RATHER THAN FOLDED IN. The FRAMEWORK_ITEMS comment read "9 of the 22 distributed sources"; DISTRIBUTION has held 24 since df6a991 added the two context-budget rows. It is set to the derived 25, so two of the three units of that correction are pre-existing drift, not this change. VERIFICATION, each command run bare with $? read on the next line. bin/tests.sh, row-for-row against a PRISTINE upstream/main control in its own worktree: control 114 passed / 0 failed, exit 0; this branch 113 / 1, exit 1. Both populations 114, ZERO skips, and ZERO status flips across 111 shared assertion texts. All 6 differing rows pair exactly: "all 24 manifest files present" -> "all 25", "one row per manifest file (24 == 24)" -> "(25 == 25)", and the sole regression, "github source dry-run works" -> "github source dry-run failed". THAT ONE FAILURE IS THIS COMMIT'S OWN PRECONDITION AND SELF-RESOLVES ON MERGE. Test 9 dry-runs bin/sync --source=github against the pinned repo, and the error names the cause exactly: "gh api failed for starter-kit/FRAMEWORK_LEARNINGS.md: 404". The file is not on GitHub because this is the change that puts it there. DO NOT WEAKEN TEST 9. tools/test_methodology_dashboard.py: 211 passed, exit 0. Twins byte-identical (cmp). bin/check-learnings: exit 0 -- 46 rows, contiguous 1..46, all citations resolve, 46 row(s), 0 over 1,500 B. WHAT THIS DOES NOT PROVE: no test here can falsify a fidelity claim about a compacted row. The suite proves the rows are well-formed, budgeted and citation-resolving; that #12 and #13 still carry their mechanisms rests on adversarial reads, which are judgement. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AePFqFtVfJvUxVG1g2NJ5Q

rmsharp mentioned this pull request May 13, 2026

feat: add Research Documentation workstream (v2.3) #9

Merged

3 tasks

rmsharp and others added 7 commits May 23, 2026 01:38

rmsharp force-pushed the feature/protocols-as-first-class-upstream branch from 6bdb50b to b477a29 Compare May 23, 2026 06:46

rmsharp marked this pull request as ready for review May 23, 2026 06:46

KJ5HST requested changes May 23, 2026

View reviewed changes

KJ5HST mentioned this pull request May 25, 2026

feat: render-dependency completeness discipline (v2.5) — closes #12 #13

Merged

5 tasks

KJ5HST approved these changes May 25, 2026

View reviewed changes

KJ5HST merged commit 8d6098e into KJ5HST:main May 25, 2026

rmsharp deleted the feature/protocols-as-first-class-upstream branch May 25, 2026 18:57

rmsharp mentioned this pull request Jul 9, 2026

feat(session-runner): capability-tiered review — elective vertical-slice addition (BL-7) #57

Merged

5 tasks done

rmsharp mentioned this pull request Jul 27, 2026

Learning #13 — a forward-looking claim has to be computed, not re-read #63

Merged

Navigation Menu

Repository navigation

feat: protocols as first-class methodology layer (v2.4) - #11

feat: protocols as first-class methodology layer (v2.4)#11
KJ5HST merged 9 commits into
KJ5HST:mainfrom
rmsharp:feature/protocols-as-first-class-upstream

rmsharp commented May 12, 2026 •

edited

Loading

Uh oh!

KJ5HST left a comment

Uh oh!

rmsharp commented May 24, 2026

Uh oh!

KJ5HST left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

rmsharp commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's added

Rebased onto main; stacked on #10

Design notes

Test plan

Uh oh!

KJ5HST left a comment

Choose a reason for hiding this comment

Request Changes — Rename "Protocol" → "Campaign"

Vocabulary collision with existing framework discipline

Proposed rename: Protocol → Campaign

Rename scope (mechanical)

Uh oh!

rmsharp commented May 24, 2026

Uh oh!

KJ5HST left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rmsharp commented May 12, 2026 •

edited

Loading

Rebased onto `main`; stacked on #10