pasika 0.3.1 → 0.3.3

package/README.md

@@ -16,9 +16,9 @@ docs/
 enforcement/
   registry.json                   # requirement → enforcement, keyed by content hash
   coverage.ts                     # reconciles the docs against the registry
-  docs-check.ts                   # the documentation guide, mechanically
 eslint/
   pasika/rules/                   # the lint rules, with fixture tests beside them
+  pasika/rules/md/                # the documentation-guide rules, linting docs/ itself
 cli/
   index.ts                        # the `pasika` command
 ```
@@ -42,13 +42,12 @@ Requirements are identified by a hash of their canonical text, not by a hand-wri
 }
 ```
 
-The `note` field is where a check's known gap is recorded, so a partial check never reads as a complete one.
+The `text` field is the bullet as written in the document (markdown links and code spans intact), so it is greppable in the doc it came from; the `hash` is computed from the same text with links collapsed to their text and code spans unwrapped, so editing a URL or adding backticks does not read as a change. The `note` field is where a check's known gap is recorded, so a partial check never reads as a complete one.
 
 | Kind | Meaning |
 | --- | --- |
 | `eslint` | An ESLint rule reports it, and a fixture test titled with the requirement pins it |
 | `doctor` | A `pasika doctor` check reports it |
-| `docs-check` | A `pasika docs` check reports it |
 | `planned` | Mechanically checkable, not written yet; `note` names the intended check |
 | `judgment` | No mechanical check can decide it; `note` says why |
 | `permission` | The requirement grants permission, so there is nothing to check |
@@ -57,9 +56,9 @@ The `note` field is where a check's known gap is recorded, so a partial check ne
 
 ## Commands
 
+The documentation guide itself is linted: the `pasika/*` markdown rules run over `docs/**/*.md` and report title, overview, structure, example-pairing, and RFC 2119 violations at the exact node.
+
 ```bash
-npx pasika docs                # check a docs/ folder against the documentation guide
-npx pasika docs --dir content  # check another folder
 npx pasika coverage            # check that every requirement has recorded enforcement
 npx pasika coverage --accept   # record reworded and removed requirements
 ```
