2.1.1 — Marker Placement: hand-written module READMEs validate as documented

Prospec 2.1.1

Prospec 2.1.1 is a correctness release that removes a contradiction between two shipped authorities: the canonical module-README convention drew the format marker below a blank line, while the validator demanded it on the summary's very next line. Every hand-written module README that followed the documentation failed validation. The validator is now the convergence point — the marker must be the first non-blank line after the summary — and the placement rule is stated identically in the convention, the knowledge-generation skill, and both root READMEs.

25 files changed · +288 / −54 · 1 merged PR (#264) + 1 direct maintenance commit

---

🐛 Bug fixes

• Hand-written module READMEs failed validation for following the documentation. A downstream project's 25 hand-written READMEs all FAILed on the same finding — line 4: format marker must appear immediately after the summary. Both examples in _module-readme-conventions.md (the marker contract and the ## Skeleton) place the marker below a blank line, so only the generator's own output could pass: the defect hit exactly the hand-written path the convention exists for. 2.1.1 relaxes the validator to the first non-blank line after the summary, a strict superset of the old rule — the marker is located by whole-line literal comparison, so adjacency bought no parsing or compatibility benefit. Every currently-valid README stays valid, the format marker date stays 2026-09-01, and no module README needs migrating (#264).
• An out-of-order marker told the author to delete their README body. The summary → marker and marker → prospec:auto-start gaps are now two halves of one rule: both allow only blank lines, both report per line, and both sit inside the auto.start < markers[0] order guard. Without that guard the scan window widened to the whole document — measured at 51 findings on a 74-line README, 50 of them instructing the author to blank out body lines. The same input now reports one finding: auto block must appear after the format marker.
• An absent marker was reported at the wrong line, without the rule. It anchored to line 1 (the title) and the message never said where the marker belongs. It now anchors to the line after the summary and carries the placement rule, falling back to line 1 only when the README has no valid summary. A duplicate marker keeps its existing exactly one semantics and line-1 anchor.
• The guards could not see the prose that caused the incident. The contract test pinned literal adjacency on the generator template but only asserted indexOf ordering on the skeleton, so the extra blank line was untestable; a first-pass negative assertion matched only immediately after the summary, while the sentence that actually broke downstream said immediately before prospec:auto-start. The guards are now section-scoped to the paragraphs that state placement, blacklist adjacency adverbs as a class, and assert structure inside both shipped example fences — each mutation-verified, including against the exact sentence that caused this bug.
• The same defect shape in the blockquote rule. _module-readme-conventions.md also claimed Exactly one > blockquote line directly under the title while the generator leaves a blank line between title and summary. It points the other way — the documentation was stricter than the validator, so following it never failed — which is why nobody noticed. Fixed alongside.

🔁 Dogfood

prospec status reports no in-progress changes. One change, relax-readme-marker-adjacency, drove this release through prospec's own loop — story → plan → tasks → implement → review → verify → knowledge-update → archive — and earned verify grade S, with delta-spec-compliance, constitution, and the design not-applicable ruling all adjudicated in fresh context.

/prospec-review ran three rounds: 0 critical, 5 major, 3 minor, all fixed before verify and each given a mutation-verified regression stake. The fix_induced_ratio moved 0% → 33.3% → 50.0% across rounds — at the threshold, not over it — and the loop converged at the hard cap with zero unresolved criticals. The out-of-order-marker guard above is a review finding: the first implementation moved the reporting density but left the guard behind.

Three MODIFIED REQs graduated: REQ-LIB-073 (lib, the validator's placement rule), REQ-TESTS-110 (tests), and REQ-TEMPLATES-226 (templates). The two declared drops matched the declaration, with no refusals and no stale declarations. The fix was replayed against the downstream scenario during verify — a blank line reinserted into modules/cli/README.md, judged PASS by the source CLI, then reverted.

🧪 Quality & tests

• 4,736 tests passing (189 files), up from 4,726 in 2.1.0; 4 tests remain skipped. The additions are 9 unit tests over module-readme-format and 2 contract assertions over the shipped examples.
• 97.75% line coverage (96.7% statements, 90.73% branches, 98.07% functions); module-readme-format.ts is at 100%.
• prospec check --strict: 21/21 checks, 0 failures, 0 skipped. The single WARN is the pre-existing, deliberate knowledge-size budget pressure (50 warnings, the SC-002 signal) — unchanged in count from 2.1.0.
• TypeScript typecheck and ESLint are clean; factual counts are in sync, all 134 generated agent artifacts are current (templates → bundle → deployed), and knowledge:check confirms the source-touched module stamped. Bundle smoke test reports 2.1.1.

📊 Compared to 2.1.0

Comparison	2.1.0	2.1.1
Marker placement rule	Literal next line after the summary	First non-blank line after the summary
Convention vs. validator	Contradictory — the documented skeleton fails validation	Aligned — every authority states the rule the validator runs
Hand-written module README	Fails unless the blank line is removed	Passes as documented
Out-of-order marker report	One "blank lines only" finding per body line (51 on a 74-line README)	One auto block must appear after the format marker finding
Absent-marker finding	Anchored to line 1, no placement rule	Anchored to the line it belongs on, with the rule
Module README format date	2026-09-01	2026-09-01 — unchanged, no migration
Minimum CLI for skills	2.1.0	2.1.0
Passing tests	4,726	4,736
Line coverage	97.71%	97.75%

⬆️ Upgrade notes

1. Re-run the macOS/Linux install.sh or Windows install.ps1 installer, which downloads releases/latest. The skills' probe floor stays at 2.1.0, so a 2.1.0 binary keeps working — but it also keeps rejecting hand-written READMEs that follow the convention, which is the reason to upgrade.
2. Run prospec upgrade in each downstream project. _module-readme-conventions.md is itself a canonical document, so a new template triggers canonical-doc-drift; the existing consent-gated resync path updates its generated format and preserves your Project Section Extensions registry byte-for-byte (preserveUserContent: true).
3. Run prospec check --strict. No check was added or removed — still 21.
4. No configuration migration and no content migration are required. The relaxation is a strict superset of the old rule: the format marker date remains 2026-09-01 and not one module README needs editing. The "zero migration" claim covers the module README surface; the canonical convention document itself is refreshed by step 2.