2 +name: system-documents
3 +description: Apply The System HTML, metadata, ID, reference, mockup, validation, and browser-review contracts
8 +This is the single document-authoring authority for `.system` authored documents.
9 +Other lifecycle skills must delegate these rules instead of copying or weakening them.
13 +- Discover the project root from the nearest `.jj` and `.git` markers; stop when they disagree.
14 +- Read `.system/config.json`; require its approved prefix and current schema/style versions.
15 +- Resolve every target below the project root and reject traversal.
16 +- Inspect existing filenames and metadata before allocating an ID.
20 +Use `<PREFIX>-(SPEC|ROADMAP|PLAN|ISSUE|RESEARCH)-<SEQUENCE>`.
21 +Start sequence text at three digits, permit growth past 999, and use the next unused value for that type.
22 +Use lowercase ASCII slugs matching `[a-z0-9]+(?:-[a-z0-9]+)*`.
23 +Write `<ID>-<slug>.html` only in its matching `.system/specs|roadmaps|plans|issues|research` directory.
27 +Every authored document is complete, formatted, directly editable HTML with:
29 +- `<!doctype html>`, `<html lang="en">`, UTF-8 charset, viewport, and a nonempty title;
30 +- exactly one `<link rel="stylesheet" href="../system.css">`;
31 +- header followed by main containing one section;
32 +- semantic headings, paragraphs, lists, tables, asides, figures, and details where appropriate;
33 +- one readable `<script type="application/json" id="system-meta">` block.
35 +Inline CSS may express document-specific layout but may not redefine shared Nugu colors, typography, breakpoints, or components.
36 +Inline JavaScript must be optional, dependency-free progressive disclosure, filtering, or a tiny explanation.
37 +Forbid network APIs, browser storage, dynamic import, external scripts, event-handler attributes, executable URL schemes, iframes, objects, embeds, meta refresh, remote runtime assets, generated SVG sludge, and diagram libraries.
38 +HTTPS anchors remain allowed navigation.
40 +##
Metadata and graph 42 +Metadata is the reference authority; prose links never create graph edges.
45 +- spec: `id`, `type`;
46 +- roadmap: `id`, `type`, one `spec`;
47 +- plan: `id`, `type`, one `spec`, plus `roadmap` and positive `phase` together when phase-scoped;
48 +- issue: `id`, `type`, `open|fixed` status, unique `specs` array;
49 +- research: `id`, `type`, ISO `capturedAt`, optional unique HTTPS `sources`.
51 +Specs are leaf truth and have no outgoing system-document metadata.
52 +Roadmaps point to one spec.
53 +Plans point to one spec and optionally one phase of a roadmap for that same spec.
54 +Issues point only to specs; an empty array is allowed while the violated contract is unknown.
55 +Tests use a language-appropriate `SYSTEM-SPEC: <SPEC-ID>` comment.
57 +##
Spec-owned mockups 59 +Persist only a human-accepted spec-owned mockup.
60 +Place it beside its owner as `<spec-stem>-mockup-<option-slug>.html` and link it relatively from the spec.
61 +A mockup is a constituent asset, not an authored graph node: do not add `system-meta`.
62 +Keep it standalone, editable, dependency-free, and subject to the same active-resource prohibitions.
64 +##
Validate and review 66 +After writing or materially editing a document, run the bundled `../../scripts/doctor.mjs` through Node with `--experimental-strip-types`.
67 +Do not hide, reorder, or silently repair findings.
68 +Print the exact source path and ask whether browser review is wanted.
69 +Never open a browser or editor automatically.
70 +Only use an explicitly approved, shell-free local-file opener when one is available; otherwise leave the source path as the review interface.