本 rules は Layer 1 consumer project に適用する (folio Layer 0 本体は folio-self-spec.html)。folio.config.yaml の schema は §2、 MUST 要件は §10 に集約する。
Layer 1 consumer の directory layout と folio.config.yaml の構造を定める。folio が govern するのは architecture/ の 3 domain のみで、 実装適合性 test の location は規定しない (P-13(b))。
<consumer-project>/ # 例: scribe / my-typescript-app / 等
├── README.md
├── CLAUDE.md (or AGENTS.md) # platform-specific binding (P-2 例外、 P-11 root 例外)
├── folio.config.yaml # folio plugin consume 宣言 + userConfig override
│
├── architecture/ # Layer 1 design-intent 空間 (folio rules で書かれた、 P-7 3-domain)
│ ├── index.html # walkable nav (folio build が graph から生成、 generated-view、 ADR-0035)
│ ├── spec/ # design intent (WHAT、 cwd で context 即判定)
│ │ ├── README.html # spec entry point (constitution P-6)
│ │ ├── constitution.html # project 固有 constitution (folio core 継承 + project 固有)
│ │ ├── overview.html
│ │ └── ...
│ ├── decisions/ # decision (WHY、 ADR project 固有)
│ └── research/ # exploration (spec 反映前の探索)
│
├── <test dir> # HOW-test (実装適合性): consumer の stack 慣習 (tests/ 等)、 folio 非規定 (P-13(b)、 ADR-0026)
│
└── <実装本体 dir> # HOW-impl (architecture/spec/ に従う)
├── (scribe の場合) skills/, agents/, commands/
├── (TS webapp の場合) src/, components/, app/
└── ...
folio が govern するのは architecture/ の 3 domain (design intent / decision / exploration) のみ (P-7、 ADR-0022)。 実装適合性 test (HOW-test) は consumer の stack 慣習 (tests/ 等) に置き、 folio は location を規定しない (P-13 (b)、 ADR-0026)。 一般 documentation (Diátaxis tutorial / how-to / explanation 等) や AI-steering context は consumer の自由領域で folio は規定しない (consumer が docs/ 等で任意に持つ)。
folio.config.yaml 構造 (schema 詳細は folio-self-spec.html §8):
folio_version: "^0.4" # folio framework の依存 version (semver range)
spec_path: "architecture/spec/" # default、 userConfig で override 可能
caller_marker_env: "FOLIO_ARCHITECT_CONTEXT"
caller_marker_value: "folio-architect"
review_model: "opus" # optional、 Phase F specialist の model
cwd で context 即判定: AI Agent は cwd が <consumer>/ 配下なら consumer project 編集中、 <consumer>/architecture/spec/ 配下なら Layer 1 spec 編集中、 <consumer>/skills/ 等の実装 dir 配下なら実装編集中、 と物理 dir で判定可能。 folio Layer 0 編集の判定は folio-self-spec.html §7.4 5-Layer Defense を参照。
全 HTML file 名は kebab-case、 ADR は ADR-NNNN-<slug>、 各 cluster は README.html を持つ MUST。 vocabulary.yaml の schema は terms 配列 (canonical MUST / forbidden = gate 用)。
kebab-case.html (例: spec-taxonomy.html)。 snake_case / camelCase 禁止。ADR-NNNN-<slug>.html (4 桁 ID)。vocabulary.yaml (project root or architecture/、 P-2 YAML 例外)。folio.config.yaml (consumer project root、 P-2 YAML 例外)。README.html を持つ MUST (orphan 例外、 constitution P-6)。vocabulary.yaml の schema (P-5 canonical naming SSoT): terms: の配列で、 各 entry は canonical (正準名、 MUST) と forbidden (禁止 synonym の配列 — vocabulary gate REQ-CI-013 が prose 内検出に使う) を持つ。 加えて各 entry は optional に definition (1 行定義)、 relationships (他 canonical 名との関係を述べる配列)、 flagged_ambiguities (grilling で surface した未解決の曖昧点の配列) を持ってよい。 これらは glossary を folio-architect grilling (Phase C) と spec-review-vocabulary agent の grounding として豊かにする (ADR-0031 §2.4)。 後方互換: vocabulary gate は forbidden のみ読むため、 optional field の有無は既存の gate 挙動に影響しない。
全 spec file は head 4 要素 (meta / title / css link / JSON-LD)・body 冒頭 aside・RFC 2119 boilerplate・section wrapper を MUST 採用する。 visual richness と a11y minimum も本章が定める。
全 spec file は以下の構造を MUST 採用する。
<head> Metadata (3 層 + JSON-LD 関係性)全 spec file の head は (1) meta tag による flat metadata、 (2) title、 (3) common.css への link、 (4) JSON-LD 関係性ブロックの 4 要素を MUST 含む。
全 spec file の <head> は (1) <meta> tag による flat metadata、 (2) <title>、 (3) <link> stylesheet、 (4) <script type="application/ld+json"> による関係性ブロックの 4 要素を MUST 含む。 JSON-LD ブロックの内容 schema は relations.html §3 に集約する。
<head>
<meta charset="UTF-8">
<meta name="folio-doc-type" content="spec"> <!-- constitution|spec|adr|changes|research|tutorial|howto|explanation -->
<meta name="folio-layer" content="core"> <!-- core|project -->
<meta name="folio-version" content="1.2.0">
<meta name="folio-status" content="active"> <!-- draft|active|deprecated|archived -->
<meta name="folio-stakeholders" content="Developer, AI Agent">
<meta name="folio-arc42" content="section-5"> <!-- arc42 mapping (optional) -->
<meta name="folio-diataxis" content="reference"> <!-- tutorial|howto|reference|explanation -->
<title>...</title>
<link rel="stylesheet" href="../../common.css">
<script type="application/ld+json">
{ /* JSON-LD block: relations.html §3.2 Full Example を参照 */ }
</script>
</head>
採用する vocabulary (dc:*, schema:*, folio:*) および @id resolution rules は relations.html §1 (W3C 標準語彙) と §2 (folio 独自語彙)、 §3.3 (@id 解決規則) に MUST 従う。 関係性のない spec (constitution.html 等) は dc:references / folio:depends-on を省略してよい。
aside.machine-readable<aside class="machine-readable" aria-hidden="true">
<dl>
<dt>id</dt>building-blocks
<dt>doc-type</dt>spec
<dt>arc42-section</dt>5
<dt>stakeholders</dt>Developer, AI Agent
<dt>version</dt>1.2.0
<dt>status</dt>active
</dl>
</aside>
全 normative section を含む file は冒頭に boilerplate aside (RFC 2119 / RFC 8174 / BCP 14 準拠) を持つ MUST。
section.normative / section.informative WrappersMUST/SHALL を含む section は <section class="normative"> で wrap、 説明・rationale のみの section は <section class="informative"> で wrap する。 common.css が視覚的境界を表現する。
folio spec は visual richness を装飾でなく WHAT 精度向上の手段として selective に採用する (P-3、 採用前に user へ推奨提示 = P-8)。 mermaid subgraph タイトルは単行 (多行 overlap を REQ-VER-021 が機械検査)。
folio spec は HTML を表現基体としており、 plain text を超える visual richness を活用できる。 domain の構造を反映する visual element を selective に採用し、 装飾でなく WHAT 表現の精度を高める手段として用いる (P-3 WHAT-only 整合)。 spec author (人間および folio-architect) は domain を grill した後、 visual cue 候補を user に推奨答えとして提示してから採用する (P-8 silently choosing 禁止)。
| domain pattern | 推奨 element | 用途例 |
|---|---|---|
| lifecycle / 状態遷移 | mermaid stateDiagram-v2 | binding live/tombstone/expired/未存在、 issue draft/active/done |
| caller-system 対話 / 操作 sequence | mermaid sequenceDiagram | API client → service の request/response、 multi-component 連携 |
| decision flow / 分岐 | mermaid flowchart | adoption-state 検出、 ADR alternatives 選択木 |
| component 関係 / 継承 | mermaid classDiagram | architecture layer 関係、 base/derived 関係 |
| data model / entity 関係 | mermaid erDiagram | binding ← short-code × target-URL 等の entity 関係 |
| traceability matrix | <table> | REQ-ID × constitution 原則 × component 実装 |
| alternative comparison | <table> | ADR §3 採用/不採用 candidates × criteria |
| state transition matrix | <table> | 遷移元 × 遷移先 × トリガー (stateDiagram と併用可) |
| progressive disclosure | <details> + <summary> | optional / advanced 内容、 長い enumeration の折りたたみ |
| structured definition | <dl> + <dt>/<dd> | 用語 / 原則 / component の definition |
| dual-audience requirement (machine SSoT + human essence) | <section class="req" data-audience> + <details> fold | 規範要件を machine normative + human 要約で co-author (§7) |
| concept flow (per-section「どう動くか」) | mermaid flowchart | section 単位 1 枚の概念図 (dual-audience human view) |
| compact requirement list (「何があるか」) | 純 CSS list (1 行 1 REQ) | 最小読量で REQ 一覧を提示 (dual-audience human view) |
| coverage RTM (traceability) | <table> (REQ × derives × scenario × verified) | trace / coverage 主題の section、 空 mapping = gap 可視化 |
| EARS keyword 色 badge | <span class="req__ears--<p>"> | EARS pattern の視覚識別 (色 mapping は folio 独自設計) |
text・diagram text は WCAG 2.2 SC 1.4.3 AA contrast、 head は viewport meta、 mermaid 図は accTitle/accDescr・fill override 時の color paired・overflow scroll の focusable 化を満たす MUST。
spec HTML 内の text および diagram 内 text は WCAG 2.2 SC 1.4.3 Level AA (normal text 4.5:1 / large text 3:1) の contrast ratio を満たす MUST (w3.org/TR/WCAG22/#contrast-minimum)。
spec HTML は <head> に <meta name="viewport" content="width=device-width, initial-scale=1"> を持つ MUST — viewport meta が無いと実機 mobile browser は仮想幅 (約 980px) で render して縮小表示し、 responsive CSS が発火せず可読性が崩れる (WCAG 2.2 SC 1.4.10 Reflow の前提)。 folio init seed と folio build 生成物 (index / glossary) は付与済で、 authored spec 側の欠落は folio validate の readability-floor gate (REQ-VER-023) が機械強制する。
mermaid 図表は以下を満たす MUST:
accTitle および accDescr directive を付与する (WCAG 2.2 SC 1.1.1 non-text content / mermaid a11y、 mermaid.js.org/config/accessibility.html)。classDef / style で fill を override する場合、 同 declaration 内で color を paired 指定する (themeVariables.primaryTextColor 継承による text contrast 不足を防ぐ)。 stroke は theme default の 3:1 contrast 維持を許容するが、 visual separation が確保されない場合は paired 指定する SHOULD (WCAG 2.2 SC 1.4.11 graphical objects)。figure.diagram 内の render 済 <pre class="mermaid"> = 図そのものが overflow した場合) は tabindex="0" で keyboard-focusable にする MUST (WCAG 2.2 SC 2.1.1 Keyboard / axe scrollable-region-focusable、 dequeuniversity scrollable-region-focusable)。 scroll 容器は figcaption を含む figure でなく内側の pre.mermaid に限定する (figcaption の xref tooltip 等による spurious overflow を避ける)。 folio では initialize script が render 後に overflow した pre.mermaid へ tabIndex を付与し、 併せて role="region" + 図 title 由来の aria-label で scroll 領域を screen-reader に明示する (§8 read-only enhancement、 <pre class="mermaid"> raw fallback は不変)。本章は spec 改訂の trace を spec 本文に inline 保存する HTML-native な markup (ins/del.delta + data-delta-* 属性) を定める。 命名は D-YYYY-MM-DD-NNN format (同日連番)。
spec 改訂の trace を spec 本文に inline 保存する。 OpenSpec の ADDED/MODIFIED/REMOVED に相当する HTML-native 実装。
<ins class="delta" data-delta-id="D-2026-05-22-001" data-delta-date="2026-05-22">新しい要件テキスト</ins>
<del class="delta" data-delta-id="D-2026-05-21-003" data-delta-superseded-by="D-2026-05-22-001">旧テキスト</del>
grep pattern: data-delta-id 属性で全変更を file 横断抽出可能。 命名: D-YYYY-MM-DD-NNN format で同日連番。
本章は acceptance criteria に EARS の 5 pattern (Ubiquitous / Event-driven / State-driven / Optional / Unwanted) を採用し、 data-ears-* 属性付き HTML markup で記述する。
acceptance criteria は EARS (Easy Approach to Requirements Syntax) の 5 pattern を採用する。
| pattern | template | 用途 |
|---|---|---|
| Ubiquitous | The system SHALL ... | 無条件不変条件 |
| Event-driven | WHEN [trigger], the system SHALL ... | event 応答 |
| State-driven | WHILE [precondition], the system SHALL ... | 状態継続中 |
| Optional | WHERE [feature included], the system SHALL ... | 機能オプション |
| Unwanted | IF [unwanted condition], THEN the system SHALL ... | 異常応答 |
<p class="ears" data-ears-pattern="event-driven">
<span class="ears-id">REQ-002</span>:
<span class="ears-when">WHEN AI agent attempts to write to spec</span>,
the system <span class="ears-shall">SHALL</span> verify caller context declaration.
</p>
specialist agent spec-review-ears (folio-self-spec.html §7.2) が pattern 完全性 + ID uniqueness を CI で検証する。
spec を機械向け (精密 normative = SSoT) と人間向け (essence + 図) の双方へ 1 HTML に co-author する markup。 採用は任意だが採用 spec は §7.3 invariant 遵守 MUST (conditional-normative)。 consistency は二層 enforcement (floor / ceiling) で担保。
data-audience は closed 2 値 (machine | human) の canonical 属性。 synonym は P-5 で禁止、 継承無く明示付与のみ。 presentation 要素にも付与でき、 REQ-DA-STRUCT-1 MUST は req container のみ。
data-audience = closed 2 値 core (machine | human)、 canonical。 AI 抽出 ([data-audience="machine"]) の決定性と floor 検査の単純化のため 2 値固定。data-reader / data-for 等) は P-5 (1 entity = 1 canonical name) により禁止。data-audience は requirement container (§7.2 の 2 form) 以外の presentation 要素にも明示付与できる — 例: 章要旨 p.section-essence (§11.5) への human、 informative 地の文の降格 wrapper への machine (ADR-0040)。 REQ-DA-STRUCT-1 の「machine 対応部 MUST」は requirement container (<section>/<details> 起点の floor 走査) にのみ適用され、 単独の presentation 要素には適用されない。requirement は 2 form (card / spec-row) で human essence と machine normative を data-audience + fold で co-author。 machine 部は DOM 常在・aria-hidden 無し・視覚のみ畳む。 id・badge・ears-id は一致、 EARS pattern は data-ears-pattern が SSoT。
dual-audience の 1 requirement は 2 つの正規 form のいずれかを採る。 いずれも human (派生 view、 既定可視) と machine normative (canonical SSoT) を data-audience + <details> 視覚 fold で 1 unit に co-author し、 machine 部は DOM に常在 (AI / accessibility-tree / find-in-page に可視) して視覚的初期表示のみ畳む。 aria-hidden を machine 部に付けない (accessibility-tree から消すと Playwright 等 AI からも不可視となり「AI は読める」目的に反する、 ADR-0033 §2.2 verified)。 floor は container class でなく data-audience="human" semantic で両 form を一律に被覆する (ADR-0033 §2.5、 §7.3)。
form 1 — verbose card (<section class="req">。 essence を常時可視に展開、 解説密度が要る個別要件向け):
<section class="req" id="req-xxx-001" data-audience="human">
<div class="req__card">
<span class="badge badge--req">REQ-XXX-001</span>
<span class="req__ears req__ears--event">Event-Driven</span> <!-- EARS badge (§6) -->
</div>
<p class="req__essence">…(human 要約 = machine normative の正確な要約)…</p>
<details class="req__machine" data-audience="machine"> <!-- canonical SSoT、 DOM 常在、 no aria-hidden -->
<summary>normative (machine)</summary>
<div class="req__normative">
<p class="ears" data-ears-pattern="event-driven">
<span class="ears-id">REQ-XXX-001</span>:
<span class="ears-when">WHEN …</span>, the system <span class="ears-shall">SHALL</span> ….
</p>
</div>
</details>
</section>
form 2 — compact spec-row (<details class="spec-row">。 1 行 1 REQ = 最小読量、 多数の要件を一望する section 向け。 summary に essence、 fold 内に machine normative。 reference 実装 = verification.html §3):
<div class="spec-list"> <!-- 複数 .spec-row を束ねる container -->
<details class="spec-row" id="req-xxx-001" data-audience="human">
<summary>
<span class="badge badge--req">REQ-XXX-001</span>
<span class="req__ears req__ears--event">Event</span> <!-- EARS badge (§6) -->
<span class="essence">…(human 要約 = machine normative の正確な要約)…</span>
</summary>
<div class="spec-normative" data-audience="machine"> <!-- canonical SSoT、 DOM 常在、 no aria-hidden -->
<p class="ears" data-ears-pattern="event-driven">
<span class="ears-id">REQ-XXX-001</span>:
<span class="ears-when">WHEN …</span>, the system <span class="ears-shall">SHALL</span> ….
</p>
</div>
</details>
</div>
規約 (両 form 共通): (a) 要件 container の id (小文字、 section / details いずれも) ・ .badge--req text ・ machine .ears-id text は同一 requirement-id (大小文字正規化で一致)。 (b) human badge の CSS class suffix (req__ears--<p>) は EARS pattern key を用いる (2 語 pattern は common.css の短縮形 event / state = canonical event-driven / state-driven の alias)。 (c) machine normative の pattern は data-ears-pattern (full form = SSoT)。 (d) reference 実装 = verification.html §3 (form 2 compact spec-row を flagship に採用、 form 1 verbose card は本 §7.2 の例示)。
dual-audience 採用 spec は REQ-DA-STRUCT-1〜5 の構造 invariant 遵守 MUST。 floor (validate) が両 form を data-audience=human で一律検査。 fidelity は ceiling (spec-review-fidelity) が担う。
dual-audience pattern を採用する spec は次の構造 invariant を満たす MUST。 これらは folio validate の dual-audience gate (deterministic floor、 ADR-0020 scope 拡張) が機械検査する。 検査は §7.2 の verbose card (section.req) と compact spec-row (details.spec-row) の両 form を data-audience="human" semantic で一律被覆する (container class 非依存)。 意味的 fidelity (essence が normative を忠実要約か) は floor の対象外で、 ceiling = spec-review-fidelity agent が担う (二層 enforcement、 ADR-0028 / ADR-0033 §2.4)。
[data-audience="human"] requirement container は [data-audience="machine"] 子孫を持つ MUST (孤立 human の排除)。
REQ-DA-STRUCT-1:
WHERE a spec adopts the dual-audience pattern,
each [data-audience="human"] requirement container (verbose card または compact spec-row) SHALL
contain a [data-audience="machine"] descendant (派生元の存在保証、 孤立 human の排除)。
id ・ .badge--req text ・ machine .ears-id text 間で case 正規化して一致する MUST。
REQ-DA-STRUCT-2:
WHERE a spec adopts the dual-audience pattern,
the requirement-id SHALL be consistent (case-normalized) across the
requirement container id (section / details), the .badge--req text, and the machine .ears-id text。
data-audience 値は machine か human のみ (synonym 禁止、 P-5)。
REQ-DA-STRUCT-3:
WHERE a spec adopts the dual-audience pattern,
every data-audience value SHALL be one of
machine or human only (no synonym、 P-5)。
[data-audience="machine"]) は aria-hidden を持たない MUST NOT (AI / accessibility-tree からの normative 不可視化を防ぐ)。
REQ-DA-STRUCT-4:
WHERE a spec adopts the dual-audience pattern,
the machine part ([data-audience="machine"]) SHALL NOT
carry aria-hidden (AI / accessibility-tree からの normative 不可視化を防ぐ)。
req__ears--<p>) は machine data-ears-pattern と整合する MUST (短縮形 alias を正規化して比較)。
REQ-DA-STRUCT-5:
WHERE a spec adopts the dual-audience pattern,
the human EARS badge (req__ears--<p>) SHALL agree with
the machine data-ears-pattern (短縮形 alias を正規化して比較)。
human view (concept 図 / list / coverage RTM / EARS badge / fold) は §4.5 menu に集約、 強制しない guidance (author 判断、 P-8)。 普遍性は tiered (core/RTM 普遍、 図・list は section 依存、 coverage opt-in)。
human 向け graphical view の構成要素 (concept flowchart / compact REQ list / coverage RTM / EARS keyword 色 badge / <details> fold) は §4.5 の visual richness menu に dual-audience 用 row として集約する。 これらは強制しない guidance (author・folio-architect 判断、 P-8 silently choosing 禁止)。 普遍性は tiered: dual-audience core (data-audience + fold + essence) と trace RTM は普遍、 concept 図 / compact list は適用可能な section、 coverage 列 (verified/scenario) は verification mapping を持つ spec の opt-in (ADR-0033 §2.6)。
spec HTML 内の JavaScript の使用範囲を定める。 原則は JS = render/view の read-only enhancement に限り、 normative content (定義/要件/MUST) の SSoT にしない (canonical は常に static)。 JS 含む spec は本章遵守。
REQ-DA-JS-1: WHERE a spec includes JavaScript, the JavaScript SHALL be limited to read-only view enhancement derived from static DOM content, and SHALL NOT hold the SSoT of any normative content (定義 / 要件 / MUST)。
fetch() は不使用 (file:// 破綻)。
REQ-DA-JS-2:
WHERE a spec includes JavaScript,
the spec SHALL remain fully readable with JavaScript disabled
(progressive enhancement), SHALL vendor its libraries (no runtime CDN),
and SHALL NOT use ES modules with fetch()
(file:// で null origin CORS により破綻、 verified)。
vendoring 違反のうち runtime-CDN script (<script src="http(s)://…"> および
protocol-relative src="//…") は folio validate の dual-audience gate が
機械検出する (escaped 例・<pre> 内 raw 例は mask、 ADR-0039 §2.5)。 検出は
単一行 tag の試作 heuristic — 行跨ぎ tag は守備範囲外で、 網羅は ceiling の領分
(folio の corpus 慣習は単一行 script tag)。 conformance: scenarios/validate-violations.yaml
(cdn-script.html seed、 double/single-quote 両形)。
| 区分 | 具体 |
|---|---|
| ALLOW | static DOM content から派生する view enhancement (TOC 補完 / mermaid render / cross-ref tooltip / dark-light toggle / beforeprint で <details> 一括 open)。 mermaid は vendored render として ALLOW。 |
| PROHIBIT | JS のみに存在する normative / fetch ロード content の SSoT 化 / CDN 実行時取得 script による content 生成 / ES modules + fetch() (file:// 破綻)。 |
| REQUIRE | noscript でも full content が読める / library は vendoring (CDN 不可) / single-file classic <script> か inline / inline data は <script type="application/json"> 同梱 / CSP は meta tag + hash ('sha256-…'、 nonce は static で不可)。 |
flowchart TB accTitle: xref lifecycle (hybrid: in-band SSoT から projection を生成) accDescr: prose 内の canonical token を folio fix が a.class=xref に materialize し、 href は in-band HTML の id (SSoT 定義 site) へ解決する。 data-tooltip は folio fix が定義 site の essence をコピーして生成する。 そこから folio validate の completeness gate と no-JS tooltip と AI-graph projection が派生する。 T["prose 内の裸 token\n(P-N / REQ-* / ADR-NNNN)"] FIX["folio fix\nauto-materialize"] X["a.class=xref\nhref + data-tooltip"] SSOT["in-band HTML の id\n= canonical SSoT 定義 site"] ESS["§9.2 essence 抽出\n(定義 site を再利用)"] VAL["folio validate\ncompleteness gate (opt-in)"] TIP["no-JS hover tooltip\n(:hover/:focus-visible)"] GRAPH["AI-graph projection\n(inventory/prime)"] T --> FIX --> X X -->|href 解決| SSOT ESS -->|data-tooltip 供給| X SSOT --> ESS X --> VAL X --> TIP X --> GRAPH
architecture 内 defined-object の in-band cross-reference・no-JS hover tooltip・完全性 enforcement を hybrid で定める (in-band id が SSoT、 lint/AI-graph/glossary は projection)。 穴は folio fix が materialize・完全性は validate・採用は opt-in。
defined-object への inline 参照は untyped な xref とし、 href は §9.1 registry に従い SSoT 定義 site (canonical ID 小文字化の id) へ解決 (ADR は file 自体)。 規則 § は explicit-tier で auto-gap 検出はしない。
defined-object への inline 参照は untyped な xref とする (typed/directional relation は file-level JSON-LD = relations §5 に留め object-level は roadmap、 untyped ゆえ folio fix の auto-materialize が成立する)。 markup form:
<a class="xref" href="<referencing-doc → SSoT-doc の相対 path>#<id>" data-tooltip="<essence>">TOKEN</a>href は referencing doc から下記 registry の SSoT-doc への相対 path + #<id> (canonical ID を小文字化した定義 site の id)。 decision (ADR) は file 自体が定義 site のため anchor 無し (file への相対 path)。 data-tooltip は §9.2 essence 抽出 contract が生成する定義 essence (folio fix がコピー)。 rule (§) は doc 跨ぎで一意な canonical token を持たない (「§7.3」は曖昧) ため explicit xref tier = resolve 検査 + tooltip + graph edge は得るが裸言及の auto-gap 検出はしない (auto-materialize 対象外)。
| prefix | class | SSoT doc | 定義 site / anchor |
|---|---|---|---|
P-N | principle | constitution.html | <dt id="p-N"> |
REQ-VER-* / REQ-NAV-* | requirement | verification.html | id="req-ver-NNN" / id="req-nav-NNN" (§3.6 / §3.8) |
REQ-REL-* | requirement | relations.html | id="req-rel-NNN" |
REQ-CI-* / REQ-DA-* / REQ-CM-* / REQ-ADR-* / REQ-XREF-* / REQ-GLOSS-* | requirement | rules.html (本 file) | id="req-…" |
ADR-NNNN | decision | decisions/ADR-NNNN-*.html | file 自体 (anchor 無し) |
| rule § | rule | rules.html | <h2 id="…"> (explicit-tier) |
marking 正規化: 上記 resolve の前提は「全 object が id 付き SSoT 要素を持つ」 こと。 rules.html の全 canonical object (REQ-CI-* / REQ-DA-* / REQ-CM-* / REQ-ADR-* / REQ-XREF-*) は §7.2 form 2 の id 付き spec-row を SSoT 定義 site として持ち、 この前提を満たす (旧 EARS-list / 概要 table 形は spec-row へ正規化し、 §10.2 の table は spec-row への cov-link に転換)。
data-tooltip 生成 (folio fix)・tooltip-consistency 検査 (folio validate)・glossary が依存する横断機構。 essence は定義 site の既存内容を再利用し (新規に書き起こさない = P-7 重複禁止)、 plain-text 化と attribute escape を必ず行う。
data-tooltip 生成 (folio fix) と tooltip-consistency 検査 (folio validate) と将来の glossary が依存する横断機構。 essence は定義 site の既存内容を再利用し (新たに書き起こさない = P-7 重複禁止)、 必ず plain-text 化 (内部タグ strip) + attribute escape する。
| class | 定義 site | essence の元 |
|---|---|---|
REQ-* | spec-row <details class="spec-row" id="req-…"> (または verbose card <section class="req">) | <summary> 内 .essence (または .req__essence) の text |
P-N | constitution <dt id="p-N"> | <strong> text から "P-N: " prefix を除いた title 部 |
ADR-NNNN | decisions/ADR-NNNN-*.html | <header> .meta div の末尾 · セグメント (summary) |
| rule (§) | rules.html <h2 id="…"> | 見出し text (explicit-tier、 auto-wrap なし) |
tooltip は §8 と整合する no-JS CSS-only 機構 (:hover + :focus-visible の擬似要素 box)。 tooltip 抜きでも xref は click で定義へ飛ぶ working baseline link を保つ (tooltip は上載せ)。 viewport 端の切れは限界。
tooltip は human のみの可読性 enhancement (AI は href/graph を辿るため不要)。 規約は §8 JS governance と整合する:
[data-tooltip] に対し :hover + :focus-visible で擬似要素 box を表示 (common.css、 既存 surface/border/text token で light/dark 両対応)。 JS に依存しない (REQ-DA-JS-2 progressive enhancement)。:target flash で着地点強調)。 tooltip は load-bearing でない上載せ。href + data-tooltip) は将来 JS (同属性を読む rich/cross-doc preview) と前方互換で非破壊に重ねられる (§8 準拠、 1.0.0 core 非搭載)。resolvable xref として数え AI-graph edge の SSoT とするのは <a class="xref"> 形のみ。 cov-req・plain nav link・normative-ref は projection に参加しない。
<a class="xref" href data-tooltip> 形を用い、 href は §9.1 registry に従い object の SSoT 定義 site に解決する。
REQ-XREF-001: An inline reference to a defined-object (principle P-N / requirement REQ-* / decision ADR-NNNN) SHALL use the <a class="xref" href data-tooltip> form, whose href resolves to the object's SSoT definition site per the §9.1 prefix→SSoT-doc registry.
folio-xref-completeness=enabled) は、 prose の canonical token 言及ごとに resolvable xref を最低 1 つ持つ (orphan-mention 禁止、 conditional-normative)。
WHERE a spec opts into xref-completeness (folio-xref-completeness=enabled), REQ-XREF-002: every prose mention of an auto-materializable canonical object token SHALL carry at least one resolvable xref to that object (orphan-mention forbidden、 folio fix が初出を wrap して充足する)。
data-tooltip に定義 essence (plain-text、 §9.2 contract) を持つ (no-JS CSS-only tooltip)。
REQ-XREF-003: Each xref SHALL remain a working baseline link (click → definition) and SHALL carry, in data-tooltip, the plain-text essence of the object's definition per the §9.2 essence-extraction contract, rendered as a no-JS CSS-only tooltip.
REQ-XREF-004: Each canonical object ID SHALL be defined exactly once as an id-bearing SSoT element across architecture, and SHALL NOT be renumbered or reused (ID immutability)。
form scope (form-strict): xref-completeness (REQ-XREF-002、 ADR-0034 §2.5) が resolvable xref として数え、 かつ AI-graph projection (§2.7) の edge SSoT とするのは <a class="xref"> 形のみである。 §10.2 RTM の cov-req (§9.1 の cov-link = spec-row への coverage link)、 nav 用の class 無し plain <a href>、 folio-self-spec で nav に用いる normative-ref 等は意図的に xref-completeness / AI-graph projection へ参加しない別 form であり (data-tooltip も edge も担わない)、 同一 object へ解決しても orphan-mention を解消しない。 帰結として、 ある canonical token の prose 裸言及は、 同一 target への plain nav link が別に存在しても folio fix が class="xref" へ wrap する (初出のみ、 REQ-XREF-002) — class="xref" が tooltip + AI-graph edge の唯一の担体、 plain link は nav という別役割ゆえ、 両者の併存は重複 (duplicate) でなく設計どおりである。
glossary 用語 (Class B) は defined-object (Class A) の no-gaps とは別の best-effort tier で、 SSoT は vocabulary.yaml の definition、 HTML glossary view はそこからの生成 projection とし定義を二重化しない (P-7)。
glossary 用語 (Class B) は defined-object (Class A) の no-gaps とは別の best-effort tier である (自然語の全 occurrence 検出は NLP 難問ゆえ term 完全性は約束しない、 ADR-0034 §2.8)。 用語の SSoT は vocabulary.yaml の definition field (§3 schema、 ISO 704 concept model: canonical = 主 designation / definition = concept 定義)。 HTML 上の glossary view は vocabulary.yaml からの生成 projection とし、 定義を二重化しない (P-7)。
domain: consumer 用語 (folio 解説不能) と任意の手動 mark は <span class="term" data-term="<canonical>">表示語</span> で明示する (REQ-GLOSS-001)。domain: folio-closed 用語は、 opt-in した doc (<meta name="folio-glossary-automark" content="enabled">) で folio fix が doc 初出を <span class="term"> に自動 mark する (hover tooltip のみ・glossary.html へはリンクしない、 REQ-GLOSS-002)。 いずれの方式も auto-detect で全言及を gap-lint することはしない (best-effort tier、 自然語の全 occurrence 検出は NLP 難問ゆえ doc 初出のみ・完全性は約束しない)。 consumer-domain 用語への auto-mark 越権はしない。folio fix が marked term の data-tooltip を vocabulary.yaml の definition から materialize する (定義は vocabulary.yaml に SSoT、 HTML へ重複させない)。 Class A xref と同じ no-JS CSS tooltip 機構 (§9.3) を dogfood して共用する。data-term → canonical) と consistency (data-tooltip → definition) は folio validate の glossary gate が block enforce する (§9.4 と同じく本節は marking 規約 = WHAT を定め、 gate 挙動の正本は verification REQ-VER-019 に一元化)。 best-effort tier ゆえ未 mark の言及は gap-lint しない。span.term[data-term] で表す MUST。 data-term は vocabulary.yaml canonical に解決、 data-tooltip はその escape 済 definition と一致。 Class B で未 mark は gap-lint せず。
WHERE a glossary term is given a hover tooltip by explicit (manual) marking — not by folio fix auto-marking, which is governed by REQ-GLOSS-002, REQ-GLOSS-001: the term SHALL be explicitly marked as <span class="term" data-term="<canonical>"> whose data-term resolves to a canonical entry in vocabulary.yaml and whose data-tooltip holds that entry's definition rendered as an HTML-attribute-escaped value (the canonical escaping of & / < / > / ", applied identically by folio fix on write and folio validate on check); unmarked term mentions SHALL NOT be gap-linted (Class B best-effort tier、 ADR-0034 §2.8)。
span.term に auto-mark (hover のみ・非リンク)。 code/見出し/summary/chrome/既 mark skip、 consumer 用語は対象外、 no-gaps 非保証。
WHERE a living spec or research document opts into glossary auto-marking via <meta name="folio-glossary-automark" content="enabled">, REQ-GLOSS-002: folio fix SHALL best-effort auto-mark the document-first prose occurrence of each domain: folio-closed canonical term as <span class="term" data-term="<canonical>" data-tooltip="<definition>"> — a no-JS hover-only mark that carries the tooltip and does not link to glossary.html — while skipping occurrences inside code / <pre> / machine-readable aside / headings (h1–h6) / the doc summary line (div.meta — folio inventory の summary 抽出 SSoT で、 mark は抽出を切断する) / chrome marker regions (folio:chrome-* — build 所有領域、 mark は再 build で drift する) and terms already marked; it SHALL NOT auto-mark domain: consumer terms nor guarantee no-gaps completeness of all occurrences (Class B best-effort tier extending REQ-GLOSS-001, ADR-0036 §2.3/§2.4)。 conformance は scenarios/glossary-automark.yaml (opt-in fixture に folio fix が doc 初出のみ span 化 + idempotent + code/見出し/既 mark skip を seed)。
dt id は canonical を slug 化した #term-<slug>。 slug は決定的 (lowercase / 非英数連→hyphen / LC_ALL=C)・非空・一意 な MUST。 衝突は fail-closed。 prose の a.term は anchor-residue として block。
WHEN folio build or folio validate resolves a vocabulary.yaml with domain: folio-closed definitions, REQ-GLOSS-003: the folio CLI SHALL give each canonical term a <dt id="term-<slug>"> whose slug is deterministic (lowercased, non-alphanumeric runs collapsed to one hyphen, edge hyphens trimmed, computed under LC_ALL=C), non-empty (an all-non-ASCII or all-symbol canonical falling back to a deterministic x<cksum>), and unique within the page; on a slug collision (two distinct canonicals mapping to one slug) it SHALL fail closed — folio build not writing glossary.html (exit 2) and folio validate blocking with [glossary-slug] — independently of whether a generated glossary.html is present。 Separately — and independently of any vocabulary.yaml resolution (this is a marking-form invariant, not a derive obligation) — the glossary gate SHALL block any <a class="term"> found in living spec/research prose as anchor residue ([glossary-anchor-residue], detect-only) since glossary term marks are span-only (hover-only、 ADR-0036 §2.4)。 conformance は scenarios/glossary-slug-collision.yaml + scenarios/glossary-residue.yaml (slug 衝突 / anchor 残滓 を seed した fixture に folio validate が exit 1)。
本 §10 は Layer 1 consumer が無条件遵守すべき動的な操作上の MUST 義務 (§2〜§6 の構造規則とは別) を 1 箇所に集約する。 enforcement 機構と binding 詳細は folio-self-spec.html §7 / §9 に分離する。
本 §10 は Layer 1 consumer project が folio rules を consume する際に 無条件に遵守すべき MUST 要件を 1 箇所に集約する。 §2〜§6 の markup / naming rules が「構造上の規則」 であるのに対し、 §10 は「動的な操作上の義務」 を規定する。 各 MUST の enforcement mechanism (hook flow / script 実装) は folio-self-spec.html §7 を参照。
spec_path 配下の file への AI agent の write を caller marker env var で gate する RFC 2119 MUST を定める。 env var 名・値・hook flow は folio-self-spec.html §7.3 / §9 に集約する。
spec_path 配下の file に write を試みる時、 system は caller marker env var が宣言値に set されているか検証する MUST。
REQ-CM-001:
WHEN AI agent attempts to write to any file under spec_path,
the system SHALL verify that the caller marker
environment variable is set to the declared value.
folio.config.yaml で宣言) を set し、 完了後即 unset する MUST。
REQ-CM-002:
The AI agent SHALL set the caller marker env var
(declared in folio.config.yaml) before invoking any spec Edit/Write tool call,
and SHALL unset it immediately upon completion.
permissionDecision: deny を返す MUST。
REQ-CM-003:
IF the caller marker env var is absent or holds an unexpected value,
THEN the PreToolUse hook SHALL return
permissionDecision: deny.
env var の具体名・値は folio.config.yaml で declare し、 binding 詳細は folio-self-spec.html §9 Bindings に集約する。
flowchart TB accTitle: §10.2 7 gate の二層 enforcement accDescr: REQ-CI-010〜016 の 7 gate を ADR-0028 の二層に振り分ける。 deterministic floor は folio validate が CI で block/warn し、 LLM ceiling は Phase F review agent が authoring 時に担保する (CI hard gate にしない)。 G["§10.2 7 gate (REQ-CI-010〜016)"] G --> F["deterministic floor — folio validate (CI block/warn)"] G --> C["LLM ceiling — Phase F review (authoring advisory)"] F --> F1["link-integrity / json-ld (block)"] F --> F2["vocabulary / delta-marker (block)"] F --> F3["EARS-coverage (warn)"] C --> C1["declarative-form (spec-review-temporal)"] C --> C2["what-only (spec-review-ssot)"]
merge 前に enforce すべき 7 gate (REQ-CI-010〜016) を ADR-0028 二層 (floor / ceiling) に振り分ける。 振り分けの全容は下図と表が示す。
REQ-CI-001: The Layer 1 consumer CI workflow SHALL enforce all seven gates defined below before permitting merge.
REQ-CI-002 〜 REQ-CI-009 は将来拡張のため予約 (例: 新規 gate 追加 / sub-requirement)。 現状の 7 gate は REQ-CI-010 〜 REQ-CI-016 を採用。
| REQ-ID | gate | 結果 | 根拠 |
|---|---|---|---|
| REQ-CI-010 | link-integrity gate | fail = merge block | P-6 |
| REQ-CI-011 | declarative-form gate | fail = merge block | P-4 |
| REQ-CI-012 | what-only gate | fail = merge block | P-3 / P-11 |
| REQ-CI-013 | vocabulary gate | fail = merge block | P-5 |
| REQ-CI-014 | EARS coverage gate | warn (merge 許可) | §6 |
| REQ-CI-015 | delta marker consistency gate | fail = merge block | §5 |
| REQ-CI-016 | json-ld-validation gate | fail = merge block | relations §3 |
REQ-CI-010: IF the link-integrity gate finds a broken reference (external URL, anchor fragment, or internal file-system reference), THEN the Layer 1 consumer CI workflow SHALL block the merge (P-6).
REQ-CI-011: IF the declarative-form gate finds a non-declarative construct, THEN the Layer 1 consumer CI workflow SHALL block the merge (P-4).
REQ-CI-012: IF the what-only gate finds WHY or HOW content in a WHAT spec, THEN the Layer 1 consumer CI workflow SHALL block the merge (P-3 / P-11).
REQ-CI-013: IF the vocabulary gate finds a forbidden synonym for a canonical term, THEN the Layer 1 consumer CI workflow SHALL block the merge (P-5).
REQ-CI-014: IF the EARS-coverage gate finds a requirement lacking a well-formed EARS pattern, THEN the Layer 1 consumer CI workflow SHALL emit a warning while still permitting the merge (§6).
REQ-CI-015: IF the delta-marker consistency gate finds an unresolved or malformed delta marker, THEN the Layer 1 consumer CI workflow SHALL block the merge (§5).
<head> JSON-LD block が relations §3 schema に適合するか検証する MUST。
REQ-CI-016:
The Layer 1 consumer CI workflow SHALL
verify that every spec file's <head> JSON-LD block
conforms to the schema defined in relations.html §3.
Detailed assertion strategy (exit code + stderr 中心、 permissionDecision: deny
JSON は SHOULD NOT 使用) は verification.html §3 REQ-VER-003
を参照。
決定が (a) 不可逆 (b) rationale 無しでは意外 (c) 代替間の真の trade-off の 3 条件すべてを満たす時のみ folio-architect が ADR 起票を offer (sparingly)。 1 つでも偽なら spec 本文や vocabulary.yaml に吸収。 承認は decisions/README §5。
folio-architect は ADR として記録するよう offer する MUST。
REQ-ADR-001:
WHEN a design decision surfaced during authoring is simultaneously (a) hard to reverse, (b) surprising without its rationale, and (c) a genuine trade-off between viable alternatives,
folio-architect SHALL offer to record it as an ADR in architecture/decisions/ (起票自体は decisions/README §5 の user 承認に従う)。
3 条件がすべて真の時のみ ADR を offer する (sparingly)。 いずれか 1 つでも偽なら ADR にしない — 可逆な決定 / context 無しで自明な決定 / trade-off の無い決定は spec 本文 (WHAT) や vocabulary.yaml に吸収し、 重厚な ADR (HTML+JSON-LD、 user 承認) を濫造しない。 folio の高コスト ADR と高い 3 条件 bar は相互補強する (少数精鋭に絞る価値が高い)。
本章は P-14 (Human Readability) を実装する presentation 規律 — 人間読者層 (§11.1)・表示層 remediate の build/fix 分業 (§11.2)・既定表示 (§11.3)・検査手続き (§11.4)・圧縮 (§11.5) を定める。 生成 SRS の design system は §12。
ページ種別ごとの主たる人間読者層と提示の力点を下表で定義する (P-14 委任の履行)。 提示判断 (見せる / 折る / 削る) はこの読者層定義を物差しとする。
| ページ種別 | 主たる人間読者層 | 提示の力点 |
|---|---|---|
入口層 — landing (index.html) / cluster README.html | folio を知らない初見の外部開発者 | hero 一文 + 読者別導線 + dead-end ゼロ (landing template、 ADR-0039 §2.2)。 専門用語は xref / glossary hover で即解決 |
spec 本文層 — architecture/spec/*.html | folio を導入済みで仕様を参照・検索する既習 consumer 開発者 | essence・表・図が常時可視、 EARS 全文は fold (§7 dual-audience)。 ページ内目次 + prev-next で検索性 |
decisions 層 — architecture/decisions/*.html | 設計経緯を時系列で辿る維持者 | ADR 番号順の prev-next chain (決定的順序)。 frozen 本文は不変、 chrome のみ build が維持 |
glossary — architecture/glossary.html | 初見〜既習の横断参照 | vocabulary.yaml 由来の生成 view。 本文からは hover tooltip (§9.5) で遷移なし参照 |
表示層 regen は folio build が一元所有、 folio fix は graph materialize 専任。 validate の violation message は対応する remediate tool を名指しする MUST。
表示層の regen は folio build が一元所有する MUST — index (landing) / glossary / 全ページ chrome の生成・維持 (「nav-regen-drift 系の violation は build で直す」)。 folio fix は graph の materialize 専任 — reverse-link (REQ-REL-002) / xref wrap (§9.4) / tooltip 再生成。 folio validate の violation message は対応する remediate tool を名指しする MUST (どの違反をどちらで直すかの迷いを消す、 ADR-0039 §2.9 = folio-dd0 の解消)。 readability-floor (REQ-VER-023) のうち landing 系は build が remediate し、 viewport / essence は authoring の責務 (機械 regen の対象外)。
no-JS では class 無しで全文可視へ graceful degrade (AI・検索・印刷は不変)。 fold ネスト 2 段上限・<summary> 要旨 1 文・印刷時全展開は MUST。 生成 SRS プレゼンの既定表示は §12 が定める。
ページ種別ごとの既定表示 (初見で何が見えるか) を次のとおり定める。 適用対象は living spec・生成物・新規 ADR template — frozen 文書の本文は不変 (折り畳み化は本文改変のため適用しない):
data-audience="machine" へ降格された informative 地の文は既定で非表示 — audience toggle で全文へ 1 操作。 no-JS 環境は全文可視へ graceful degrade (§11.5)。<summary> には要旨 1 文 MUST (空 summary・「詳細」のみの summary を禁止)。 この 2 つは現状機械 gate を持たない — authoring 規律 + Phase F review (ceiling) が担い、 違反頻度を見て floor 化を判断する (ADR-0039 §2.7 の warn→block と同じ昇格規律)。beforeprint で閉じた <details> を一時 open し afterprint で復元する (author CSS では closed details の中身を描画できないため script が担う、 §8 read-only enhancement)。audience toggle (ADR-0039 §2.5): chrome の inline script が、 data-audience 要素を持つ page にのみ「両方 / 人間向け / 機械向け」の 3 状態 toggle を生成する (no-JS では UI 自体が存在しない = progressive enhancement)。 初期状態は「人間向け」 — script が toggle 生成と同時に body class audience-human を付与する (既定 = 人間プレゼン型、 ADR-0040。 script 経由ゆえ no-JS では class が付かず全文可視 = graceful degrade。 static HTML / DOM は全文を保持し続けるため AI・検索・印刷への影響はない)。 実装は body class 切替のみ (audience-human = machine 精密部を隠す / audience-machine = human 派生 view を減光)・DOM 構造不変・永続なし (状態はページ内のみ)。 連続閲覧の煩わしさが実機 walk で実証されたら localStorage 昇格 (graceful degradation 付き) する片道を注記する。 closed <details> の中身は UA の rendering skip ゆえ author CSS では開けない — 開閉は読者操作に委ねる (toggle の設計境界)。
flowchart TB
accTitle: §11.4 readability 検査の三層
accDescr: 「読める」の検査は三層で行う。 下層は機械 (deterministic) で readability floor (REQ-VER-023) と render-gate ceiling (REQ-VER-022) が幾何を検査する。 幾何が clean でも読みにくい page はあるため、 その上層に readability review lens (常設 MUST、 LLM persona review) を置き、 最上層に user 実機 walk (MUST、 人間の目視) を最終検査器として置く。 上層 2 手続きは presentation 変更時の必須 step。
subgraph L1["下層 = 機械 (deterministic、 CI gate)"]
floor["readability floor
REQ-VER-023"]
ceiling["render-gate ceiling
REQ-VER-022 (幾何 detector)"]
end
L1 --> lens["readability review lens
(常設 MUST・LLM persona review)"]
lens --> walk["user 実機 walk
(MUST・最終検査器 = 人間)"]
「読める」検査は三層 (機械 floor + render-gate / readability lens / user 実機 walk)。 上層 2 手続き (lens + walk) は presentation 変更時の必須 step。 非決定的ゆえ機械 gate なし (Phase F / 独立 ceiling review が担保)。
「読める」の検査は三層で行う。 下層 = 機械 (deterministic): readability floor (REQ-VER-023) + render-gate ceiling (REQ-VER-022、 幾何 detector 6 class × 3 viewport + screenshot artifact)。 幾何が clean でも読みにくい page はある — その上層 2 手続きを presentation 変更時の必須 step と定める (適用 trigger = ページ追加 / template・chrome・common.css の変更 / spec-row 等の表示構造変更):
agents/readability-walk.md (spawn して使う。 本討論の監査 lens の常設化、 ADR-0039 §2.8)。この 2 手続きは LLM review + 人間の目視ゆえ非決定的で、 機械 gate (CI) を持たない (ADR-0028 §2.3 の LLM-ceiling 非搭載と同根拠)。 実施は authoring 規律 + Phase F / 独立 ceiling review が担保し、 違反 (lens/walk を踏まない presentation 変更の ship) を review が指摘する — §11.3 の fold 規律と同じ昇格規律 (違反頻度を見て floor 化を判断) に従う。
人間層 = 制限時間付きプレゼン / 機械層 = 無制限の原稿。 各章に章要旨 MUST・地の文は machine へ降格 (削除しない MUST)・可視 prose は約 12,000 字を time-box 上限とする。 生成 SRS プレゼンの圧縮は §12 が改訂・置換する。
人間層 (既定表示で可視の内容) は制限時間付きプレゼン、 機械層は無制限の原稿とする (ADR-0040)。 本節が圧縮基準 (folio 自身の living spec 対象) の単一 SSoT であり、 migration 道具と folio-architect の presentation pass の双方がここを参照する — 道具側に基準を複製しない。 適用範囲の改訂: 生成 SRS プレゼン (consumer が機械 SSoT から生成する要件定義書) には本節の長さ基準でなく §12 の design system 生成 + floor 刷新 (visual-first) が適用される (ADR-0041 §2.5 / ADR-0042 が ADR-0040 を改訂)。 folio 自身の living spec (本 rules を含む) の人間層は ADR-0041 適用範囲の拡張パックが後追いするまで本節の規律下に留まる。
<p class="section-essence" data-audience="human"> で 1〜3 文の要旨を置く MUST (living spec の圧縮対象ページ)。 短小規約章 (単文 MUST のみの h3 等) は、 親章の essence がその核 MUST を運ぶ場合に限り省略してよい — floor の presence 検査は v1 page 単位ゆえ章単位の gap は ceiling (Phase F fidelity / readability lens) が拾う。 章要旨は当該章の降格 prose の正確な要約であり、 REQ essence (requirement 単位、 §7.2) とは粒度の異なる入れ子 — fidelity (章要旨 ↔ 地の文) は Phase F review が検査する。data-audience="machine" の明示付与、 複数段落は wrapper <div> 可): informative 地の文・運用注記・歴史的経緯。 aside.machine-readable は降格対象外 — aria-hidden 付き metadata block として既に別機構で機械専用であり、 data-audience を重ねない (2 機構を混同しない)。 mermaid 図 (<pre class="mermaid">) は人間層に置き降格しない — render-gate の図数照合は static な block 数を期待するため、 machine 降格 (display:none) は render 不足 false-fail を生む。 削除は禁止 MUST — 圧縮は降格であり、 AI は CSS 表示状態に依存せず DOM 全文を読むため情報はゼロ損失。@type=FolioConstitution として floor scan 対象外 (既存 carve-out)。要件定義書 (SRS) の人間プレゼンを機械 SSoT から生成し 2-gate (floor ∧ ceiling) で検証する regime。 規律を普遍コア (core) と SRS 固有パック (srs-pack) に分ける。
data-doc-scope による engine / pack 標識: 本章が導入する規律は data-doc-scope 属性で標識する。 値は closed 2 値 (core | srs-pack)、 canonical (synonym は P-5 禁止、 data-audience と直交する別 taxonomy — 本値 core は §7.1 の data-audience を指す「closed 2 値 core」とは別 entity の標識値)。 core = doc-type 非依存の普遍メタ規律 (エンジンコア候補)、 srs-pack = SRS 核 (γ) 固有の規律・部品 (SRS 核の外を後追いする「拡張パック」とは別概念 — 前者は核内、 後者は核外)。 grep data-doc-scope="core" は普遍コア抽出の地図であり、 core 規律の普遍化が要る doc-type が現れた際 (rule of three) の抽出単位を標識する。 既存 §1〜§11 は本属性を持たない。
エンジンコア規律 (普遍メタ、 doc-type 非依存):
data-component 付きで組立てる。 RTM / トレースの各セルはトレースデータから決定的に導出するため、 元に無い行・列・リンクの捏造は構成上不可能になる (fabrication-free-by-construction)。 高能力モデルは assembler が空で残した prose スロットのみ充填する (章リード / 「なぜ要る」根拠 / 専門語のやさしい併記 / 1 文サマリ)。 構造は SSoT から毎回決定的に再組立し、 構造に差分編集を介在させない (更新は prose 層でのみ差分再生成する)。file:// 動作、 §8 JS governance / P-13 と整合)。folio verify-srs が floor 通過時に CEILING=PENDING を返す機械担保を含む)。 本章は WHAT 規律を定め、 gate を個別列挙しない (P-7、 gate 詳細は verification に集約)。SRS doc-type パック規律 (29148 接地・SRS 固有):
design system は再利用可能な部品庫で、 dual-audience の境界が部品単位へ降りる (各部品が機械精密スロットと設計された人間の顔を持つ)。 SRS 核 (γ scope) は ISO/IEC/IEEE 29148 で完全性を錨留めし、 部品 taxonomy の設計 SSoT は srs-component-taxonomy.html (37 部品の register 分類)、 部品庫の HOW 実装は design-system catalog が持つ (folio 自身の ADR / research / 原則は拡張パックで後追い)。
密系部品の非エンジニア可読化は assembler が 3 戦略に振り分けて構造的に保証する (ADR-0042 §2.2)。 高密度は fidelity の背骨として全 DOM 保持・展開可のまま残し、 主役の配置のみを変える:
| 戦略 | 対象 (判定根拠) | assembler が必ず生成する affordance |
|---|---|---|
| B = 畳む | rtm-grid register 全体 (トレース監査の道具、 register-pure ゆえ機械判定) | 人間ビューで既定折りたたみ + 直前に空不可の平易要約スロット。 全グリッドは保持し AI / 印刷で展開 (情報は畳むだけで欠落しない)。 |
| A = 噛み砕く | 要件本体・NFR の明示 allowlist (register をまたぐ部品 id 集合) | 各行に空不可の plain-language スロット (やさしい言い換え) + 専門語の inline 併記。 文書の本体ゆえ畳まない。 |
| 据置 | 元々平易な部品 (用語表・参照一覧・改訂履歴 等) の明示集合 | 既存のまま、 軽い注釈のみ (plain スロットは SHOULD)。 |
plain-language-term-inline) は用語定義表 (glossary-term-table) の派生ビューであり、 両者の定義一致を fidelity が検証する (double-SSoT 回避、 §9.5 glossary 機構と整合・用語定義 SSoT は vocabulary.yaml)。