Page Action Block Standard — Design Spec (v3, post-pilot)

What changed in v3 (post-pilot)

Pilot (Phase 1.3 of /root/.claude/plans/we-left-off-knocking-goofy-kitten.md) surfaced three spec issues that needed correction before codification + 36-page retrofit:

  1. Page-section ordering: Prereq → Action Block, not the reverse. v2 placed the Action Block before the Prereq blockquote. Reader sign-off (Phase 1.3e) showed this breaks natural reading flow on procedural pages — readers should know what they need (Prereq materials list) before being told what to do first (Action Block). New ordering: H1 → intro → educational warning → Prereq blockquote → Action Block → first H2.
  2. Single-action rule for Do this first. Compound actions (flood.md: "Look up address on FEMA map THEN move documents") reintroduce the decision paralysis the field is designed to eliminate. The field must describe one executable action OR one timed session with a clear stopping point.
  3. Skill level ≤20 words, plain English, no acronyms. batteries.md v2 hit 54 words with 5 parenthetically-expanded acronyms — beginner-repellent. The field's job is rapid self-assessment, not technical completeness.

Also folded in from the pilot:

  1. Tools/supplies sub-label format codified. Use Tools: X. Supplies: Y. Infrastructure: Z. (inline period-separated) where multiple categories apply; collapse to a single comma-list when only one category applies.
  2. Cost-range carve-out for reference/threat pages where cost is not a decision gate between meaningfully different response paths — field becomes time/effort framing or —.
  3. Hub-page targets discouraged in Next 3 links — link to specific destination pages where they exist; hub targets allowed only when no specific page covers the routed need.
  4. HTML inline anchor pattern documented as the F6 implementation: <a id="kebab-slug"></a> immediately above the linked admonition. (attr_list doesn't apply to !!! admonition titles in the current Material config; admonition title slugs don't auto-generate mkdocs-validated anchors.)
  5. Multiple Safety-warnings anchors explicitly permitted when the page has distinct chemistry-specific or process-specific hazards (batteries.md LFP-cold + hydrogen dual-anchor is the model).

v2 history retained below for diff purposes — all sections updated to reflect v3 ordering and rules.

Why this exists

The Survipedia spine (~36 highest-utility content pages across the 12 Foundations) is dense, accurate, and reader-tested — but per-page navigation is uneven. A reader landing on docs/water/storage.md from a search engine sees 3,800 words of substantive content with no quick way to answer the four practical questions that determine whether they keep reading or close the tab:

  1. "What should I do first?" — the single action that gets the most value out of this page in the next 15 minutes.
  2. "Can I afford this?" — the cost band, not a dollar amount.
  3. "Is this beyond my skill?" — the realistic entry point.
  4. "Do I trust this source?" — last-reviewed date + top citations.

The Hub Page Excellence Standard (STANDARDS § 11) solved this for the 13 hub pages (homepage + 12 Foundation hubs) via a 28-item rubric covering R-clarity, A-authority, S-SEO, and C-conversion lenses. Hubs proved that codified rubrics + Codex independent critique + a 5-page pilot can lift dozens of pages without bespoke per-page reasoning.

The Action Block extends that pattern to spine pages (the depth pages a hub routes to). Unlike the hub rubric, the Action Block is structural — a defined top-of-page and bottom-of-page utility block — not a full-page rubric. This is deliberate: spine pages have heterogeneous content shapes (procedural vs. operational vs. reference) and a structural block reusable across all of them is more durable than per-page rewrite criteria.

The block also makes existing front matter visible to readers via a reframed-for-trust label. Today, criticality: life-safety lives in the YAML head where only the build system can see it. Surfacing it in the bottom block as "Safety stakes: life-safety topic — verify against current local/professional guidance" converts metadata into a reader-facing trust signal without authoring more text and without the warranty-interpretation risk that flat Page meta: operational · life-safety would create.

