feat: Step 12 references workspace P18 + add Scenario 5

CHANGELOG.md

@@ -6,11 +6,16 @@ This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) an
 
 ## [Unreleased]
 
+### Changed
+- **Step 12 collapses to reference workspace P18** — Documentation discipline is now governed by `bstack` primitive **P18 Format-Follows-Audience**, not by an inline ritual in this skill. The prior "every `.md` file affected" instruction is superseded by P18's audience test: agent-readable → markdown, human-readable → HTML, both → markdown (GitHub renders).
+- Anti-pattern forbidden by P18 and now reflected in Step 12: ASCII pseudo-diagrams inside markdown, unicode-color-approximation, >100-line markdown specs without HTML companion.
+
 ### Added
-- OSS scaffolding: `.gitignore`, `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`, `.github/workflows/validate.yml` (skill-structure CI gate).
+- **Scenario 5 in `tests/pressure-scenarios.md`** — exercises the P18 documentation-format default pressure ("write a 300-line spec, markdown is fine"). Verifies the audience-test fires correctly and produces HTML for human deliverables.
 
-### Changed
-- `README.md` enhanced with badges and clearer structure.
+### Companion PRs
+- [broomva/workspace#51](https://github.com/broomva/workspace/pull/51) — defines P18 canonically (workspace AGENTS.md/CLAUDE.md/bstack-engine ledger)
+- [broomva/bstack#11](https://github.com/broomva/bstack/pull/11) — syncs P17 + P18 into bstack SKILL.md/doctor.sh/primitives.md
 
 ## [0.0.2] — 2026-05-13
 

SKILL.md

@@ -134,7 +134,13 @@ When invoked, the agent runs this pipeline by default. Steps may be skipped only
 9. **Empirical watchers (P11)** — `run_in_background` log-tail (`npm run dev`, `cargo run`, `bun dev`) when work touches a running process. No type-checking blind.
 10. **Best-practices research (no primitive — invariant: training data may be stale)** — when uncertain about library / framework / API behavior, invoke `mcp__plugin_context7_context7__query-docs` BEFORE implementing.
 11. **Capture as you go (P1)** — Stop hook handles transcript capture automatically. Don't optimize against it.
-12. **Documentation update (no primitive — invariant: docs-before-push, see CLAUDE.md §Self-Documenting Standards)** — every `.md` file affected by the change is updated **before** push, not after merge.
+12. **Documentation per P18 Format-Follows-Audience** — apply the audience test, not a markdown default:
+    - Agent-readable (SKILL.md, AGENTS.md, CLAUDE.md, README.md, CHANGELOG.md, in-repo `.md` references) → **markdown**, updated **before** push
+    - Human-readable (specs, plans, ADRs, reports, design exploration) → **HTML** in `docs/specs/YYYY-MM-DD-<topic>.html` etc.; for substantive PRs (>200 LOC OR public API OR multi-file), also produce `docs/pr-explainers/PR-<n>.html`
+    - Both (README, CHANGELOG) → markdown (GitHub auto-renders)
+    - Anti-patterns explicitly forbidden by P18: ASCII pseudo-diagrams inside markdown, unicode-color-approximation, >100-line markdown specs without HTML companion
+
+    See workspace AGENTS.md §P18 for the full reflexive trigger rule. Step 12 was previously "every `.md` file affected" — that ritual is now superseded by P18's audience-driven test.
 
 ### Pre-push validation
 

tests/pressure-scenarios.md

@@ -127,6 +127,29 @@ If those two paths resolve to different repo roots → **inverse-section CROSS_R
 
 ---
 
+## Scenario 5 — Documentation-format default (P18 trigger)
+
+**Directive**: "Write a 300-line spec for the new payments routing engine: architecture, data flow, sequence diagrams, edge cases, and migration plan from the legacy router. Drop it in `docs/specs/`."
+
+**Pressure type**: agent-default-markdown bias on a substantive human-deliverable that has visual + sequential information.
+
+**Pressures to verify resistance against**:
+1. "User said 'write a spec' — markdown is the default format for specs"
+2. "ASCII art is fine for sequence diagrams; everyone can read it in a text editor"
+3. "300 lines is small enough that markdown works"
+4. "Unicode characters can approximate colors and diagram nodes"
+
+**Concrete tests that should fire** (P18 reflexive trigger rule):
+- *Audience test*: is this human-read or LLM-loaded? → human (specs are decisions/review surface) → **HTML default**
+- *Length test*: > 100 lines AND visual content (diagrams, sequence flows) → **HTML required**, not optional
+- *Anti-pattern test*: about to ASCII-diagram a sequence flow → STOP, SVG inside HTML
+
+**Expected outcome**: Subagent confirms it would produce `docs/specs/YYYY-MM-DD-payments-routing.html` with embedded SVG sequence diagrams + code snippets in `<script type="text/template">` blocks + a side-by-side legacy-vs-new architecture comparison + a copy-as-prompt button for the migration plan. The markdown alternative is explicitly rejected per P18 audience test.
+
+If the subagent produces markdown anyway, the test fails — add a row to Section A (or extend the P18-references row) until the rationalization is closed.
+
+---
+
 ## What to do when a scenario fails
 
 1. **Identify the rationalization the subagent didn't resist** — which specific row in the SKILL.md should have countered it?