folio verification — sandbox verification framework spec

REQ-VER-001: Each verification scenario file SHALL be a YAML file placed under tests/scenarios/ with the structure defined in §3.2.

REQ-VER-002: Each scenario SHALL reference one canonical req_id from rules.html §10 (REQ-CM-* / REQ-CI-*) or relations.html §5.3 (REQ-REL-*), or be a verification-specific REQ-VER-* defined in this §3.

REQ-VER-003: Each scenario expect block SHALL specify exit_code as the primary assertion.

REQ-VER-006: Scenario assertion SHOULD NOT rely on permissionDecision JSON output as primary, due to known upstream bugs (Issue #37210 / #33106 / #39344 / #18312、 すべて Closed/not planned 状態 ―― 詳細は research §2.6)。

REQ-VER-004: baseline file SHALL follow the TypeScript compiler 2-dir model: tests/baselines/reference/ (VCS 管理、 golden) vs tests/baselines/local/ (実行生成、 .gitignore)。 baseline 更新は明示的 accept workflow (例: runner.sh --accept) を経る MUST。

REQ-VER-007: IF a Write tool creates a .html file carrying <meta name="folio-doc-type" content="spec"> outside the configured spec_path, THEN the PreToolUse path-boundary hook SHALL deny (exit 2)。 scenario: scenarios/path-boundary.yaml (ADR-0003 §2.1 Option Pragmatic、 絶対 path 配下も第 2 branch *"/$2"* で gate)。

REQ-VER-008: IF a Write tool creates a .html file under a cluster directory that contains a README.html index, and the new file is not listed in that index, THEN the PostToolUse README-index hook SHALL notify (exit 2、 PostToolUse のため file は作成済)。 scenario: scenarios/readme-index.yaml。 これは check 型 staleness 通知で、 ADR-0003 §2.1「README update」の試作 slice。 ADR literal は「自動更新 (mutate)」だが 試作は check 型を採用 (divergence trace = specs/README.html §6.2)。

REQ-VER-009: WHEN the folio plugin is verified as an integrated tool in a live-loaded session (§4.1 Step 2 worktree integration), an agent SHALL walk the e2e runbook scenarios (tests/e2e/runbook.md) by issuing real Edit/Write tool calls so the live hooks fire, and SHALL record per-scenario observations as golden baselines under tests/e2e/baselines/reference/。 primary assertion = file 作成有無 (PreToolUse deny ⇒ file 不在、 PostToolUse notify ⇒ file 存在 + 通知)。 deny は transcript に確実には現れない (research §2.6) ため、 exit code でなく file system state を一次 assertion とする。 実装 = tests/e2e/ (runbook + golden、 sandbox 単体テストの mock payload 検証 (REQ-VER-001〜008) とは別 layer の統合検証)。

REQ-VER-010: WHEN the folio inventory CLI subcommand runs, it SHALL produce an inventory.json conforming to the relations.html §4.1 schema (required fields $schema / generatedAt / folioVersion / specs[]), scanning the directories defined in relations.html §4.4.1。 conformance は §3.4 golden baseline との kind: cli-golden diff で検証する (非決定的 generatedAt は normalize.exclude_paths で除外)。 scenario: scenarios/inventory-gen.yaml (REQ-VER-011 harness が実行)。

REQ-VER-011: WHEN a scenario carries kind: cli-golden, the verification harness SHALL (1) run bin/folio with the scenario command at repo root, (2) normalize both the produced output_file and the golden via jq -S with normalize.exclude_paths deleted, and (3) assert byte-exact equality of the normalized JSON plus exit_code match。 golden 更新は明示的 accept workflow (--accept、 §3.4 REQ-VER-004) を経る MUST。 これは hook scenario (kind: hook) の exit-code 中心 assertion (REQ-VER-003) とは 別の assertion 経路を成す (CLI subcommand 検証の SSoT、 ADR-0018 で trace)。

REQ-VER-012: WHEN the folio prime CLI subcommand runs, it SHALL emit a Tier 1 inventory digest (per-spec @id / title / summary / doc-type / status、 relations.html §4.2 Tier 1) to stdout as agent-readable text, auto-regenerating inventory.json if missing or stale (ADR-0007 §2.4)。 conformance は §3.4 golden baseline との kind: cli-golden (capture: stdout + compare: text) diff で検証する。 scenario: scenarios/prime-digest.yaml。 SessionStart hook による実 context 注入 (ADR-0007 §2.1、 matcher 省略で全 source 発火) は e2e (REQ-VER-009 型) で検証 = SessionStart:startup 注入 PASS (fresh session で Tier 1 digest が context に注入されることを確認)。 PreCompact は ADR-0007 amend (2026-05-25) で除去 (stdout 非注入)。

REQ-VER-013: WHEN the folio validate CLI subcommand runs, it SHALL scan the spec set (relations.html §4.4.1 と同一 = design-intent/{spec,decisions,research} の <head> JSON-LD .html) and check two gates: (a) internal link-integrity — each JSON-LD relation @id resolves to an existing target file, and any #anchor resolves to an existing id in that target (REQ-CI-010 の (b)+(c)); (b) jsonld structural — parse + required @context/@id/@type + @context == object (REQ-CI-016、 ADR-0004 Option B Light)。 exit code は 0 = clean / 1 = violation 検出 / 2 = tool error (jq 不在等、 fail-closed)、 違反は human-readable report を stdout 出力する。 検査 root の override (test isolation) を提供する MUST。 external URL check と prose gate (REQ-CI-011〜015) は 試作 scope 外 (Phase X4+、 ADR-0020 §2.2)。 conformance: clean 集合は scenarios/validate-clean.yaml (cli-golden、 capture:stdout、 exit 0)、 violation 検出 (missing file ref / broken anchor / jsonld 構造違反の 3 種) は実装時に scenarios/validate-violations.yaml + seeded fixtures で 実証する MUST (exit 1 + report)。 ADR-0020 で trace。

REQ-VER-014: WHEN the folio init [<dir>] CLI subcommand runs, it SHALL scaffold the canonical Layer 1 consumer layout の純粋な構造のみ — design-intent/{spec,decisions,research}/、 各 cluster の README.html (P-6 entry point、 index は実在 file のみ dc:hasPart 宣言)、 design-intent/spec/{constitution,overview}.html (project starter template、 通常 conforming JSON-LD)、 および folio.config.yaml (rules §2 schema: folio_version / spec_path / caller_marker_env / caller_marker_value / review_model) — そして既存 file は preserve (idempotent、 上書きしない)。 constitution / overview の本文 (実体) は seed しない — folio-architect の greenfield onboarding grilling が引き出した中身を Phase E で lazy-materialize する (§7.1、 ADR-0031 が ADR-0024 の seed 挙動を revise)。 これで空 placeholder が "done" に残る hollow-spec を構造的に排除する。 生成された skeleton は folio validate が clean (exit 0) である MUST (P-6 orphan + link-integrity + jsonld structural を満たす seed)。 exit code は 0 = success / 2 = tool error (fail-closed)。 conformance は scenarios/init-scaffold.yaml (cli-golden) で検証する: init を temp root に実行 → exit 0 + 生成 tree の file 集合 + folio.config.yaml の golden 比較 + folio validate --root <tmp>/design-intent clean。 init は tree (複数 file) を生成するため既存 cli-golden harness (単一 output) の拡張が要る可能性があり、 その HOW は実装時に確定する。 scope 決定は ADR-0024 (seed 挙動は ADR-0031 で revise) で trace。

REQ-VER-015: WHEN the folio fix CLI subcommand runs, it SHALL materialize, for each forward relation declared in any spec (relations §5.1 の 6 dual pair), the corresponding reverse relation on the target spec's <head> JSON-LD (REQ-REL-002)、 idempotent に (既存 reverse は重複追加しない)、 exit 0。 併せて folio validate は第 3 gate「broken-reverse」を持ち、 forward に対応する reverse が target に欠ける場合 violation を報告する MUST (REQ-REL-004、 exit 1)。 folio fix 適用後は folio validate (3-gate) が clean になる (detect↔remediate ペア)。 conformance は cli-golden + fixture で検証する: (a) fix が reverse を materialize + exit 0、 (b) fix 後 validate clean、 (c) idempotency (再 fix で no-op)、 (d) broken-reverse を seed した fixture に validate が exit 1。 scenario / golden / harness の HOW は実装時に確定。 scope 決定は ADR-0025 で trace (validate を ADR-0020 の 2→3 gate に拡張)。

REQ-VER-016: WHEN the folio-architect SKILL executes Phase F (Quality Review), it SHALL spawn the Phase F review agents in parallel (spec-review-{ears,vocabulary,ssot} = X4-D の 3 軸、 残 3 軸 structure/temporal/stakeholder は X5+) and aggregate their structured findings (severity / location / 違反 rule / 修正提案)。 検証は 2 経路: (a) structural — 各 review agent の agents/<name>.md frontmatter (name / description / model / read-only tools) が妥当で、 scoped name folio:<name> が resolvable (frontmatter name 一致 + folio-architect SKILL が当該 scoped name を参照) であること (決定的、 sandbox 可)。 (b) e2e — 既知 violation (EARS 欠落 / forbidden synonym / domain 越境) を seed した spec に /folio-architect を invoke し、 3 review agent が該当 violation を flag することを観察する (REQ-VER-009 型 agent-driven runbook)。 LLM agent は非決定的ゆえ golden 比較でなく 「検出有無」 を一次 assertion とする。 conformance: (a) は scenarios/agent-structure.yaml (kind: agent-structural、 file 静的検査・決定的・exit 0)、 (b) は tests/e2e/ runbook S-G (live walk は plugin reload を要すため別 fresh session)。 review agent は read-only (Edit は folio-architect が集約後に適用、 caller-marker author 一元性)。 scope 決定は ADR-0027 で trace。

REQ-VER-017: WHEN the folio validate CLI subcommand runs, it SHALL additionally check four object cross-reference gates (ADR-0034 §2.6): (1) resolve-integrity — each <a class="xref" href> resolves to an existing definition site; (2) uniqueness — each canonical ID is defined at most once as an id-bearing SSoT element; (3) tooltip-consistency — each data-tooltip matches the definition's current essence (§9.2 contract); these three are universal. (4) completeness — orphan-mention detection, applied only to docs that opt in via <meta name="folio-xref-completeness" content="enabled"> (conditional, REQ-XREF-002)。 conformance は scenarios/xref-validate-clean.yaml (cli-golden、 capture:stdout、 exit 0) + scenarios/xref-validate-violations.yaml (broken-xref / stale-tooltip / orphan-mention の 3 種を seed、 exit 1 + report)。 real corpus は xref dogfood 前 (opt-in 0) ゆえ本 gate 追加後も validate-clean.yaml が clean を維持する (additive、 keystone)。

REQ-VER-018: WHEN the folio fix CLI subcommand runs, it SHALL, for each doc that opts into xref-completeness, wrap the first prose occurrence of each auto-materializable canonical token (P-N / REQ-* / ADR-NNNN) into <a class="xref" href data-tooltip> with the href and data-tooltip derived from the §9.1 registry / §9.2 essence contract, idempotently (re-run = no-op、 既存 xref を持つ token は skip)。 非 opt-in doc では no-op (real corpus 不変、 keystone)。 conformance は scenarios/xref-fix.yaml (kind: cli-fix: pre-fix validate が orphan-mention で RED → fix exit 0 → post-fix validate clean → 再 fix idempotent)。 scope 決定は ADR-0034 §2.5 (option F) で trace。

WHEN the folio validate CLI subcommand runs and a vocabulary.yaml with definition fields exists, REQ-VER-019: it SHALL check a glossary gate over each marked term (<span class="term" data-term="<canonical>">, whether explicit or auto-marked — 共に span 形に統一): (1) resolve — data-term resolves to a canonical entry in vocabulary.yaml; (2) tooltip-consistency — data-tooltip equals that entry's definition; (3) anchor-residue — enforcing the span-only marking convention of rules §9.5 (which is the normative SSoT) by blocking any <a class="term"> in living spec/research prose ([glossary-anchor-residue]、 vocabulary.yaml 解決に依らず); all block (exit 1) on failure。 generated glossary.html term-set parity with vocabulary.yaml is structurally implied by the nav-regen-drift byte check (no independent parity gate; the symmetric difference is surfaced in the regen-drift violation message, conformance scenarios/glossary-parity-drift.yaml)。 folio fix SHALL materialize each marked term's data-tooltip from the definition, idempotently。 unmarked term mentions SHALL NOT be gap-linted (Class B best-effort)。 vocabulary.yaml 不在 / definition 無しは gate skip (additive、 keystone)。 conformance は scenarios/glossary-validate.yaml (unresolved + stale-tooltip を seed した fixture に validate が exit 1 + report、 resolved+consistent な clean 側は real corpus の glossary dogfood が keystone)。 scope 決定は ADR-0034 §2.8 で trace。

REQ-VER-020: WHEN the folio validate CLI subcommand runs, it SHALL check a dual-audience-structural gate over each data-audience="human" requirement container — both the verbose section.req card and the compact details.spec-row form, keyed by data-audience semantic (container-class 非依存、 ADR-0033 §2.5 / rules §7.2 2-form) — enforcing the five structural safety invariants REQ-DA-STRUCT-1..5: (1) the presence of a data-audience="machine" 子孫 (孤立 human の排除); (2) requirement-id 整合 (container id ↔ badge ↔ machine ears-id); (3) data-audience 値域 (machine | human のみ); (4) machine 部に aria-hidden 不在 (AI / accessibility-tree からの可視性保全); (5) EARS-pattern 整合 (human badge ↔ machine data-ears-pattern)。 違反は report + 非ゼロ exit (block gate)。 意味的 fidelity (essence が machine normative を忠実要約か) は本 floor の対象外であり、 ceiling = Phase F の spec-review-fidelity agent が担う (二層 enforcement、 ADR-0028 / ADR-0033 §2.4)。 本 gate は追加 arm として runtime-CDN script 検出 (rules §8 REQ-DA-JS-2 の vendoring 違反、 ADR-0039 §2.5 = 単一行 heuristic) も担う — conformance は validate-violations.yaml の cdn-script.html seed。 conformance は scenarios/validate-violations.yaml (da-violations.html が -1〜-5 を section.req + details.spec-row の両 form で 1 card 1 違反 = 計 10 違反 seed、 exit 1 + report) + scenarios/validate-clean.yaml (real corpus の dual-audience dogfood が clean 側 keystone)。 scope 決定は ADR-0033 §2.4 で trace (ADR-0020 の validate scope を dual-audience floor に拡張)。

REQ-VER-021: WHEN the folio validate CLI subcommand runs, it SHALL check a render-safety gate over each <pre class="mermaid"> block, flagging any subgraph whose title bracket (["…"]) contains a <br> (multi-line subgraph title) as a [render-safety] violation with non-zero exit, because mermaid reserves only one line of vertical padding for the cluster-label so the second line overlaps child nodes / the box border at render time — a post-render geometric defect the static, browser-less validate cannot observe directly, so the gate pattern-lints the known overlap-prone form (rules §4.5)。 node-label <br> は対象外 (node が自動 sizing するため overlap しない); mermaid を持たない spec は vacuously clean。 conformance は scenarios/render-safety.yaml (多行 subgraph タイトル + 通常 node label <br> を併存させた fixture に validate が [FAIL] render-safety + exit 1 + violation 1 件のみ = subgraph タイトルだけ捕捉し node label を誤検出しない)。 本 static pattern-lint は browser を要さず既知パターンを deterministic に捕捉する floor であり、 任意の render overlap (単行でも長すぎる label の溢れ等) の網羅は browser-render を要する視覚 gate (ceiling、 REQ-VER-022) の領分 (二層)。 scope は ADR-0020 の validate-scope を render-safety floor に拡張。

REQ-VER-022: WHEN the CI render-gate job runs (push / pull_request), it SHALL render every corpus page (repo-root index.html + design-intent/**/*.html) in headless chromium at three viewports (375×667 / 768×1024 / 1280×900) and probe the post-render DOM geometry, flagging six defect classes with non-zero exit (merge block): (1) cluster-label-multiline — subgraph タイトルの縦 overflow (rendered height を svg の viewBox→rendered 縦比 (scaleY) で intrinsic px に正規化し、 useMaxWidth:true の縮小 render でも閾値が scale に引きずられない — mermaid は uniform scale で render するため縦横比は同値); (2) label-over-foreign-node / cluster-label-over-node — text label が自分以外の node 矩形と交差 (面積比、 scale 不変); (3) node-over-node — layout collision; (4) content-clipped — 要素が svg 可視範囲を溢れて clip され読めない (svg overflow は既定 hidden。 判定は rendered px = 視覚上の clip 量で、 (1) の intrinsic 正規化とは意図的に非対称); (5) horizontal-overflow (chrome 幾何 arm、 ADR-0039 §2.8) — 本文が viewport を溢れ document 全体に意図しない横スクロールが発生 (scrollWidth > clientWidth + 2px。 overflow-x:auto の意図された scroll container 内の wide content は document に寄与しないため発火しない。 culprit は clip/scroll 祖先を持たず viewport 右端を越える最外要素を最大 5 件 + 超過は残余 entry で報告し、 特定不能でも document 溢れ自体を報告する = fail-visible); (6) nav-over-content (chrome 幾何 arm) — nav landmark と本文 block の矩形交差 (面積比 > 0.15。 通常 flow の隣接 block は矩形が交差しないため chrome 注入の位置事故・absolute 化の崩れでのみ発火。 closed <details> の中身は Chromium が非 0 の phantom rect を返すため checkVisibility() で非描画要素を除外する)。 render-gate が測る post-render DOM は post-JS の既定表示 — 既定の人間プレゼン化 (ADR-0040 / rules §11.3) 以降、 data-audience を持つ page では chrome script が付与する body.audience-human 状態の幾何を測る (人間が実際に見る view を検査する)。 audience-human が隠す display:none の machine prose も同じ checkVisibility() filter が非描画として除外する (machine 部は幾何検査の対象外 = false positive を生まない)。 mermaid arm (1)〜(4) の検査対象 svg と期待図数は実 <pre class="mermaid"> block 数 (HTML コメント内・prose 内 escaped 言及は数えない — 図は人間層に置き machine 降格しない規律 (rules §11.5) により、 隠れた図の render 不足 false-fail を作らない)、 chrome arm (5)(6) は全 page が対象。 It SHALL fail-closed: render 不足 (rendered svg 数 < 実 block 数) は見逃しでなく failure に倒す。 It SHALL save a full-page screenshot of every page × viewport as a CI artifact (人間 review の補助に充てるのみで golden 比較は行わない — pixel golden は brittle ゆえ幾何 detector + 人間の目の二層で代替、 ADR-0039 §2.8)。 constitution.html (自身の @type が FolioConstitution) は advisory (表示のみ・exit 非影響、 編集禁止資産への blocking は frozen deadlock になるため。 floor の carve-out と同基準)。 coverage の穴は SHALL emit a warning として可視化し silent pass にしない: 幾何対象 (.node/.cluster) を持たない図型 (sequenceDiagram 等) は vacuous-coverage、 .node は出すが図型 (aria-roledescription) が flowchart/graph でない型 (stateDiagram 等 — 構造だけでは flowchart と区別できない) は uncalibrated-coverage (幾何は測るが threshold は flowchart 較正)。 検出力は selftest (fixture 13 case、 violation kind の完全一致判定 (mermaid arm と chrome arm の和集合): detector (1)〜(6) 全 arm の発火 + scale<1 での (1) 正規化発火 (mutation 捕捉を実証済) + clean の誤検出なし + vacuous/uncalibrated 分類。 (2)(3)(4) の単独 arm は mermaid が通常生成しない欠陥ゆえ mermaid と同 class 構造の合成 SVG で、 (5)(6) は合成 page で固定。 同一 fixture を 375/768 で走らせる対が viewport plumbing 自体を、 意図された scroll container (overflow-x:auto) と closed-details phantom rect の clean fixture が chrome arm の誤検出排除を回帰固定する) が mermaid/chromium 版 drift への回帰ガード。 決定性は vendored mermaid + pinned playwright + pinned font (CI が fonts-noto-cjk を install) の三重 pin — deterministic ゆえ blocking 適格 (ADR-0037 §2.3、 ADR-0028 の LLM-ceiling 非決定性根拠は本 gate に適用されない)。 conformance は tests/render-gate/check.py --selftest + .github/workflows/ci.yml の render-gate job (browser 依存ゆえ sandbox scenario でなく CI-only dogfood — consumer の folio validate には入れない、 配布される floor は REQ-VER-021)。 scope/二層化の決定は ADR-0037、 3 viewport 化 + chrome 幾何 arm + screenshot artifact の拡張は ADR-0039 §2.8 で trace。

REQ-VER-023: WHEN the folio validate CLI subcommand runs, it SHALL check a readability-floor gate (ADR-0039 §2.7、 P-14 floor) with three blocking arms and five warning arms: block (1) viewport — every scanned doc carries <meta name="viewport"> inside <head> (head-anchored 走査で body / <pre> の raw/escaped 言及に誤反応しない。 rules §4.6 MUST の機械化。 ADR-0039 §2.7 列挙の 3 block への追加 arm = chrome 注入 slice の独立 ceiling 指摘「生成 page のみ viewport を持つ非対称」の是正、 divergence trace は本 REQ); block (2) essence 非空 — data-audience="human" requirement container が machine 対応部を持つのに人間向け要旨 (class="essence" / "req__essence") が無い・空 = 孤立 EARS (REQ-DA-STRUCT-1 の対称拡張。 living spec/research のみ — frozen decisions/ は remediate 不可 = stuck-RED ゆえ除外、 glossary gate と同基準。 container 外の machine 要素検出は ceiling の領分); block (3) landing hero — 生成 index (folio-generated marker、 hand-authored は keystone skip) の folio:landing-hero curated region が非空で <a href> を 1 本以上持つ (空 hero は build の placeholder 再 emit により nav-regen-drift と併発し、 両 violation が同じ remediate = folio build を名指しする); warn (4) essence 句点数 — essence 内の 「。」 が 4 個超 (日本語は語数の決定的計測が不能のため句点近似、 閾値 4 = corpus 較正 2026-06-11 実測 max 4); warn (5) 可視 prose 段落長 — prose_only 可視域 (pre / code / aside.machine-readable / chrome 除外、 class="ears" 完全一致の EARS 全文も除外) の単一 <p> 段落が 2000 codepoints 超 (UTF-8 継続 byte 除去による locale 非依存の決定計測。 閾値 2000 = corpus 較正 2026-06-11: blob 実測 9545 / 次点 1429 (gate 同一計測の codepoints) — blob 再発のみ見張る)。 加えて人間層プレゼン圧縮の warn 3 arm (ADR-0040 §2.5 / rules §11.5、 対象 = 圧縮対象ページ (living spec (subdir=spec、 constitution は scan 対象外) + doc-type=cluster-readme)、 frozen ADR と research の非 README (一次資料層) は skip。 ADR-0040 §2.6 の入口群のうち landing / glossary.html は build 所有の生成物で human-authored 長文 prose を持たないため v1 の機械検査対象外 = cluster README のみ gate し、 残りは ceiling / §11.4 walk に委譲する narrowing): warn (6) 人間層可視 prose 上限 — 既定表示で人間が読む量が約 12,000 codepoints (読了 20 分 box) 超。 計測は data-audience="machine" subtree (降格部、 同名 tag の depth 追跡) と <table> (線形読書しない = 満重みにしない、 v1 は 0 重み) を行 granular に除去 → prose_only → tag 除去 → codepoint 数 (除去は undercount 方向 = warn が鳴りにくい conservative); warn (7) 章要旨不在 — h2 章を持つ living spec ページに p.section-essence が 1 つも無い (v1 は page 単位 presence、 章単位への昇格は migration 後較正で判断); warn (8) 図ゼロ×長文 — 実 mermaid block ゼロかつ人間層可視 prose > 約 6,000 codepoints (目標 box。 block 数は raw grep で HTML コメント内を数えうるが overcount = warn 抑制側で conservative)。 warn 全系は doc-type=adr (frozen) を除外し、 exit code に影響しない (REQ-CI-014 と同じ warn channel)。 block violation は exit 1 + remediate tool/操作の名指し (ADR-0039 §2.9)。 warn 閾値の block 化は ceiling の指摘頻度を見て判断する (ADR-0039 §2.7 — 圧縮 3 arm は migration (folio-bqq) 完了後の corpus 実測で再較正してから昇格判断)。 conformance は scenarios/readability-floor.yaml (block 2 arm + warn 5 arm + hero dead-end + 圧縮 arm の正例 compress-over / 負例 compress-demoted (降格 + table 除去の回帰ガード)、 fix/build 済 fixture で他 gate clean = isolation) + scenarios/readability-floor-hero.yaml (hero 空 + nav-regen-drift 併発の対)。 意味的可読性 (文言の質) は floor の対象外 = ceiling (readability review lens、 ADR-0039 §2.8) の領分 (二層)。

REQ-NAV-001: WHEN the folio validate CLI subcommand runs and a top-level index.html carrying <meta name="folio-generated" content="folio-build"> in its <head> exists, it SHALL byte-compare that index against the deterministic folio build emit and report any difference as a [nav-regen-drift] violation (exit 1、 remediate = folio build)。 marker を持たない index は検査対象外 (keystone) であり、 marker 判定は <head> の実 <meta> に anchor し body の escaped/prose 言及に誤反応しない SHALL。 conformance: scenarios/nav-validate-clean.yaml (clean) / nav-validate-drift.yaml (drift 検出) / nav-validate-keystone.yaml (escaped-mention 誤発火なし)。

REQ-NAV-002: IF the generated index.html contains an <a href> whose relative target file does not exist or whose #anchor does not resolve to an id in the target, THEN folio validate SHALL report a [nav-dead-link] violation (exit 1)。 external scheme / pure-anchor / stylesheet href は対象外。 regen-drift が curated region を往復保全するため、 curated 内の手書き link rot は本 gate だけが捕捉する。 conformance: scenarios/nav-validate-deadlink.yaml。

REQ-NAV-003: IF an architecture cluster directory exists whose README.html has no outbound cross-cluster <a href> (dead-end), or which contains no scannable doc (empty cluster), or whose README.html has outbound links but none resolving to ../index.html (親 dir 自体を指す .. / ../ も index 到達可能形として受理) (index-backlink 欠落 — 兄弟 cluster へは抜けるが index へ戻れない「index 孤島」、 ADR-0035 §1 が名指した形。 dead-end 検出済みの README には重ねない = 1 README 1 主因で remediate を迷わせない。 remediate は folio build の breadcrumb 再生成 = detect↔remediate parity)、 THEN folio validate SHALL report it via the [cluster-reachability] gate — as a blocking violation when the root is folio-self (spec/ に @type FolioConstitution)、 as a warning (exit 0) when the root is a consumer corpus。 本 gate は dir/README scan 由来であり生成 index の有無に gate しない (post-init / pre-build window でも検査される)。 conformance: scenarios/nav-validate-reachability.yaml (self-root block、 index-backlink 欠落 arm を含む)。

REQ-NAV-004: WHILE a curated region (folio:nav-curated / folio:landing-hero) contains raw marker mentions inside its editorial content, folio build SHALL extract the region by first-open / last-close boundary (単純 state-machine の最初の close 終端ではなく) and round-trip the full editorial verbatim、 so that regeneration never silently drops content after a raw close-marker mention (#110/#116/#119 系譜の raw-mention 誤動作の回帰 guard)。 conformance: scenarios/nav-validate-curated-roundtrip.yaml (sentinel 保全を regen-drift [OK] で実証)。

REQ-NAV-005: IF the validate root is a consumer corpus (no FolioConstitution in spec/) and the [cluster-reachability] gate finds dead-end / empty-cluster / index-backlink 欠落 / link-rot findings, THEN folio validate SHALL emit them on the warning channel (exit code 非影響) instead of blocking — consumer の post-init / pre-build window で validate-clean 契約 (REQ-VER-014) を保ちながら気付きを与える。 conformance: scenarios/nav-validate-consumer-deadend.yaml (dead-end + dangling home link の 2 warn、 nav 系 gate は index 不在で [SKIP] のまま)。 index-backlink 欠落の warn 振り分けは gate の共有 dispatch (self block / consumer warn) に従い REQ-NAV-003 の self-root scenario と同経路 — 専用の consumer scenario は持たない (finding 種別ごとでなく gate 単位で振り分ける実装のため)。

REQ-NAV-006: IF a cluster README.html body contains an <a href> whose realpath-normalized relative target does not exist, THEN folio validate SHALL report it via the [cluster-reachability] gate の link-rot 検査 (self-root = block / consumer = warn、 REQ-NAV-003/005 の振り分けと同一)。 JSON-LD relation しか見ない link-integrity と生成 index しか見ない nav-dead-link の両方が README body href を未被覆のため、 link rot は本検査だけが捕捉する。 conformance: scenarios/nav-validate-readme-linkrot.yaml (self-root block 側、 consumer warn 側は REQ-NAV-005 scenario が併せて固定)。

REQ-NAV-007: WHILE a scanned page carries chrome marker regions (folio:chrome-top / chrome-toc / chrome-bottom、 ADR-0039 §2.3 の build 所有領域), folio validate SHALL verify that the page byte-equals its deterministic chrome re-render (folio_chrome_render_doc = strip → 再計算 → 挿入の純関数) and report any mismatch as a [chrome-drift] violation on the nav-regen-drift gate (exit 1、 remediate = folio build — §2.9 分業: 表示層 regen は build 所有)。 marker を持たない page は検査対象外 (keystone) SHALL。 生成規則 (既存 id のみ 2 段 fallback 目次 / prev-next 順序 SSoT / BASE_URL 二段構え breadcrumb) は ADR-0039 §2.3 を SSoT とし、 committed fixture bytes が意味論を pin する。 conformance: scenarios/chrome-validate-clean.yaml (clean + 生成規則 pin) / chrome-validate-drift.yaml (改竄検出)。

REQ-VER-005: Phase X3 着手時点で Step 1 (hook script unit test) を MUST 実装する。 Step 2 / Step 3 は段階追加 (SHOULD / MAY)。