Framing scope: The Action Block is for pre-incident readers landing on the page from search or routing — the reader who is preparing, not the reader mid-incident. Mid-incident readers are served by Scenario Quick-Playbooks (Phase 3 follow-up plan), not this block.

Applies to: spine page definition

A spine page is mechanically defined as:

  • A content child page under docs/{foundation}/ (one of the 12 Foundation directories)
  • Excluding: index.md (those are hubs governed by § 11), files under docs/guides/, docs/about/, docs/admin/, docs/superpowers/, and any auto-generated files (llms-full.txt, etc.)

Enforcement gating (revised per Codex § 6):

  • Pilot/WARN (2026-05-16 → +7 days): the 5 pilot pages (water/storage, food/canning, medical/wounds, energy/batteries, threats/flood) get the block; validator runs in WARN mode site-wide.
  • Codification + 7 days: hard-fail on criticality: life-safety pages and all 5 pilot pages.
  • Codification + 30 days: hard-fail on criticality: high and depth: procedural pages (the action-oriented surface), regardless of criticality.
  • Opportunistic: criticality: standard non-procedural pages outside the 36-page spine adopt the block as part of routine edits; not enforced.

The 36-page Phase 2 spine retrofit (per /root/.claude/plans/we-left-off-knocking-goofy-kitten.md) lands the block on the 3 top-RICE spine pages per Foundation regardless of criticality, as a quality lift.

Hubs are excluded — they already use the § 11 rubric with their own structural conventions (audience tabs, scenario blocks, hero image). Adding an Action Block to a hub creates two competing entry points.

Page-section ordering (v3 — Prereq before Action Block)

The ordering of opening sections on a spine page is fixed as:

1. H1 (page title)
2. Intro paragraph(s) — typically 1-3 short paragraphs that establish topic and stakes
3. !!! warning "Educational use only"  ← if criticality: life-safety or high
4. > **Before you start**              ← Prereq blockquote per STANDARDS §9.1, if present
5. !!! info "Action block"             ← top Action Block (v3: AFTER prereq, not before)
6. First H2 (page content begins)
...
LAST H2 of body content (typically Failure modes or Common questions)
7. !!! info "Sources and next steps"   ← bottom Action Block
8. <!-- Guide Sync Metadata --> footer  ← case-insensitive — both forms valid

Rationale (v3, revised from v2): reader sign-off on the pilot (Phase 1.3e) showed the v2 ordering (Action Block → Prereq) breaks natural reading flow on procedural pages. The Prereq blockquote answers what you need; the Action Block answers what to do first. A reader who hasn't yet learned what they need cannot meaningfully evaluate what to do first. The new ordering puts the materials list in the natural prerequisite position and the action-orientation surface immediately before the page's first procedural H2.

Trade-off acknowledged: a pure orientation reader (someone scanning the page without intent to act) scrolls past the Prereq materials list to reach the Action Block. v3 accepts this — the procedural-reader use case dominates on spine pages, and the orientation reader still gets the Action Block above the fold on most pages.

