Requirements
| ID | Requirement |
|---|---|
| FONT-1 | The published subset SHALL cover every codepoint appearing in the wiki, and a codepoint with no glyph SHALL fail the check rather than fall back silently. |
| FONT-2 | Coverage SHALL be measured over rendered text only, excluding fenced code blocks, which are set in the monospace face, and excluding control characters, which are layout rather than glyphs. |
| FONT-3 | The subset SHALL always include the printable ASCII range and CJK punctuation, whether or not the current content uses them. |
| IDX-1 | Index synchronization SHALL preserve every existing entry line, section heading and ordering byte-for-byte unless the entry's page moved folder or ceased to exist. |
| IDX-2 | A page present on disk but absent from the index SHALL be appended to its folder's section with the summary placeholder （待補摘要）. |
| IDX-3 | An index entry whose page no longer exists on disk SHALL be removed. |
| IDX-4 | An index entry whose page changed folder SHALL move to the section for the new folder, carrying its authored summary unchanged. |
| IDX-5 | Sections SHALL be mapped to folders by inferring each section's folder from where its currently listed pages live, never by assuming the heading equals the folder name. |
| IDX-6 | In check mode the command SHALL write nothing and exit 1 when the index has drifted from disk. |
| IDX-7 | Structural and generated pages SHALL never appear as index entries, namely index.md, log.md and anything under specs. |
| OWN-1 | The guard SHALL deny any edit that changes a single byte of the body of a page whose frontmatter says human, including whitespace and typo corrections. |
| OWN-2 | On a page authored by a human with llm_section_authorized set true, the guard SHALL permit changes strictly between the <!-- llm:begin --> and <!-- llm:end --> markers and deny changes outside them. |
| OWN-3 | The guard SHALL fail closed, denying the edit, whenever it cannot prove the edit safe — missing frontmatter, an unrecognized author value, or an internal error. |
| OWN-4 | An authorization upgrade of llm_section_authorized from false to true SHALL be permitted only as an edit that changes nothing else. |
| OWN-5 | The guard SHALL treat index.md, log.md and every page under docs/specs as fully LLM-owned, requiring no frontmatter. |
| PROMPT-1 | A ::: prompt container SHALL render as an element carrying the class llm-prompt, so the design system can style it without touching prose rules. |
| PROMPT-2 | The container SHALL use the title given after the fence, falling back to LLM Prompt when none is written. |
| PROMPT-3 | Markdown inside the container SHALL be rendered as Markdown, including fenced code blocks. |
| WIKI-1 | The Markdown pipeline SHALL resolve a wikilink to a root-absolute href ending in .md, so VitePress normalizes it and records it for dead-link detection. |
| WIKI-2 | A wikilink SHALL carry a trailing #section through to the emitted href as a fragment. |
| WIKI-3 | A wikilink of the form [[Target|alias]] SHALL link to Target while displaying alias. |
| WIKI-4 | Wikilink targets SHALL resolve against page filenames case-insensitively, ignoring the folder the page lives in. |
| WIKI-5 | The pipeline SHALL NOT transform wikilink syntax appearing inside inline code spans or fenced code blocks. |
| WIKI-6 | A wikilink whose target matches no page SHALL still emit a link, so the production build fails on it rather than publishing a broken reference. |
| WIKI-7 | The resolution table SHALL be read at render time, so a page created while the dev server runs resolves without restarting it. |
| ZEN-1 | The page ground SHALL be 呂 at #0C0C0C and body text 白練 at #FCFAF2, and neither SHALL be restated anywhere the design can drift from. |
| ZEN-2 | Every colour the theme defines SHALL be a member of the declared 日本の伝統色 palette at that colour’s published value, across each of docs/.vitepress/theme/dark-zen.css, src/theme/dark-zen-shiki.ts, uno.config.ts. |
| ZEN-3 | Code block highlighting SHALL be coloured from that same palette rather than by a bundled vendor theme. |
| ZEN-4 | Uniformly indented fenced code SHALL be dedented when rendered, leaving the Markdown source byte-for-byte unchanged. |
FONT-1
The published subset SHALL cover every codepoint appearing in the wiki, and a codepoint with no glyph SHALL fail the check rather than fall back silently.
Why: A silent fallback mixes two typefaces inside one sentence, which is both the most likely subsetting failure and the hardest to notice.
FONT-2
Coverage SHALL be measured over rendered text only, excluding fenced code blocks, which are set in the monospace face, and excluding control characters, which are layout rather than glyphs.
Why: Code is not set in GenWanMin, and a tab or a line ending is not set in any face, so demanding glyphs for either inflates the subset with characters no reader ever sees — and in the case of a carriage return, demands one no rebuild can supply.
FONT-3
The subset SHALL always include the printable ASCII range and CJK punctuation, whether or not the current content uses them.
Why: These are what the next sentence written will be made of; excluding them makes the check fail on ordinary typing rather than on a real gap.
| Param | Value |
|---|---|
asciiStart | 32 |
asciiEnd | 126 |
IDX-1
Index synchronization SHALL preserve every existing entry line, section heading and ordering byte-for-byte unless the entry's page moved folder or ceased to exist.
Why: Summaries and ordering are editorial judgment no script can reproduce; rewriting them silently destroys authored work.
IDX-2
A page present on disk but absent from the index SHALL be appended to its folder's section with the summary placeholder （待補摘要）.
Why: The placeholder is greppable on purpose: it is the queue of summaries an agent or the user still owes.
| Param | Value |
|---|---|
placeholder | （待補摘要） |
separator | — |
IDX-3
An index entry whose page no longer exists on disk SHALL be removed.
Why: A dangling entry becomes a dead wikilink, which under WIKI-6 breaks the build.
IDX-4
An index entry whose page changed folder SHALL move to the section for the new folder, carrying its authored summary unchanged.
Why: Reorganizing the vault in Obsidian must not cost the summaries already written.
IDX-5
Sections SHALL be mapped to folders by inferring each section's folder from where its currently listed pages live, never by assuming the heading equals the folder name.
Why: The vault already relies on this: ### .NET holds the pages in docs/NET/.
IDX-6
In check mode the command SHALL write nothing and exit 1 when the index has drifted from disk.
Why: This is the CI gate; a checker that writes is not a checker.
| Param | Value |
|---|---|
driftExitCode | 1 |
IDX-7
Structural and generated pages SHALL never appear as index entries, namely index.md, log.md and anything under specs.
Why: index.md and log.md are the structure itself; docs/specs is regenerated by attest render and owned by the registry.
| Param | Value |
|---|---|
reserved | index.md, log.md |
generatedDir | specs |
OWN-1
The guard SHALL deny any edit that changes a single byte of the body of a page whose frontmatter says human, including whitespace and typo corrections.
Why: Handwritten notes carry the uncertainty, the open questions and the later-overturned judgments of the moment they were written; editing flattens those signals away.
| Param | Value |
|---|---|
humanAuthor | human |
OWN-2
On a page authored by a human with llm_section_authorized set true, the guard SHALL permit changes strictly between the <!-- llm:begin --> and <!-- llm:end --> markers and deny changes outside them.
Why: The hybrid page is the negotiated middle ground: relations and sources without touching prose.
| Param | Value |
|---|---|
authorizedField | llm_section_authorized |
beginMarker | <!-- llm:begin --> |
endMarker | <!-- llm:end --> |
OWN-3
The guard SHALL fail closed, denying the edit, whenever it cannot prove the edit safe — missing frontmatter, an unrecognized author value, or an internal error.
Why: A guard that opens on its own failure protects nothing precisely when something is already wrong.
OWN-4
An authorization upgrade of llm_section_authorized from false to true SHALL be permitted only as an edit that changes nothing else.
Why: Bundling the upgrade with the body change it authorizes would let one edit grant itself permission.
| Param | Value |
|---|---|
authorizedField | llm_section_authorized |
OWN-5
The guard SHALL treat index.md, log.md and every page under docs/specs as fully LLM-owned, requiring no frontmatter.
Why: These files are generated or structural; attest render output in particular is byte-compared by its own freshness gate and cannot carry added frontmatter.
| Param | Value |
|---|---|
structural | index.md, log.md |
generatedDir | docs/specs |
PROMPT-1
A ::: prompt container SHALL render as an element carrying the class llm-prompt, so the design system can style it without touching prose rules.
Why: Styling by a single class keeps the block one thing to restyle, rather than a pattern re-derived per page.
| Param | Value |
|---|---|
containerClass | llm-prompt |
PROMPT-2
The container SHALL use the title given after the fence, falling back to LLM Prompt when none is written.
Why: Most prompts want a name; the ones that do not should not have to invent one.
| Param | Value |
|---|---|
defaultTitle | LLM Prompt |
PROMPT-3
Markdown inside the container SHALL be rendered as Markdown, including fenced code blocks.
Why: Prompts are mostly code fences and lists; a container that renders them as plain text would be useless for the one thing it exists for.
WIKI-1
The Markdown pipeline SHALL resolve a wikilink to a root-absolute href ending in .md, so VitePress normalizes it and records it for dead-link detection.
Why: Emitting the source path rather than a finished URL hands cleanUrls, base and dead-link checking to VitePress instead of duplicating them.
| Param | Value |
|---|---|
sourceExtension | .md |
WIKI-2
A wikilink SHALL carry a trailing #section through to the emitted href as a fragment.
Why: Obsidian section links are common in this vault and must survive the build.
WIKI-3
A wikilink of the form [[Target|alias]] SHALL link to Target while displaying alias.
Why: Aliases are how prose keeps a link readable inside a Chinese sentence.
WIKI-4
Wikilink targets SHALL resolve against page filenames case-insensitively, ignoring the folder the page lives in.
Why: Obsidian resolves by note name, not path; the vault is authored in Obsidian first and built second.
WIKI-5
The pipeline SHALL NOT transform wikilink syntax appearing inside inline code spans or fenced code blocks.
Why: This wiki documents its own link syntax. The regex-based MkDocs hook this replaces could not make that distinction.
WIKI-6
A wikilink whose target matches no page SHALL still emit a link, so the production build fails on it rather than publishing a broken reference.
Why: Preserves the mkdocs build --strict property: a broken link stops the deploy instead of shipping.
WIKI-7
The resolution table SHALL be read at render time, so a page created while the dev server runs resolves without restarting it.
Why: The vault is edited in Obsidian while the site is open; a table captured at config load would make every new note a broken link until restart.
ZEN-1
The page ground SHALL be 呂 at #0C0C0C and body text 白練 at #FCFAF2, and neither SHALL be restated anywhere the design can drift from.
Why: These two are the only colours the brief fixes; everything else is free, so they are the pair a redesign is most likely to nudge without anyone noticing.
| Param | Value |
|---|---|
ground | #0C0C0C |
text | #FCFAF2 |
ZEN-2
Every colour the theme defines SHALL be a member of the declared 日本の伝統色 palette at that colour’s published value, across each of docs/.vitepress/theme/dark-zen.css, src/theme/dark-zen-shiki.ts, uno.config.ts.
Why: Three of the six tokens already carried invented hexes under traditional names, which is the failure a palette stated in prose cannot catch and a checked one can.
| Param | Value |
|---|---|
surfaces | docs/.vitepress/theme/dark-zen.css, src/theme/dark-zen-shiki.ts, uno.config.ts |
ZEN-3
Code block highlighting SHALL be coloured from that same palette rather than by a bundled vendor theme.
Why: A vendor theme is a second palette shipped inside the first, and it is the one place on the page where colours the design never chose can appear.
ZEN-4
Uniformly indented fenced code SHALL be dedented when rendered, leaving the Markdown source byte-for-byte unchanged.
Why: The indentation is an Obsidian editing artefact in pages whose bodies are human-owned and may not be edited, so the only place it can be removed is the renderer.