@@ -93,6 +92,8 @@ const { eslintConfig } = styleguide({
 export default eslintConfig;
 ```
 
+`zirka` composes the full pasika ruleset over four file scopes: TS/TSX under `src/**`, `globals.css` and other stylesheets, `package.json`, and markdown — each with its own ESLint language.
+
 ### Without Zirka
 
 ```ts
@@ -102,7 +103,9 @@ import { pasikaConfig } from "pasika/eslint";
 export default [pasikaConfig];
 ```
 
-The ruleset applies to `src/**` only, so a repository without a `src/` tree passes it trivially.
+`pasikaConfig` applies the TS/TSX rules to `src/**` only, so a repository without a `src/` tree passes it trivially. The CSS, JSON, and markdown language configs are composed by `zirka`'s `styleguide()`; the individual rule objects (`cssRules`, `jsonRules`, `mdRules`) are exported for manual wiring.
+
+### TS/TSX rules
 
 | Rule | Enforces |
 | --- | --- |
@@ -112,20 +115,76 @@ The ruleset applies to `src/**` only, so a repository without a `src/` tree pass
 | `pasika/no-arbitrary-tailwind` | No arbitrary `-[value]` classes, including inside `cn()` conditionals |
 | `pasika/enforce-cn-merge` | `cn()` instead of `+` or template literals; at most five classes per group |
 | `pasika/enforce-cva-variant-props` | `VariantProps<typeof …>` instead of hand-written unions |
+| `pasika/cva-appearance-props` | Visual option props (`size`, `variant`, …) declared through CVA appearance props |
+| `pasika/cva-boolean-variants` | Boolean appearance props placed on the CVA variant, not as standalone props |
 | `pasika/enforce-barrel-exports` | A nested `index.ts` re-exports only its component |
 | `pasika/component-placement` † | The folder a component's consumers imply |
 | `pasika/support-file-placement` † | The folder a hook, type, schema, constant, or utility belongs in |
+| `pasika/application-structure` | The path-based parts of the application structure and configuration rules |
+| `pasika/named-exports` | Named exports for application files (framework routing files may default-export) |
+| `pasika/data-testid-case` | `data-testid` casing where a rendered result carries one |
+| `pasika/support-folder-shape` | A `constants/`, `types/`, or `schemas/` folder defines exports directly in `index.ts` or in named-re-exported files |
+| `pasika/import-through-index` | An extracted constant, type, or schema is imported through its folder's `index.ts` |
+| `pasika/util-file-name` | A single-function utility file is named in the function's kebab-case form |
+| `pasika/no-util-barrel` | A utility is imported directly, without a barrel |
+| `pasika/jsx-hygiene` | Calculations and complex conditions stay out of JSX children and attributes |
+| `pasika/interactive-component` | Interactive elements are component boundaries when mixed with other content |
+| `pasika/ui-state` | Native or ARIA state expression and Tailwind state variants |
+| `pasika/cross-feature-import` | A component importing from two or more feature folders lives in a shared location |
+| `pasika/pure-function-extract` | Pure functions extracted to `utils/`, even with one consumer |
+| `pasika/hook-complexity` | Hook complexity limits (imperative categories per hook) |
+| `pasika/locale-dotted-path` | A namespaced locale is read through its full dotted path |
+| `pasika/locales-location` | Locales live in the named locales object |
+| `pasika/hook-extraction` † | A hook with two or more consumers is extracted to its own file |
+| `pasika/value-extraction` † | A value with cross-folder consumers is extracted |
+| `pasika/config-extraction` † | A type, schema, or utility used outside its config module is moved |
+| `pasika/component-nesting` † | A component is not nested solely because it has support files |
+| `pasika/stay-flat` † | A component stays flat until it has exclusive children |
+| `pasika/type-extraction` † | A type or schema with cross-folder consumers is extracted |
+| `pasika/locale-placement` † | Shared locales at the top level, single-feature locales namespaced |
+| `pasika/shared-style-dedup` † | A className combo used by two or more components becomes a named utility |
+| `pasika/no-eslint-disable` | No `eslint-disable` directives |
+
+### CSS rules
+
+Applied to `src/**/globals.css` (and other stylesheets) through `@eslint/css` with tolerant Tailwind v4 parsing.
+
+| Rule | Enforces |
+| --- | --- |
+| `pasika/theme-reset` | A `--*: initial` theme reset is present |
+| `pasika/root-variables` | `:root` defines the CSS custom properties |
+| `pasika/apply-usage` | `@layer base` uses `@apply` for declarations |
+| `pasika/base-layer-pair` | The base layer applies `base-canvas` and `base-ink` |
+| `pasika/stylesheet-ordering` | Imports → `@custom-variant` → `:root` → `@theme` → `@utility` → `@layer base` |
+| `pasika/css-variable-naming` | Background vars named `--<role>-canvas`, text vars `--<role>-ink` |
+| `pasika/custom-utility-apply` | `@utility` blocks use `@apply` |
+| `pasika/surface-utility` | Repeated canvas+ink combos become a named surface utility |
+| `pasika/theme-variable-namespace` | Utility class groups share a namespace prefix |
+| `pasika/global-css-location` | Global CSS lives in the correct entry point |
+
+### JSON rules
+
+Applied to `package.json` through `@eslint/json`.
+
+| Rule | Enforces |
+| --- | --- |
+| `pasika/no-cache-flag` | Lint scripts don't pass `--cache` |
+| `pasika/no-vulyk-dependency` | `vulyk` is not in `dependencies` |
+
+### Documentation rules
+
+The `pasika/*` markdown rules enforce the documentation guide over `docs/**/*.md` (24 rules): file-name suffixes and titles, overview presence and length, guide step structure, Incorrect/Correct pairing, policy document shape, reference block headings, RFC 2119 placement, template hygiene, link anchoring, and glossary-term linking. They run through `@eslint/markdown`; `pasika coverage` verifies each has a test and a registry entry. Pasika's own `docs/` are linted by them in CI (`npm run docs`).
 
 Run `pasika coverage --json` for the exact requirement each rule covers.
 
 ### † Cross-file rules
 
-Where a component or support file belongs depends on which files import it, so these two rules index the whole `src/` tree instead of looking at one file. Two consequences:
+Where a component, hook, value, type, or style belongs depends on which files use it, so the rules marked † index the whole `src/` tree instead of looking at one file. Two consequences:
 
 - **Do not pass `--cache`.** Move a file and the finding belongs to a *different* file, whose cache entry is unchanged — so ESLint would replay a stale verdict. `agent-policy.md` requires lint commands to run without it.
 - The index is read from disk rather than from ESLint's file list, so a partial run such as `lint-staged` still judges against the true graph.
 
-Both are inert in a repository with no `src/` tree.
+All are inert in a repository with no `src/` tree.
 
 ## Development
 
@@ -133,7 +192,6 @@ Both are inert in a repository with no `src/` tree.
 npm run lint
 npm run typecheck
 npm run test
-npm run docs
 npm run coverage
 npm run build
 ```

package/dist/cli/index.js

@@ -4,7 +4,8 @@ import path from "node:path";
 import { Command } from "commander";
 import { buildCoverageReport, classifyRequirement, readRegistry, writeRegistry, } from "../enforcement/coverage.js";
 import { enforcementKindSchema } from "../enforcement/types.js";
-import { checkDocs } from "../enforcement/docs-check.js";
+import { runDoctor } from "../enforcement/doctor.js";
+import { log, error, json } from "./output.js";
 const REGISTRY_RELATIVE_PATH = path.join("enforcement", "registry.json");
 /** Walks up from `startDir` to the directory that holds the enforcement registry. */
 function findRegistryRoot(startDir) {
@@ -30,30 +31,6 @@ function truncate(text, width) {
 }
 const program = new Command();
 program.name("pasika").description("Applies and diagnoses the pasika framework.");
-program
-    .command("docs")
-    .description("Check documentation against the documentation guide.")
-    .option("--dir <path>", "documentation folder to check", "docs")
-    .option("--json", "print findings as JSON")
-    .action((options) => {
-    const docsRoot = path.resolve(options.dir);
-    if (!existsSync(docsRoot)) {
-        console.error(`No documentation folder at ${docsRoot}`);
-        process.exit(1);
-    }
-    const { docs, findings } = checkDocs(docsRoot);
-    if (options.json) {
-        console.log(JSON.stringify({ documents: docs.length, findings }, undefined, 2));
-        process.exit(findings.length > 0 ? 1 : 0);
-    }
-    for (const finding of findings) {
-        console.log(`  ✗ ${finding.doc}:${String(finding.line)}  ${finding.check}  ${finding.message}`);
-    }
-    console.log(findings.length === 0
-        ? `\n✓ ${String(docs.length)} documents pass`
-        : `\n${String(docs.length)} documents checked · ${String(findings.length)} findings`);
-    process.exit(findings.length > 0 ? 1 : 0);
-});
 program
     .command("coverage")
     .description("Check that every documented requirement has recorded enforcement.")
@@ -66,19 +43,19 @@ program
     .action((options) => {
     const root = findRegistryRoot(process.cwd());
     if (!root) {
-        console.error(`No ${REGISTRY_RELATIVE_PATH} found in this directory or any parent.`);
+        error(`No ${REGISTRY_RELATIVE_PATH} found in this directory or any parent.`);
         process.exit(1);
     }
     const docsRoot = path.join(root, "docs");
     if (!existsSync(docsRoot)) {
-        console.error(`No documentation folder at ${docsRoot}. Run coverage inside the pasika repository.`);
+        error(`No documentation folder at ${docsRoot}. Run coverage inside the pasika repository.`);
         process.exit(1);
     }
     const registryPath = path.join(root, REGISTRY_RELATIVE_PATH);
     if (options.classify !== undefined) {
         const kind = enforcementKindSchema.safeParse(options.kind);
         if (!kind.success) {
-            console.error(`✗ --kind must be one of ${enforcementKindSchema.options.join(", ")}.`);
+            error(`✗ --kind must be one of ${enforcementKindSchema.options.join(", ")}.`);
             process.exit(1);
         }
         try {
@@ -87,14 +64,14 @@ program
                 registry: readRegistry(registryPath),
                 input: { hash: options.classify, kind: kind.data, ref: options.ref, note: options.note },
             });
-            writeRegistry(registryPath, result.registry);
+            writeRegistry(registryPath, result.registry, docsRoot);
             const change = result.previousKind === undefined
                 ? `recorded as ${result.requirement.kind}`
                 : `reclassified from ${result.previousKind} to ${result.requirement.kind}`;
-            console.log(`✓ ${change}: ${result.requirement.text}`);
+            log(`✓ ${change}: ${result.requirement.text}`);
         }
-        catch (error) {
-            console.error(`✗ ${error instanceof Error ? error.message : String(error)}`);
+        catch (err) {
+            error(`✗ ${err instanceof Error ? err.message : String(err)}`);
             process.exit(1);
         }
     }
@@ -104,29 +81,46 @@ program
         rulesDir: path.join(root, "eslint", "pasika", "rules"),
     });
     if (options.json) {
-        console.log(JSON.stringify(report, undefined, 2));
+        json(report);
         process.exit(report.issues.length > 0 ? 1 : 0);
     }
     for (const issue of report.issues) {
         const where = issue.line === undefined ? issue.doc : `${issue.doc}:${String(issue.line)}`;
-        console.log(`  ✗ ${ISSUE_LABELS[issue.kind]} ${truncate(issue.text, 76)}`);
-        console.log(`              ${where}${issue.detail ? `\n              ${issue.detail}` : ""}`);
+        log(`  ✗ ${ISSUE_LABELS[issue.kind]} ${truncate(issue.text, 76)}`);
+        log(`              ${where}${issue.detail ? `\n              ${issue.detail}` : ""}`);
     }
     const { counts } = report;
-    console.log([
+    log([
         "",
         `${String(report.total)} requirements · ${String(report.mechanical)} mechanically enforced`,
-        `  eslint ${String(counts.eslint)} · doctor ${String(counts.doctor)} · docs-check ${String(counts["docs-check"])}`,
+        `  eslint ${String(counts.eslint)} · doctor ${String(counts.doctor)}`,
         `  planned ${String(counts.planned)} · judgment ${String(counts.judgment)} · permission ${String(counts.permission)}`,
         `  unclassified ${String(report.issues.filter((issue) => issue.kind === "new").length)}`,
     ].join("\n"));
     if (options.accept) {
-        writeRegistry(registryPath, report.nextRegistry);
+        writeRegistry(registryPath, report.nextRegistry, docsRoot);
         const accepted = report.issues.filter((issue) => issue.kind === "changed" || issue.kind === "removed");
-        console.log(`\nAccepted ${String(accepted.length)} change(s) into ${REGISTRY_RELATIVE_PATH}.`);
-        console.log("Requirements reported as new still need a classification.");
+        log(`\nAccepted ${String(accepted.length)} change(s) into ${REGISTRY_RELATIVE_PATH}.`);
+        log("Requirements reported as new still need a classification.");
         process.exit(report.issues.some((issue) => issue.kind === "new") ? 1 : 0);
     }
     process.exit(report.issues.length > 0 ? 1 : 0);
 });
+program
+    .command("doctor")
+    .description("Diagnose gaps between the repository and the pasika framework baseline.")
+    .option("--json", "print findings as JSON")
+    .action((options) => {
+    const findings = runDoctor(process.cwd());
+    if (options.json) {
+        json({ findings });
+        process.exit(findings.some((f) => f.severity === "error") ? 1 : 0);
+    }
+    for (const finding of findings) {
+        const icon = finding.severity === "error" ? "✗" : "⚠";
+        log(`  ${icon} ${finding.check}  ${finding.message}`);
+    }
+    log(findings.length === 0 ? "\n✓ No gaps found" : `\n${String(findings.length)} finding(s)`);
+    process.exit(findings.some((f) => f.severity === "error") ? 1 : 0);
+});
 program.parse();

package/dist/cli/output.d.ts

@@ -0,0 +1,3 @@
+export declare function log(message: string): void;
+export declare function error(message: string): void;
+export declare function json(data: unknown): void;

package/dist/cli/output.js

@@ -0,0 +1,11 @@
+/* eslint-disable no-console -- cli-reports-to-terminal: stdout is the CLI's output channel */
+export function log(message) {
+    console.log(message);
+}
+export function error(message) {
+    console.error(message);
+}
+export function json(data) {
+    console.log(JSON.stringify(data, undefined, 2));
+}
+/* eslint-enable no-console -- re-enable after CLI output block */

package/dist/enforcement/coverage.d.ts

@@ -48,4 +48,8 @@ export declare function classifyRequirement(options: {
     input: ClassifyInput;
 }): ClassifyResult;
 export declare function readRegistry(registryPath: string): Registry;
-export declare function writeRegistry(registryPath: string, registry: Registry): void;
+/**
+ * Writes the registry sorted in the same order the requirements appear in the
+ * docs: document order, then line order within each document.
+ */
+export declare function writeRegistry(registryPath: string, registry: Registry, docsRoot: string): void;

package/dist/enforcement/coverage.js

@@ -1,8 +1,8 @@
-import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { readdirSync, readFileSync, writeFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
-import { pasikaRuleIds } from "../eslint/pasika/index.js";
-import { DOCS_CHECKS } from "./docs-check.js";
+import { allPasikaRuleIds } from "../eslint/pasika/index.js";
+import { normalizeRequirement } from "./normalize.js";
 import { parseDocs } from "./parse-docs.js";
 import { MECHANICAL_KINDS, registrySchema } from "./types.js";
 /** Ratio of shared words, used only to guess which stored requirement a reworded bullet came from. */
@@ -13,17 +13,27 @@ function similarity(left, right) {
     const union = new Set([...leftWords, ...rightWords]).size;
     return union === 0 ? 0 : shared / union;
 }
-/** Titles passed to `describe` or `test` in the rule test files. */
+/** Titles passed to `describe` or `test` in the rule test files, recursing into subfolders. */
 function collectTestTitles(rulesDir) {
     const titles = new Set();
-    for (const entry of readdirSync(rulesDir)) {
-        if (!entry.endsWith(".test.ts"))
-            continue;
-        const body = readFileSync(path.join(rulesDir, entry), "utf8");
-        for (const match of body.matchAll(/\b(?:describe|test|it)\(\s*"(?<title>(?:[^"\\]|\\.)*)"/g)) {
-            titles.add((match.groups?.title ?? "").replaceAll('\\"', '"'));
+    const visit = (dir) => {
+        for (const entry of readdirSync(dir)) {
+            const entryPath = path.join(dir, entry);
+            if (statSync(entryPath).isDirectory()) {
+                visit(entryPath);
+                continue;
+            }
+            if (!entry.endsWith(".test.ts"))
+                continue;
+            const body = readFileSync(entryPath, "utf8");
+            const titlePattern = /\b(?:describe|test|it)\(\s*(?:"(?<double>(?:[^"\\]|\\.)*)"|'(?<single>(?:[^'\\]|\\.)*)')/g;
+            for (const match of body.matchAll(titlePattern)) {
+                const title = match.groups?.double ?? match.groups?.single ?? "";
+                titles.add(title.replaceAll('\\\\"', '"').replaceAll("\\\\'", "'"));
+            }
         }
-    }
+    };
+    visit(rulesDir);
     return titles;
 }
 /** A requirement several checks cover lists them comma-separated. */
@@ -33,19 +43,16 @@ function refParts(ref) {
         .map((part) => part.trim())
         .filter(Boolean);
 }
-function isRefKnown(requirement, docsChecks) {
+function isRefKnown(requirement) {
     const parts = refParts(requirement.ref);
     if (requirement.kind === "eslint")
-        return parts.length > 0 && parts.every((part) => pasikaRuleIds.includes(part));
-    if (requirement.kind === "docs-check")
-        return parts.length > 0 && parts.every((part) => docsChecks.has(part));
+        return parts.length > 0 && parts.every((part) => allPasikaRuleIds.includes(part));
     // Doctor checks do not exist yet, so a `doctor` entry is a forward reference.
     return true;
 }
 export function buildCoverageReport(options) {
     const { docsRoot, registry, rulesDir } = options;
     const docs = parseDocs(docsRoot);
-    const docsChecks = new Set(DOCS_CHECKS);
     const testTitles = collectTestTitles(rulesDir);
     const byHash = new Map(registry.requirements.map((requirement) => [requirement.hash, requirement]));
     const matched = new Set();
@@ -53,10 +60,9 @@ export function buildCoverageReport(options) {
     const counts = {
         eslint: 0,
         doctor: 0,
-        "docs-check": 0,
+        planned: 0,
         judgment: 0,
         permission: 0,
-        planned: 0,
     };
     const nextRequirements = [];
     const parsed = docs.flatMap((doc) => doc.requirements.map((requirement) => ({ doc: doc.doc, requirement })));
@@ -65,13 +71,13 @@ export function buildCoverageReport(options) {
         if (recorded) {
             matched.add(requirement.hash);
             counts[recorded.kind] += 1;
-            nextRequirements.push({ ...recorded, doc });
-            if (!isRefKnown(recorded, docsChecks)) {
+            nextRequirements.push({ ...recorded, doc, text: requirement.raw });
+            if (!isRefKnown(recorded)) {
                 issues.push({
                     kind: "unknown-ref",
                     doc,
                     line: requirement.line,
-                    text: requirement.text,
+                    text: requirement.raw,
                     detail: `${recorded.kind} ref "${recorded.ref ?? "(none)"}" does not exist`,
                 });
             }
@@ -80,7 +86,7 @@ export function buildCoverageReport(options) {
                     kind: "missing-test",
                     doc,
                     line: requirement.line,
-                    text: requirement.text,
+                    text: requirement.raw,
                     detail: `no rule test is titled with this requirement`,
                 });
             }
@@ -89,24 +95,24 @@ export function buildCoverageReport(options) {
         // Not recorded under this hash: either a reworded requirement or a new one.
         const candidate = registry.requirements
             .filter((entry) => entry.doc === doc && !matched.has(entry.hash))
-            .map((entry) => ({ entry, score: similarity(entry.text, requirement.text) }))
+            .map((entry) => ({ entry, score: similarity(normalizeRequirement(entry.text), requirement.text) }))
             .sort((left, right) => right.score - left.score)
             .find(({ score }) => score >= 0.5);
         if (candidate) {
             matched.add(candidate.entry.hash);
             counts[candidate.entry.kind] += 1;
-            nextRequirements.push({ ...candidate.entry, doc, text: requirement.text, hash: requirement.hash });
+            nextRequirements.push({ ...candidate.entry, doc, text: requirement.raw, hash: requirement.hash });
             issues.push({
                 kind: "changed",
                 doc,
                 line: requirement.line,
-                text: requirement.text,
+                text: requirement.raw,
                 hash: requirement.hash,
                 detail: `was "${candidate.entry.text}" — re-verify ${candidate.entry.kind}${candidate.entry.ref ? ` ${candidate.entry.ref}` : ""}`,
             });
         }
         else {
-            issues.push({ kind: "new", doc, line: requirement.line, text: requirement.text, hash: requirement.hash });
+            issues.push({ kind: "new", doc, line: requirement.line, text: requirement.raw, hash: requirement.hash });
         }
     }
     for (const entry of registry.requirements) {
@@ -150,20 +156,11 @@ export function classifyRequirement(options) {
     if (input.kind === "eslint") {
         if (refs.length === 0)
             throw new Error('Kind "eslint" needs --ref naming the rule that reports it.');
-        const unknown = refs.filter((ref) => !pasikaRuleIds.includes(ref));
+        const unknown = refs.filter((ref) => !allPasikaRuleIds.includes(ref));
         if (unknown.length > 0) {
             throw new Error(`--ref ${unknown.map((ref) => `"${ref}"`).join(", ")} is not a rule in the plugin.`);
         }
     }
-    else if (input.kind === "docs-check") {
-        if (refs.length === 0)
-            throw new Error('Kind "docs-check" needs --ref naming the check that reports it.');
-        const known = new Set(DOCS_CHECKS);
-        const unknown = refs.filter((ref) => !known.has(ref));
-        if (unknown.length > 0) {
-            throw new Error(`--ref ${unknown.map((ref) => `"${ref}"`).join(", ")} is not a documentation check.`);
-        }
-    }
     else if (input.kind !== "doctor" && refs.length > 0) {
         throw new Error(`Kind "${input.kind}" takes no --ref, because nothing reports it.`);
     }
@@ -173,7 +170,7 @@ export function classifyRequirement(options) {
     }
     const requirement = {
         doc: match.doc,
-        text: match.requirement.text,
+        text: match.requirement.raw,
         hash: match.requirement.hash,
         kind: input.kind,
         ...(refs.length > 0 ? { ref: refs.join(", ") } : {}),
@@ -192,6 +189,22 @@ export function readRegistry(registryPath) {
     }
     return result.data;
 }
+/**
+ * Sequence position of each requirement in the docs: doc order as `parseDocs`
+ * yields it, then line order within each doc. Entries whose hash no longer
+ * exists in the docs (removed, not yet accepted) sort after everything parsed.
+ */
+function buildDocOrder(docsRoot) {
+    const order = new Map();
+    let position = 0;
+    for (const doc of parseDocs(docsRoot)) {
+        for (const requirement of doc.requirements) {
+            order.set(requirement.hash, position);
+            position += 1;
+        }
+    }
+    return order;
+}
 /**
  * Code-point order on doc then text. Deliberately not `localeCompare`, whose
  * result depends on the host's locale data — a generated file that is committed
@@ -204,7 +217,23 @@ function compareRequirements(left, right) {
         return left.text < right.text ? -1 : 1;
     return 0;
 }
-export function writeRegistry(registryPath, registry) {
-    const sorted = { requirements: [...registry.requirements].sort(compareRequirements) };
+/**
+ * Writes the registry sorted in the same order the requirements appear in the
+ * docs: document order, then line order within each document.
+ */
+export function writeRegistry(registryPath, registry, docsRoot) {
+    const order = buildDocOrder(docsRoot);
+    const withPosition = registry.requirements.map((requirement) => ({
+        requirement,
+        position: order.get(requirement.hash) ?? Number.MAX_SAFE_INTEGER,
+    }));
+    withPosition.sort((left, right) => {
+        if (left.position !== right.position)
+            return left.position - right.position;
+        // Two entries with the same hash cannot coexist; this fallback orders
+        // entries whose hash the docs no longer contain, deterministically.
+        return compareRequirements(left.requirement, right.requirement);
+    });
+    const sorted = { requirements: withPosition.map((entry) => entry.requirement) };
     writeFileSync(registryPath, `${JSON.stringify(sorted, null, 2)}\n`);
 }

package/dist/enforcement/doctor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `pasika doctor` checks.
+ *
+ * Diagnoses gaps between a consumer repository and the pasika framework
+ * baseline. Scope: dependencies, configuration, managed files, and
+ * source structure. Code-level and path-level rules belong to ESLint.
+ */
+export interface DoctorFinding {
+    /** Which requirement this relates to. */
+    check: string;
+    /** Human-readable description. */
+    message: string;
+    /** Severity: error blocks adoption, warning is informational. */
+    severity: "error" | "warning";
+}
+export declare function runDoctor(cwd: string): DoctorFinding[];