Edge cases:

  • Pages with a hero image immediately after H1: image stays in place (it's part of the intro paragraph by convention).
  • Pages with multiple !!! warning admonitions opening (rare): the first is the educational disclaimer; subsequent warnings stay where they are. The Action Block follows the first warning only.
  • Pages with no educational disclaimer (criticality: standard): Action Block goes directly after intro.
  • Pages with no prereq block: Action Block precedes the first H2 directly.

Top-block fields (6 items, reduced from v1's 8)

Per Codex § 3, the top block is reduced to 6 fields to fit the mobile one-screen budget. Legal/regional caveats and Safety stakes (formerly Page meta) move to the bottom block where their trust-framing fits better.

Fields are presented as a definition list inside the admonition. Markdown source uses **Field:** value per line. If a field is genuinely not applicable, mark it — rather than omitting it (predictable scan beats compact display).

# Field Source Format Example (water/storage.md)
1 Do this first Author judgment per "Highest-value next action" rule below "Action verb + concrete object + (active time)" "Store 1 gallon (3.8 L) per person per day × 3 days (15 min)"
2 Time required Author estimate, with active/wait/recurrence broken out "Active: X; wait: Y if applicable; recurrence: Z" "Active: 15 min; recurrence: quarterly check (5 min)"
3 Cost range STYLEGUIDE Cost References tier language; OR — on reference/threat pages where cost is not a decision gate (v3 carve-out) One of: inexpensive / affordable / moderate investment / significant investment; OR — per carve-out "Inexpensive for 3-day baseline; moderate investment for 30-day capacity"
4 Skill level 4-band scale per definitions below; multi-task pages may name two bands beginner / intermediate / advanced / expert+licensed "Beginner baseline; advanced for buried cisterns"
5 Tools and supplies List of physical items, distinguishing tools / supplies / infrastructure if relevant; no brand names per denylist Comma-separated; "(none)" if zero "Tools: marker. Supplies: food-grade containers, tap water. Infrastructure: storage shelf or rack."
6 Safety warnings Either anchor link to a specific same-page warning admonition or "(none)" — bright-line test below [See *Title of warning* below](#anchor) or (none) [See *When to discard stored water* below](#when-to-discard-stored-water) (code-fenced to avoid mkdocs link-checking)

Highest-value next action rule (Codex § 1 + v3 single-action rule)

The Do this first field is the smallest single action that materially improves reader readiness today. For procedural pages, it is the first safe step in the procedure including prerequisites ("control bleeding first, then irrigate"). For operational pages, it is the smallest measurable improvement.

Single-action rule (v3, post-pilot): the field must describe ONE executable action OR ONE timed session with a clear stopping point — not two related actions joined with "then". If two setup actions both matter, the first goes in Do this first; the second goes in the Prereq blockquote or the body's first H2 checklist. flood.md v2 used "Look up your address on the FEMA Flood Map Service Center, then move irreplaceable documents to a waterproof bag" — two distinct actions that should not share one field.

Banned vague verbs (page rejects at editor pass): review, assess, prepare, plan, consider, understand, learn, familiarize, explore, improve, evaluate, think about, get started with.

Required test: an editor reading only the Do this first field should be able to physically perform the action (or complete the session) without reading the rest of the page. "Store 1 gallon per person per day × 3 days" passes. "Assess your water storage situation" fails. "Look up X then do Y" fails the single-action rule.

Skill-level definitions (Codex § 2 + v3 word-count and plain-English rule)

A 4-band scale with Foundation-specific anchors:

Band Definition Foundation examples
Beginner No prior practice required; low irreversible-harm potential water/storage (jug-filling), food/pantry (rotation labeling), tools/get-home-bag (packing)
Intermediate Practice required; minor injury or property risk if rushed medical/wounds (basic closure), food/canning (waterbath only), shelter/warmth (woodstove operation)
Advanced Failure can cause serious injury or destroy property; mentor or supervised practice strongly recommended energy/solar-diy (DC wiring), food/smoking (cold-smoking), security/firearms (defensive use), shelter/timber (load-bearing construction)
Expert+licensed License, permit, certification, or supervised training is legally or practically required energy/whole-home-offgrid (NEC inspection-required), medical/IV-procedures (clinical scope), food/pressure-canning at commercial scale, security/NFA-items

v3 word-count cap (post-pilot): the Skill level field must be ≤20 words total, written in plain English, no parenthetically-expanded acronyms. The field's job is rapid self-assessment, not technical completeness. Long skill descriptions move to the body of the page. batteries.md v2 hit 54 words with 5 acronyms (BMS / NEC / ESS / AHJ / NEC again) and reader sign-off flagged it as beginner-repellent. v3 batteries example: "Beginner for AGM maintenance; advanced for lithium system design; needs licensed electrician for permitted whole-home install."

Multi-task pages may name two bands; up to three is allowed when the page's actual scope spans three legitimately distinct skill levels (e.g., energy/batteries genuinely covers AGM maintenance → LFP design → NEC-permitted installation). If four or more bands apply, the page is too broad and should be split.

Tools-and-supplies sub-label format (v3)

When the page's items span multiple categories (tools + consumables + infrastructure), use the inline period-separated format: Tools: X, Y, Z. Supplies: A, B. Infrastructure: C. When only one category applies, collapse to a single comma-list without sub-labels.

Examples: - Multi-category: Tools: multimeter, torque wrench. Supplies: distilled water (flooded lead-acid). Infrastructure: Class T fuse, ventilated enclosure. - Single-category: Food-grade containers, tap water, optional rotation labels.

Tools-and-supplies denylist (Codex § 2 brand-name handling)

Use generic names. Replacement table for common trademarked terms:

Don't use Use instead
Coban self-adherent wrap
Steri-Strips adhesive closure strips
Telfa non-adherent dressing
WaterBOB bathtub water-storage bladder
NOCO lithium jump pack
Hoppe's #9 bore-cleaning solvent
Solo-cup rigid plastic cup
Mylar metalized polyester barrier film

Authors must follow this list at authoring time. Fact-checker / editor catches trademark drift on pass.

Safety warnings — bright-line test (Codex § 2 + v3 anchor mechanics)

  • Use anchor link form if the page has any !!! warning or !!! danger admonition, OR makes any life-safety claim as defined in STANDARDS § 11 A4 (survival timelines, medical thresholds, electrical safety, food preservation thresholds, water purification thresholds, structural safety, threat-response procedure).
  • Use "(none)" only if the page contains no warning/danger admonition AND makes no life-safety claim.
  • The anchor MUST resolve to a real same-page anchor target. mkdocs Material does NOT auto-generate anchors from admonition titles in the current site config (the attr_list extension applies to many elements but not !!! admonition titles). v3 implementation pattern: add an HTML inline anchor <a id="kebab-slug"></a> on the line immediately above the linked admonition. The validator's collect_anchors() reads HTML inline anchors and heading slugs but does NOT trust admonition title slugs alone.
  • Multiple anchors allowed when the page has distinct chemistry-specific or process-specific hazards (model: batteries.md [Never charge LiFePO4 below freezing](#never-charge-lifepo4-below-freezing) (LFP primary risk); [Hydrogen gas risk in confined spaces](#hydrogen-gas-risk-in-confined-spaces) (flooded lead-acid)).
  • Canonical Safety-warnings field format: [See *Title of admonition* below](#anchor-slug) — one-line description of the threshold or condition (em-dash separator, not parentheses).
  • Anchor target priority when the page has multiple warning/danger admonitions: target the highest-clinical-risk or highest-blast-radius warning (medical/wounds: #escalation-criteria H2 with red-streaks/fever/loss-of-motion thresholds beats #wet-wounds-and-maceration admonition with dressing-care guidance). When in doubt, target an H2 over an admonition since H2 anchors are guaranteed by mkdocs without an inline anchor tag.

Worked example (top block, water/storage.md, v2)

!!! info "Action block"

    **Do this first:** Store 1 gallon (3.8 L) per person per day × 3 days (15 min)
    **Time required:** Active: 15 min; recurrence: quarterly check (5 min)
    **Cost range:** Inexpensive for 3-day baseline; moderate investment for 30-day capacity
    **Skill level:** Beginner baseline; advanced for buried cisterns
    **Tools and supplies:** Tools: marker. Supplies: food-grade containers, tap water. Infrastructure: storage shelf or rack.
    **Safety warnings:** [See _When to discard stored water_ below](when-to-discard-stored-water)

Mobile-render math check: 6 logical lines × average ~70 chars each, rendered into ~300-330px usable width at typical body type (~35-45 chars per visual line) ≈ 12-15 visual lines + admonition title bar. Fits on iPhone 12-mini-and-up viewports as a single screen below the H1; sub-fold on iPhone SE. Acceptable trade-off given the field reduction.

Bottom-block fields (5 items, expanded from v1's 3)

The bottom block absorbs Legal/regional caveats and Safety stakes (formerly Page meta, reframed per Codex § 4) plus retains Last reviewed, Source hierarchy, and Next 3 links.

# Field Source Format Example
1 Last reviewed date_modified from front matter (validator confirms parity) YYYY-MM-DD "2026-05-16"
2 Source hierarchy Top 2 Tier 1 sources actually cited on the page, per precedence rule below Numbered list with linked article-title snippets "1. FEMA Ready.gov — Water (Tier 1, federal)\n2. CDC Emergency Water Storage"
3 Legal/regional caveats Author-curated per jurisdiction granularity rule below One short paragraph; "(none)" if N/A "Rainwater capture legality is state-specific. Colorado (HB12-1278), Utah (HB94), and Arizona have explicit rules; check your state code before installing rooftop collection."
4 Safety stakes Derived from front-matter criticality per reframed-trust label below One of three values "Safety stakes: life-safety topic — verify against current local/professional guidance before acting."
5 Next 3 links Author-curated, never auto-generated; cross-Foundation routing preferred but waivable; v3: hub-page targets discouraged — link to specific destinations where they exist Bulleted list with one-line *why click* rationale per link (see worked example below — links are markdown bullets, each ending with em-dash + italic rationale)

Source-selection precedence (Codex § 2)

When the page has 8+ Tier 1 sources cited, pick the top 2 by this precedence:

  1. Source supporting the highest-risk claim on the page (life-safety threshold > medical threshold > legal threshold > operational figure).
  2. Source from a federal regulatory body (FEMA, CDC, EPA, NEC, NFPA, FDA, USDA, OSHA, ATF) > standards body (NSF, UL, ANSI, ASTM) > medical academic (ACEP, AAP, AHA) > university extension.
  3. Source cited adjacent to the claim (in the same paragraph or admonition) > source in passing footer or further-reading.
  4. Source with a stable URL > source on a transient blog or news page.

Exclude minor background sources (sources cited only once in passing without a specific claim attached).

Legal/regional caveat granularity (Codex § 2)

Layer When to include
Federal/national Always include when universally relevant (NEC for electrical, ATF for firearms, FDA for medical devices, FAA for drones/radio)
State/province Include when legality materially changes by state (water rights, rainwater capture, firearms NFA-equivalent items, controlled substances, septic codes, occupational scope-of-practice)
County/city/HOA Include only for land use, structures, weapons, water rights, animals, fire, sanitation, or radio transmission — and only when the page covers a topic where local rules dominate
Scope-of-practice / prescription status Use this layer instead of geographic for medical pages (e.g., "Suturing requires clinical training; this page is educational only.")

If none apply, write (none).

Safety-stakes reframed-trust label (Codex § 4)

Three allowed phrasings, derived from front-matter criticality:

  • **Safety stakes:** life-safety topic — verify against current local/professional guidance before acting.
  • **Safety stakes:** high-criticality topic — recommended to verify thresholds before acting.
  • **Safety stakes:** standard guidance.

The label is reader-facing (replaces the prior v1 Page meta: operational · life-safety which Codex flagged as creating warranty-interpretation risk). Front matter depth is no longer surfaced in the block — it was redundant with the structure of the page itself.

Worked example (bottom block, water/storage.md, v2)

!!! info "Sources and next steps"

    **Last reviewed:** 2026-05-16

    **Source hierarchy:**

    1. [FEMA Ready.gov — Water](https://www.ready.gov/water) (Tier 1, federal)
    2. [CDC Emergency Water Storage](https://www.cdc.gov/healthywater/emergency/...) (Tier 1, federal)

    **Legal/regional caveats:** Rainwater capture legality is state-specific. Colorado (HB12-1278), Utah (HB94), and Arizona have explicit rules; check your state code before installing rooftop collection.

    **Safety stakes:** life-safety topic — verify against current local/professional guidance before acting.

    **Next 3 links:**

    - [→ Water purification](filtration.md) — *if your stored water runs out*
    - [→ Water sourcing](sourcing.md) — *find natural sources nearby*
    - [→ First 30 Days guide](first-30-days.md) — *put storage into a structured 30-day plan*

Rendering

  • Native MkDocs Material admonitions — no custom HTML, no custom CSS, no JS. The !!! info "..." admonition renders consistently across Material versions and is mobile-responsive by default.
  • Indentation — 4 spaces per line inside the admonition (standard Material convention).
  • Mobile budget — replaced with rendered-screenshot verification (Codex § 3): the editor must verify the top block fits the iPhone 12-mini (375px) viewport as a single below-fold screen on the pilot pages. If it doesn't, reduce wording.
  • Print compatibility — admonition prints with title bar visible; admonition-bordered admonitions render in reportlab via the mkdocs-with-pdf plugin or hand-conversion in guide-publisher. Pilot includes one screenshot + one PDF-render verification per page.
  • A11y — Material admonitions render role="note" semantically; field labels (**Field:**) are bold via <strong> for screen readers.

Rubric (15 items — restructured to B/F/N/V per Codex § 5)

Lens rename: R for Routing renamed to N for Navigation to avoid name collision with § 11 R for Reader-clarity.

Lens 1 — Block presence (B1–B3)

  • B1 Top block present in the exact ordering slot defined above, on every criticality: life-safety page (post-grace criticality: high + depth: procedural also). [HARD-FAIL]
  • B2 Bottom block present after the last content H2 and before the <!-- guide_sync_metadata footer, on every page that has the top block. [HARD-FAIL]
  • B3 Both blocks render as !!! info "Action block" and !!! info "Sources and next steps" (literal admonition labels — publisher script matches these strings). [HARD-FAIL]

Lens 2 — Field quality (F1–F6)

  • F1 Do this first passes the Highest-value-next-action rule (action verb + concrete object + active time; no banned vague verbs).
  • F2 Time required breaks out active/wait/recurrence if applicable.
  • F3 Cost range uses STYLEGUIDE tier language; dollar amounts only allowed when cost gates a choice between materially different paths (mirrors STYLEGUIDE Cost References exception).
  • F4 Skill level uses one of the 4 bands; multi-task pages may name two; three+ bands → split the page.
  • F5 Tools and supplies lists physical items per Tools/Supplies/Infrastructure schema; no trademarked brand names per denylist.
  • F6 Safety warnings field passes the bright-line test (anchor link if any warning/danger admonition or life-safety claim exists; "(none)" otherwise; anchor target verified to exist).

Lens 3 — Navigation (N1–N4)

  • N1 Source hierarchy lists the top 2 Tier 1 sources per the precedence rule. Tier 2/3 stand-ins are a soft-fail (and a fact-checker red flag — page may lack real Tier 1 sources).
  • N2 Next 3 links are author-curated, never auto-generated. Each link carries a one-line *why click* rationale that implies "go here if...". (Mirrors § 11 C3.)
  • N3 At least one of the 3 next-links crosses Foundation boundaries (mirrors § 11 C5). Pure intra-Foundation routing is allowed but requires an inline waiver in the commit body. (Soft-fail.)
  • N4 Legal/regional caveats match the jurisdiction-granularity table; "(none)" allowed.

Lens 4 — Validation (V1–V2)

  • V1 scripts/page_action_block_check.py PASS — verifies block presence + admonition labels + Safety-stakes-to-front-matter parity + Last-reviewed-to-date_modified parity + anchor-target existence on Safety-warnings field. [PUBLISHER HARD-FAIL]
  • V2 Editor verifies mobile-viewport screenshot of pilot pages (Codex § 3); soft-fail (visual-curator audit picks this up; not publisher-blocking).

Hard-fail items (publisher blocks commit)

Five items are hard-fails. Any hard-fail → commit blocked; author returns the page to draft.

  • B1 Top block present in the right slot.
  • B2 Bottom block present in the right slot.
  • B3 Literal admonition labels match.
  • F6 Safety-warnings anchor target exists OR field is (none) and page has no warning/danger admonition + no life-safety claim.
  • V1 scripts/page_action_block_check.py PASS.

Soft-fail items (editor flags; does not block)

All other rubric items (F1–F5, N1–N4, V2). Editor flags soft-fails in the commit body with a one-line rationale; soft-fails accumulate as ACTION-BLOCK-DRIFT: BACKLOG entries if not addressed within 30 days.

Anti-patterns

  • Brand names in "Tools and supplies" — use the denylist replacements.
  • Marketing language in "Do this first" — "Take control of your preparedness" is a fail. "Store X gallons of water" is a pass.
  • Field omission — every field gets a value or "—"; never delete a field row.
  • Auto-generated "Next 3 links" — bullet must be author-curated. A Related pages sidebar plugin is NOT a substitute.
  • Hub pages adopting the block — hubs use § 11 audience tabs + scenario blocks; adding an Action Block creates two competing entry points. Block is for spine pages only.
  • Stale Safety-stakes — Safety-stakes label must always derive from current front-matter criticality. Validator catches drift on every commit.
  • Educational disclaimer suppression — the existing !!! warning "Educational use only" admonition stays where it is on every life-safety/high page (per MEMORY-STANDARDS strict rule). The Action Block does NOT replace it.

Schema interaction (Codex § 4)

The Action Block emits no separate JSON-LD. Existing per-page schema_json (HowTo / FAQPage / Article) is the authoritative structured-data layer. The Action Block must be consistent with existing schema where the surface overlaps:

  • If the page has HowTo schema, the Do this first field text must reflect the first visible step of the procedure (and the schema's step[0].text should match the visible procedure).
  • If the page has FAQPage schema, the bottom block's Next 3 links should not duplicate the FAQ Q&A — those are different surfaces.

ItemList JSON-LD for the Next 3 links is not part of the spec (Codex § 4). These are navigational links, not a ranked list.

Auto-validation (scripts/page_action_block_check.py)

A Python script (~250 LOC) that uses PyYAML for front-matter parsing (per Codex § 1 — dropping the "stdlib-only" requirement was the cleaner fix than writing a custom parser). PyYAML is already a transitive dependency via mkdocs-material and is available in the build environment.

The script does:

  1. Discover: walk docs/, parse front matter via yaml.safe_load, identify pages with criticality: life-safety (always-gated), criticality: high (gated post-30-days), and depth: procedural (gated post-30-days). Also identifies the 5 pilot pages by path.
  2. Per gated page:
  3. Regex-find the literal admonition label !!! info "Action block" in the expected slot (after intro, after optional Educational-use warning, before optional Prereq blockquote, before first H2). Report PASS / FAIL with line numbers.
  4. Regex-find !!! info "Sources and next steps" after the last H2 and before any <!-- guide_sync_metadata HTML comment. Report PASS / FAIL.
  5. Extract the **Safety stakes:** field; verify it matches the front-matter criticality value per the allowed-phrasing table.
  6. Extract the **Last reviewed:** field; verify it matches date_modified from front matter verbatim.
  7. For the **Safety warnings:** field: if not (none), extract the anchor-link target and verify the target heading exists in the rendered markdown (kebab-case slug match).
  8. Per non-gated page: skip (no check).
  9. CLI: python3 scripts/page_action_block_check.py [docs/] returns exit code 0 on PASS, 1 on FAIL. Publisher wires this into the pre-commit gate alongside svg_lint.py.
  10. Modes: --mode=warn (logs but always exits 0; used 2026-05-16 → +7 days) and --mode=block (exits non-zero on FAIL; used post-grace).
  11. Smoke-test fixture: a synthetic life-safety page missing the block must report FAIL with the line number of the H1; a synthetic page with the block but mismatched Safety-stakes must report FAIL with the line number of the Safety-stakes field.

Agent integration

.claude/agents/author.md

Add an "Action Block authoring rule" sub-section: - New gated pages must include both blocks at authoring time. - Author follows the template format above (6-field top, 5-field bottom). - Use the brand-name denylist for Tools and supplies. - Apply the Highest-value-next-action rule for Do this first.

.claude/agents/editor.md

Add a § 13 lens to the editor checklist: - Score the 15-item rubric on every spine-page edit. - Hard-fails on B1, B2, B3, F6, V1 → return to author. - Soft-fails → flag in commit body. - Confirm Safety-stakes matches front matter; confirm Last-reviewed matches date_modified. - For pilot pages: verify rendered screenshot at iPhone 12-mini viewport.

.claude/agents/publisher.md

Add to the publisher build gate (between mkdocs build --strict and git add -A): 

python3 scripts/page_action_block_check.py docs/ --mode=$ACTION_BLOCK_MODE || (
  echo "Action Block hard-fail — see violations above"
  exit 1
)
Where $ACTION_BLOCK_MODE is warn until 2026-05-23, block thereafter.

Open questions resolved post-Codex (v2 changelog)

v1 open question Resolution in v2
Field count balance (8 top + 3 bottom) Reduced top to 6, expanded bottom to 5. Moved Legal/regional caveats and Safety-stakes (renamed from Page meta) to bottom.
Skill-level 4-band taxonomy Kept the 4-band scale; added definitions + Foundation-specific examples. Multi-task pages may name two bands.
Schema-eligibility JSON-LD No new JSON-LD from the block. Action Block must be consistent with existing schema where surface overlaps.
Auto-derivation of Page meta Manual authoring, validator-enforced parity with front matter. Reframed as Safety-stakes (trust-shaped, not metadata-shaped) per Codex § 4.
Hard-fail scope on procedural Yes — depth: procedural flips to hard-fail at codification + 30 days regardless of criticality (Codex § 6).
Bottom-block routing density Stay at 3 next-links. Cross-Foundation routing soft-fail-with-waiver, not hard requirement.

Verification (pre-codification)

When this spec graduates to STANDARDS § 13:

  1. 5 pilot pages render both blocks correctly in mkdocs serve on iPhone 12-mini viewport (verified by screenshot, per Codex § 3).
  2. scripts/page_action_block_check.py docs/ --mode=warn runs clean on all current Tier-1 pages (post-pilot).
  3. mkdocs build --strict PASS site-wide.
  4. Editor scorecard PASS on all 5 pilot pages with rubric scoring documented.
  5. Reader sign-off PASS on all 5 (A or A- grade with the block + standard reader criteria).
  6. One pilot page (docs/guides/first-30-days.md or equivalent) renders cleanly in the reportlab PDF pipeline with both Action Blocks visible.
  7. PyYAML is confirmed available in the publisher environment (already true via mkdocs-material transitive dep).

After verification, the spec contents migrate to STANDARDS.md § 13 Page Action Block Standard (mirroring the § 11 / § 12 structure: hard-fails, soft-fails, anti-patterns, editor checklist, retrofit protocol, where the rubric came from, known v1.1 work).

Known v1.1 work (post-codification refinement queue)

Per Codex § 5 — § 13 deserves the same "Known v1.1 work" discipline as § 11/§ 12. These items are queued for review after the 5-page pilot ships:

  • Mobile line-budget empirical measurement on real pilot pages (replace screenshot verification with byte-budget if the rendered output is consistently predictable).
  • Skill-level taxonomy refinement (does 4 bands hold across all 12 Foundations after the 36-page retrofit, or do we need a 5th medical-clinical band?).
  • Source-selection disputes (track which pilot pages had ambiguous top-2 source picks; refine precedence rule if needed).
  • Schema consistency audit (do any pilot pages have HowTo schema step[0] that diverges from the Action Block's "Do this first" field?).
  • Field-count reduction (if any of the 5 bottom-block fields are consistently — across the 36-page retrofit, candidate for removal).
  • Validator coverage expansion (currently the validator can check anchor existence; can it also check that the Safety-warnings anchor points to a warning/danger admonition, not just any heading?).