@csark0812/skeleton 1.6.3 → 2.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 <!-- source-of-truth: Package overview -->
 
-<!-- doc-meta: owner=eng | last-reviewed=2026-08-16 -->
+<!-- doc-meta: owner=eng | last-reviewed=2026-08-19 -->
 
 <!-- code-fit: targets=src/cli.ts surface=audit,validate,catalog,init,build-plugin,references -->
 
@@ -23,14 +23,14 @@ That needs to be explicit — and stay true after the next 50 PRs. Skeleton turn
 | Code repos                                              | Agent repos                                                                            |
 | ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | ESLint catches broken imports, unused vars, style drift | Skeleton catches broken links, bad SSOT markers, stale doc-meta, deny.paths artifacts |
-| `eslint --fix` on changed files                         | `skeleton validate changed` on changed docs and skills                                 |
+| `eslint --fix` on changed files                         | `skeleton validate changed` on changed docs, skills, and docs linked to changed code   |
 | Pre-commit + CI gate                                    | `--staged` pre-commit + `--base` CI gate                                               |
 
 Skill linters ask: _"Is this SKILL.md well-formed?"_
 
 Skeleton asks the repo-level question: _"Does this whole thing still agree with itself?"_
 
-## Why a clean SSOT helps agents
+## Preliminary agent-behavior evidence
 
 ### Question
 
@@ -38,19 +38,19 @@ Does an intact Skeleton contract change agent behavior — grounding on the righ
 
 ### What we did
 
-We ran a paired live A/B harness with [`@post-print/agent-test`](https://www.npmjs.com/package/@post-print/agent-test): `skeleton-clean` vs `skeleton-messy`. Same prompts and scenario set; the only intentional difference was SSOT / conflict structure and context profile.
+We ran a paired live A/B self-benchmark with [`@post-print/agent-test`](https://www.npmjs.com/package/@post-print/agent-test): `skeleton-clean` vs `skeleton-messy`. The same authored prompts compare an intact fixture with a conflicting fixture.
 
 Scenarios covered contested grounding (conflicting docs), docs-only validation routing, canonical grounding, owned-skill routing, and customize ownership. Protocol: **N=10** sequential paired compares on 2026-07-17; McNemar on paired pass/fail; median token deltas with a bootstrap CI on the mean.
 
 Full method: [refs/llm-harness.md](refs/llm-harness.md). Suites: [agent-suites/README.md](agent-suites/README.md). Aggregated numbers: [SUMMARY.md](agent-suites/evidence/SUMMARY.md). Side-by-side excerpts: [evidence/transcripts/](agent-suites/evidence/transcripts/).
 
-### What improved
+### What the benchmark observed
 
 ![Pass rate by scenario — clean vs messy](agent-suites/evidence/charts/pass-rates.svg)
 
 ![Median extra tokens on messy](agent-suites/evidence/charts/token-delta.svg)
 
-On tasks that depend on an intact SSOT, the clean fixture was both more accurate and cheaper:
+Inside this harness, tasks that depend on an intact SSOT favored the clean fixture:
 
 - **Contested grounding** — In every paired run, clean settled on the SSOT canonical; messy never did (McNemar p = 0.002). Clean hops the catalog/SSOT path; messy thrashes across conflicting docs.
 - **Docs routing** — Clean consistently chose the correct audit lane; messy invented a non-existent `audit all` path (McNemar p = 0.002).
@@ -65,7 +65,7 @@ Charts regenerate from `SUMMARY.json` via `bun run agent:evidence:charts`.
 
 ### Limits
 
-Fixture A/B on Skeleton’s own contract (live model + prompt variance) — not a general coding-task or SWE-bench claim. Skill/customize may not separate when the entry doc already teaches the correct rule.
+This is preliminary evidence from Skeleton’s own authored fixture, prompt set, repository, and execution period. Repeated runs characterize variance inside that harness; they do not independently establish a causal product effect. It is not a general coding-task or SWE-bench claim. Skill/customize did not separate when the entry doc already taught the correct rule.
 
 ### Industry context
 
@@ -99,6 +99,8 @@ Flag details: [install](docs/developer/install.md).
 - **deny.paths** — globs for files that must not exist (often outside `scan.include`)
 - **Coverage gaps** — markdown outside the scan perimeter (warn-only)
 - **Doc meta + stale dates** — owner and `last-reviewed` on indexes and SSOT-bearing files
+- **Review proof** — optional hashes bind a human review to exact document and `code-fit` target bytes
+- **Code impact routing** — changed source files automatically pull linked documents into validation
 - **Prose policy** (optional plugins) — YAML pattern rules; idle with no plugins
 - **Shell / JSON syntax** — lightweight checks on changed `.sh` and `.json` files
 
@@ -114,6 +116,7 @@ Config lives in **`skeleton.toml`** at the repo root (preferred). Optional under
 skeleton.toml          # scan perimeter, deny.paths, docsLint, …
 .skeleton/
 ├── catalog.md         # generated by `skeleton catalog` (gitignored)
+├── review-lock.json   # generated review evidence when reviewProof.mode = "hash"
 ├── plugins/           # optional consumer audit plugins (.ts + built .mjs)
 └── customize/         # project-specific skill overrides (optional)
     └── code-review.md
@@ -139,8 +142,9 @@ Synced skills stay pristine. Project overrides live in `.skeleton/customize/<slu
 
 ```bash
 skeleton init [--skills] [--force-hooks]
-skeleton catalog [--check]
-skeleton audit docs|skills|self [--strict] [--paths=a,b] [--fix[=doc-meta|anchors|ssot]] [--dry-run]
+skeleton catalog [--check] [--strict]
+skeleton audit docs|skills|self [--strict] [--json] [--paths=a,b] [--fix[=doc-meta|anchors|ssot]] [--dry-run]
+skeleton audit docs --paths=docs/a.md --fix=doc-meta --confirm-reviewed
 skeleton build-plugin [path] [--check]
 skeleton validate changed [--staged | --base <ref>] [paths…]
 skeleton references sync|check
@@ -156,7 +160,8 @@ skeleton customize resolve <slug>
 | Foreign / lockfile-synced skill bodies                                              | skip → lint in the owning skills/toolbox repo |
 | `.sh`, `.bash`, `.zsh`                                                              | shellcheck or `bash -n`                       |
 | Other `.json`                                                                       | JSONC-tolerant syntax check                   |
-| `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.py`, `package.json`, `project.json` | skip (exits 1 if all skip)                    |
+| `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.py`                               | native code gates + audit documents whose `code-fit` target changed |
+| `package.json`, `project.json`                                                     | native code gates (exits 1 if no auditable paths) |
 
 Pre-commit: `skeleton validate changed --staged` (path-scoped, fast).
 
@@ -195,7 +200,7 @@ bun run check
 
 `bun run check` = lint + test + typecheck + build + `audit:self`.
 
-`validate:changed` is docs/config only for path-scoped work — it skips code/config extensions (see table above). Owned skill-body edits need `audit skills`. All-skip, owned skill paths (alone or mixed with docs), and missing paths exit non-zero.
+`validate:changed` does not replace code tests. It classifies code separately and also audits every scanned document that names a changed file in `code-fit`. Owned skill-body edits need `audit skills`. Code-only changes with no linked document still exit non-zero locally and point to native gates.
 
 For code: `bun test`, `bun run typecheck`, `bun run build`.
 

package/dist/audit/config/load.d.ts

@@ -0,0 +1,18 @@
+import type { SkeletonConfig } from "./types.ts";
+export declare const ROOT_CONFIG_TOML = "skeleton.toml";
+export declare const LEGACY_CONFIG_YAML: string;
+/** Built-in exclude patterns applied to scan and deny.paths passes. */
+export declare const BUILTIN_EXCLUDES: string[];
+/** Built-in excludes for coverage-gaps candidate discovery. */
+export declare const COVERAGE_BUILTIN_EXCLUDES: string[];
+export declare function findRepoRoot(startDir?: string): string;
+export interface LoadConfigResult {
+    config: SkeletonConfig;
+    source: "toml" | "yaml";
+    warnedDual?: boolean;
+}
+export declare function loadConfigDetailed(root: string): LoadConfigResult;
+export declare function loadConfig(root: string): SkeletonConfig;
+export declare function mergedExcludes(config: SkeletonConfig): string[];
+export declare function denyPaths(config: SkeletonConfig): string[];
+export declare function nonPublicSkills(config: SkeletonConfig): string[];

package/dist/audit/config/types.d.ts

@@ -0,0 +1,75 @@
+export interface ScanConfig {
+    include: string[];
+    exclude: string[];
+    /** Slugs present on disk but excluded from README Taxonomy (internal skills). */
+    nonPublicSkills?: string[];
+}
+export interface DenyConfig {
+    /** Repo-wide globs that must not exist — audit fails if matched. */
+    paths?: string[];
+}
+export interface CustomizeConfig {
+    /** Basenames under `.skeleton/customize/` appended on every customize inject. */
+    alwaysInclude?: string[];
+}
+/**
+ * Ownership policy for skill-body linting.
+ * Lockfile `sourceType` other than `local` (e.g. `github`) marks skills foreign by default.
+ */
+export interface SkillOwnershipConfig {
+    /** Repo-relative path to skills-lock.json (default: skills-lock.json). */
+    lockfile?: string;
+    /** Force these slugs owned even if the lockfile marks them foreign. */
+    ownedSlugs?: string[];
+    /** Force these slugs foreign even if absent from the lockfile / local. */
+    foreignSlugs?: string[];
+}
+/** Verifiable evidence that a human review covered exact document and code bytes. */
+export interface ReviewProofConfig {
+    /** Hash mode stores reviewed document and code-target digests in a lockfile. */
+    mode: "hash";
+    /** Repo-relative proof lockfile (default: .skeleton/review-lock.json). */
+    lockfile?: string;
+}
+/** Tunables for near-duplicate, SSOT-summary, and code-fit docs lint. */
+export interface DocsLintConfig {
+    /** Jaccard threshold on word shingles (0–1). Default 0.72. */
+    nearDuplicateThreshold?: number;
+    /** Min fraction of SSOT tokens that must appear in evidence (default 0.35). */
+    ssotOverlapMin?: number;
+    /** Margin by which another file must beat own overlap for better-match (default 0.15). */
+    ssotBetterMatchMargin?: number;
+    /** When overlap fails, mention missing SSOT phrase in the message (default true). */
+    ssotPhraseCheck?: boolean;
+    /** Repo-relative path pairs to skip in near-dupe / duplicate-SSOT checks. */
+    ignorePairs?: [string, string][];
+    /** Globs excluded from near-dupe / duplicate-SSOT (still catalogued if they have SSOT). */
+    ignoreGlobs?: string[];
+    /**
+     * Min fraction of code identifiers that must appear in the doc (code-fit).
+     * Default 0.03 — separate from ssotOverlapMin (doc-grounding vs large modules).
+     */
+    codeFitOverlapMin?: number;
+    /** Max auto-extracted surface names before surface= is required (default 25). */
+    codeFitSurfaceCap?: number;
+}
+export interface SkeletonConfig {
+    scan: ScanConfig;
+    /** Re-read cadence (days) for doc-meta last-reviewed; separate from git edit-behind-review. */
+    daysUntilStale: number;
+    deny?: DenyConfig;
+    customize?: CustomizeConfig;
+    skillOwnership?: SkillOwnershipConfig;
+    reviewProof?: ReviewProofConfig;
+    docsLint?: DocsLintConfig;
+    /**
+     * Plugin entry paths relative to `.skeleton/` (e.g. `plugins/example.ts`).
+     * Each entry must have a built sibling `.mjs` (`skeleton build-plugin`).
+     */
+    plugins?: string[];
+    /**
+     * Path prefixes where `draft-marker` prose-policy placement is allowed
+     * (in addition to `_draft-*.md` filenames). Not the same as `scan.exclude`.
+     */
+    draftPathPrefixes?: string[];
+}

package/dist/audit/core/code-fit.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Docs↔code surface fit (no LLM): opt-in markers, public-name coverage, identifier overlap.
+ */
+export declare const DEFAULT_CODE_FIT_OVERLAP_MIN = 0.03;
+export declare const DEFAULT_CODE_FIT_SURFACE_CAP = 25;
+export interface CodeFitMarker {
+    targets: string[];
+    surface: string[] | null;
+    raw: string;
+}
+export interface CodeFitOptions {
+    overlapMin?: number;
+    surfaceCap?: number;
+    root: string;
+}
+export interface CodeFitIssue {
+    path: string;
+    message: string;
+    link?: string;
+}
+/** Parse all code-fit HTML comment markers in a markdown body (fences + inline code stripped). */
+export declare function parseCodeFitMarkers(content: string): CodeFitMarker[];
+/** Strip // and /* *\/ comments and string literals for identifier harvest. */
+export declare function stripCodeNoise(source: string): string;
+/** Auto-extract public-ish names: export forms + case "…" dispatch labels. */
+export declare function extractPublicSurface(source: string): string[];
+/** Identifier tokens from source (for lexical overlap). */
+export declare function codeIdentifiers(source: string): string[];
+/**
+ * Fraction of unique doc content tokens that also appear as identifiers in the
+ * code file (doc grounded in module vocabulary). Separate from name coverage.
+ */
+export declare function identifierOverlap(docContent: string, codeSource: string): number;
+/** Evaluate one markdown doc's code-fit markers. */
+export declare function evaluateCodeFitDoc(docPath: string, docContent: string, options: CodeFitOptions): CodeFitIssue[];

package/dist/audit/core/collect.d.ts

@@ -0,0 +1,21 @@
+import type { SkeletonConfig } from "../config/types.ts";
+import { type SkillIndex } from "./skill-roots.ts";
+export declare function collectScanFiles(config: SkeletonConfig, root: string, skillIndex?: SkillIndex): string[];
+export declare function collectBannedFiles(config: SkeletonConfig, root: string): string[];
+export declare function collectCoverageCandidateFiles(root: string, exclude: string[]): string[];
+/** Drop foreign lockfile-synced skill trees from doc-meta scope (linted upstream). */
+export declare function excludeForeignSkillDocMetaPaths(docMetaPaths: string[], skillIndex?: SkillIndex): string[];
+interface DocMetaCollectContext {
+    config: SkeletonConfig;
+    root: string;
+    registryPaths: string[];
+    skillIndex?: SkillIndex;
+}
+export declare function collectDocMetaPaths(ctx: DocMetaCollectContext): string[];
+export declare function validateScanRoots(config: SkeletonConfig, root: string): string[];
+export declare function filterDocMetaPaths(docMetaPaths: string[], paths: string[], skillIndex?: SkillIndex): string[];
+export declare function filterToPaths(files: string[], paths: string[], root: string): string[];
+export declare function includeExplicitMarkdownPaths(files: string[], paths: string[], root: string): string[];
+export declare function readFileContent(absPath: string): string;
+export declare function relPath(absPath: string, root: string): string;
+export {};

package/dist/audit/core/context.d.ts

@@ -0,0 +1,46 @@
+import type { SkeletonConfig } from "../config/types.ts";
+import type { PolicyFile } from "../policies/types.ts";
+import { type SkillIndex } from "./skill-roots.ts";
+import type { SsotForm } from "./ssot.ts";
+import { type SsotFileEntry } from "./ssot-collect.ts";
+export interface AuditContext {
+    root: string;
+    config: SkeletonConfig;
+    files: string[];
+    docMetaPaths: string[];
+    /** Opt-in SSOT-bearing files (catalog membership). */
+    ssotEntries: SsotFileEntry[];
+    ssotErrors: Array<{
+        path: string;
+        kind: "dual" | "malformed";
+        detail: string;
+        forms?: SsotForm[];
+    }>;
+    /**
+     * @deprecated Prefer ssotEntries — kept empty for plugin type stability during transition.
+     */
+    registryPaths: string[];
+    /** @deprecated Always false — hand registry removed. */
+    registryHasTableHeader: boolean;
+    skillIndex: SkillIndex;
+    /**
+     * Foreign (synced) skill slugs — same as `skillIndex.foreignSlugs`.
+     * Used by doc-meta to skip consumer-side git-date freshness on upstream bodies.
+     */
+    lockedSkillSlugs: Set<string>;
+    /** Compiled prose policies from plugins (empty when no plugins / no policy globs). */
+    policies: PolicyFile[];
+}
+export interface AuditOptions {
+    root?: string;
+    changed?: boolean;
+    paths?: string[];
+    policies?: PolicyFile[];
+    /**
+     * Union skill-tree markdown (SKILL.md + references/**) into the corpus even when
+     * `scan.exclude` dropped them. Used by bare `audit skills` so skill-scoped prose
+     * matches path-scoped / validate `--base` prove.
+     */
+    includeExcludedSkillTrees?: boolean;
+}
+export declare function createContext(options?: AuditOptions): AuditContext;

package/dist/audit/core/draft.d.ts

@@ -0,0 +1,11 @@
+/** `_draft-foo.md` anywhere in the tree. */
+export declare const DRAFT_FILENAME_RE: RegExp;
+/** Treat configured prefixes as directories (trailing `/` implied). */
+export declare function normalizeDraftPrefix(prefix: string): string;
+/** Fail closed on prefixes that would never match repo-relative paths. */
+export declare function validateDraftPathPrefixes(prefixes: string[] | undefined): void;
+/**
+ * Draft markers (`draft-marker` prose entry) are allowed in `_draft-*.md`
+ * filenames or under any configured `draftPathPrefixes` path prefix.
+ */
+export declare function isDraftPlacementAllowed(relPath: string, draftPathPrefixes: string[]): boolean;

package/dist/audit/core/fix.d.ts

@@ -0,0 +1,29 @@
+import type { AuditContext } from "./context.ts";
+export type FixKind = "doc-meta" | "anchors" | "ssot";
+export interface FixEdit {
+    file: string;
+    description: string;
+    content: string;
+}
+export interface ApplyFixesOptions {
+    kinds: FixKind[];
+    dryRun?: boolean;
+}
+export interface ApplyFixesResult {
+    edits: FixEdit[];
+    modifiedFiles: string[];
+}
+/**
+ * Merge per-file snapshots so default `--fix` (doc-meta + anchors) does not
+ * last-write-win. Prefer anchors content, then overlay last-reviewed from meta.
+ */
+/** Merge per-file fix edits: anchors content, overlay last-reviewed, then SSOT rewrite. */
+export declare function coalesceFixEdits(metaEdits: FixEdit[], anchorEdits: FixEdit[], ssotEdits?: FixEdit[]): FixEdit[];
+/** Resolve a write path and refuse escapes outside the repo root (incl. symlinks). */
+export declare function resolveWritePath(root: string, relFile: string): string;
+export declare function applyFixes(ctx: AuditContext, options: ApplyFixesOptions): ApplyFixesResult;
+export declare function parseFixKinds(raw: string | true): FixKind[];
+/** Owning audit rule id for each fix kind (used to scope `--fix` under `--only`). */
+export declare const FIX_KIND_RULE: Record<FixKind, string>;
+/** When `--only` is set, keep fix kinds whose owning rules are selected. */
+export declare function fixKindsForOnly(kinds: FixKind[], only: Set<string> | null): FixKind[];

package/dist/audit/core/git-meta.d.ts

@@ -0,0 +1 @@
+export declare function lastGitCommitDate(relPath: string, root: string): string | null;

package/dist/audit/core/markdown.d.ts

@@ -0,0 +1,16 @@
+export interface ExtractedLink {
+    target: string;
+    line?: number;
+    /** Inclusive start offset of the URL in the source (when known). */
+    urlStart?: number;
+    /** Exclusive end offset of the URL in the source (when known). */
+    urlEnd?: number;
+}
+/**
+ * Strip leading YAML frontmatter so a closing `---` is not parsed as a setext
+ * underline (which yields false heading slugs like `title-getting-started`).
+ */
+export declare function stripYamlFrontmatter(content: string): string;
+export declare function extractLinksFromMarkdown(content: string, _filePath?: string): ExtractedLink[];
+export declare function extractHeadingSlugs(content: string, _filePath?: string): Set<string>;
+export declare function slugifyAnchor(anchor: string): string;

package/dist/audit/core/report.d.ts

@@ -0,0 +1,31 @@
+export type Severity = "error" | "warning";
+export interface Issue {
+    rule: string;
+    code?: string;
+    file: string;
+    link?: string;
+    message: string;
+    remediation?: string;
+    severity: Severity;
+}
+export interface ReportOptions {
+    strict?: boolean;
+    json?: boolean;
+    label?: string;
+    fileCount?: number;
+    successSuffix?: string;
+}
+export interface IssueOptions {
+    link?: string;
+    severity?: Severity;
+    code?: string;
+    remediation?: string;
+}
+export interface IssueDetails extends IssueOptions {
+    message: string;
+}
+export declare function issue(rule: string, file: string, details: string | IssueDetails): Issue;
+/** @deprecated Prefer the details-object form. Retained for 1.x plugin compatibility. */
+export declare function issue(rule: string, file: string, message: string, options?: IssueOptions): Issue;
+export declare function finalizeIssues(issues: Issue[], strict: boolean): Issue[];
+export declare function printReport(issues: Issue[], options: ReportOptions): number;

package/dist/audit/core/review-proof.d.ts

@@ -0,0 +1,23 @@
+import type { AuditContext } from "./context.ts";
+import { type Issue } from "./report.ts";
+export declare const DEFAULT_REVIEW_LOCKFILE = ".skeleton/review-lock.json";
+export interface AttestDocumentsOptions {
+    root: string;
+    paths: string[];
+    reviewedAt?: string;
+    dryRun?: boolean;
+}
+export interface AttestDocumentsResult {
+    reviewedAt: string;
+    documents: string[];
+    lockfile: string | null;
+    modifiedFiles: string[];
+}
+export declare function formatLocalReviewDate(date: Date): string;
+/** Record explicit review evidence for exactly the selected documents. */
+export declare function attestDocuments(options: AttestDocumentsOptions): AttestDocumentsResult;
+export declare function runReviewProofRule(ctx: AuditContext): Issue[];
+export declare const reviewProofRule: {
+    id: string;
+    run: typeof runReviewProofRule;
+};

package/dist/audit/core/shared.d.ts

@@ -0,0 +1,25 @@
+export declare const REGISTRY_REL_PATH = ".skeleton/registry.md";
+export declare const CATALOG_REL_PATH = ".skeleton/catalog.md";
+export declare const REGISTRY_DIR_REL = ".skeleton";
+export declare const EXTERNAL_LINK_RE: RegExp;
+export declare const SOURCE_OF_TRUTH_BANNER_RE: RegExp;
+export declare const SOURCE_OF_TRUTH_BANNER_LINE_RE: RegExp;
+export declare const DOC_META_RE: RegExp;
+export declare const DOC_META_LAST_REVIEWED_RE: RegExp;
+/** Extract last-reviewed date from the doc-meta comment only (ignore prose examples). */
+export declare function docMetaLastReviewed(content: string): string | null;
+/** Replace last-reviewed inside the doc-meta comment only. Returns null if unchanged/missing. */
+export declare function replaceDocMetaLastReviewed(content: string, date: string): string | null;
+export declare const SKILL_LINK_IN_TARGET_RE: RegExp;
+export declare const SKILL_LINK_RE: RegExp;
+/**
+ * Normalize repo-relative paths for bucket / filter matching.
+ * Converts backslashes and strips leading `./` segments. Absolute paths are left as-is
+ * (callers that accept only repo-relative paths must reject or remap them separately).
+ */
+export declare function normalizeRelPath(p: string): string;
+export declare function isExternalLink(target: string): boolean;
+export declare function isPlaceholderLink(target: string): boolean;
+export declare function matchesGlobScope(relPath: string, scope: string | undefined): boolean;
+export declare function extractScanRootsFromInclude(include: string[]): string[];
+export declare function resolveFromRegistry(root: string, linkTarget: string): string;

package/dist/audit/core/skill-provenance.d.ts

@@ -0,0 +1,37 @@
+import type { SkillOwnershipConfig } from "../config/types.ts";
+export declare const DEFAULT_SKILLS_LOCKFILE = "skills-lock.json";
+export type SkillSourceType = "github" | "local" | string;
+export interface SkillLockEntry {
+    source: string;
+    sourceType: SkillSourceType;
+    skillPath?: string;
+    computedHash?: string;
+}
+export interface SkillsLockFile {
+    version: number;
+    skills: Record<string, SkillLockEntry>;
+}
+export type SkillOwnership = "owned" | "foreign";
+export interface SkillProvenanceMap {
+    /** Repo-relative lockfile path that was read, or null when absent. */
+    lockfile: string | null;
+    /** Parsed lock entries keyed by slug (empty when no lock / empty lock). */
+    entries: Record<string, SkillLockEntry>;
+    /** Non-fatal parse / version problems. */
+    warnings: string[];
+}
+/**
+ * External lock provenance is treated as foreign (synced) by default.
+ * `local` stays owned so same-repo installs (e.g. `skills add .`) keep linting.
+ */
+export declare function isForeignLockSourceType(sourceType: string): boolean;
+export declare function loadSkillsLock(root: string, lockfileRel?: string): SkillProvenanceMap;
+/**
+ * Classify a discovered skill slug.
+ * Precedence: config ownedSlugs → config foreignSlugs → lock provenance → owned default.
+ */
+export declare function classifySkillOwnership(slug: string, provenance: SkillProvenanceMap, ownership?: SkillOwnershipConfig): SkillOwnership;
+export declare function resolveOwnershipForSlugs(slugs: string[], provenance: SkillProvenanceMap, ownership?: SkillOwnershipConfig): {
+    ownedSlugs: string[];
+    foreignSlugs: string[];
+};

package/dist/audit/core/skill-roots.d.ts

@@ -0,0 +1,54 @@
+import type { SkillOwnershipConfig } from "../config/types.ts";
+import { type SkillProvenanceMap } from "./skill-provenance.ts";
+export declare const NESTED_SKILL_ROOTS: readonly [".claude/skills", ".agents/skills"];
+/** Directories at repo root that must not be treated as flat skill slugs. */
+export declare const FLAT_SKILL_DENYLIST: Set<string>;
+export type SkillRootKind = "nested" | "flat";
+export interface SkillRoot {
+    kind: SkillRootKind;
+    relPath: string;
+}
+export interface SkillIndex {
+    roots: SkillRoot[];
+    /** All discovered skill slugs (owned + foreign) — used for link resolution. */
+    slugs: string[];
+    /**
+     * Slugs that exist as flat trees (`<slug>/SKILL.md` at repo root).
+     * Flat path matching must use this set — never the union `slugs` — so a
+     * nested-only foreign slug cannot poison top-level dirs with the same name.
+     */
+    flatSlugs: string[];
+    /** Skill slugs whose bodies this repo owns and should lint. */
+    ownedSlugs: string[];
+    /** Synced / lockfile foreign skills — skipped for body lint. */
+    foreignSlugs: string[];
+    provenance: SkillProvenanceMap;
+}
+export declare function detectSkillRoots(root: string): SkillRoot[];
+export declare function buildSkillIndex(root: string, ownership?: SkillOwnershipConfig): SkillIndex;
+export declare function isOwnedSkillSlug(index: SkillIndex, slug: string): boolean;
+export declare function isForeignSkillSlug(index: SkillIndex, slug: string): boolean;
+export declare function resolveSkillPath(index: SkillIndex, root: string, slug: string): string | null;
+export declare function isSkillPath(relPath: string, index: SkillIndex): boolean;
+export declare function skillSlugForPath(relPath: string, index: SkillIndex): string | null;
+/** True when path is under a skill tree classified foreign for body lint. */
+export declare function isForeignSkillPath(relPath: string, index: SkillIndex): boolean;
+export declare function slugFromSkillPath(relPath: string): string | null;
+/**
+ * Resolve a skill slug from a read path.
+ * Covers `…/SKILL.md`, nested `.claude|agents/skills/<slug>/**`, and flat
+ * `<slug>/references/**` (optionally verified via workspaceRoot + SKILL.md).
+ */
+export declare function slugFromPath(filePath: string, workspaceRoot?: string): string | null;
+export declare function skillCollectAugments(index: SkillIndex): string[];
+/**
+ * Repo-relative markdown paths for owned skill trees (SKILL.md + references/**,
+ * including under scan.exclude). Used by validate --base policy prove so skill-scoped
+ * prose still runs against the full skill body, not just SKILL.md.
+ *
+ * Walks each nested root independently so the same slug under both `.claude/skills`
+ * and `.agents/skills` (distinct dirs) is fully covered — not first-wins only.
+ */
+export declare function listSkillMarkdownPaths(root: string, index: SkillIndex): string[];
+export declare function listSkillSlugs(index: SkillIndex): string[];
+export declare function listOwnedSkillSlugs(index: SkillIndex): string[];

package/dist/audit/core/ssot-collect.d.ts

@@ -0,0 +1,16 @@
+import { type SsotEntry, type SsotForm } from "./ssot.ts";
+export interface SsotFileEntry extends SsotEntry {
+    path: string;
+}
+export interface CollectSsotResult {
+    entries: SsotFileEntry[];
+    /** Path → dual forms or malformed detail for the ssot rule. */
+    errors: Array<{
+        path: string;
+        kind: "dual" | "malformed";
+        detail: string;
+        forms?: SsotForm[];
+    }>;
+}
+/** Collect opt-in SSOT membership from scanned markdown abs paths. */
+export declare function collectSsotEntries(files: string[], root: string): CollectSsotResult;

package/dist/audit/core/ssot-fit.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Lexical SSOT↔evidence fit (no LLM).
+ * Conservative stemming, H1/lead/body evidence, overlap, phrase-as-explanation, better-match.
+ */
+export declare const DEFAULT_SSOT_OVERLAP_MIN = 0.35;
+export declare const DEFAULT_BETTER_MATCH_MARGIN = 0.15;
+export declare function lightStem(token: string): string;
+export declare function contentTokens(text: string): string[];
+export declare function uniqueContentTokens(text: string): string[];
+/** First ATX H1 text, if any. */
+export declare function extractH1(content: string): string;
+/** First non-empty prose paragraph after stripping SSOT/meta/code. */
+export declare function extractLeadParagraph(content: string): string;
+export declare function buildEvidenceText(content: string): string;
+export declare function ssotEvidenceOverlap(summary: string, evidence: string): number;
+/** Longest contentful n-gram from summary (prefer 3, else 2). */
+export declare function longestSummaryPhrase(summary: string): string[] | null;
+export declare function evidenceHasPhrase(evidence: string, phrase: string[]): boolean;
+export interface FitOptions {
+    overlapMin?: number;
+    betterMatchMargin?: number;
+    phraseCheck?: boolean;
+}
+export interface FitFile {
+    path: string;
+    summary: string;
+    content: string;
+}
+export type FitIssueKind = "short" | "weak" | "better-match";
+export interface FitIssue {
+    kind: FitIssueKind;
+    path: string;
+    message: string;
+    otherPath?: string;
+}
+export declare function evaluateSsotFit(files: FitFile[], options?: FitOptions): FitIssue[];
+/** @deprecated Prefer ssotEvidenceOverlap — kept for callers that pass raw body. */
+export declare function ssotBodyOverlap(summary: string, body: string): number;

package/dist/audit/core/ssot.d.ts

@@ -0,0 +1,28 @@
+export type SsotForm = "comment" | "visible" | "legacy";
+export interface SsotEntry {
+    summary: string;
+    form: SsotForm;
+}
+export type SsotParseResult = {
+    status: "ok";
+    entry: SsotEntry;
+} | {
+    status: "none";
+} | {
+    status: "dual";
+    forms: SsotForm[];
+} | {
+    status: "malformed";
+    detail: string;
+};
+/** @deprecated Prefer parseSsot — presence-only legacy check. */
+export declare const SOURCE_OF_TRUTH_BANNER_RE: RegExp;
+export declare const SOURCE_OF_TRUTH_BANNER_LINE_RE: RegExp;
+/**
+ * Parse SSOT from markdown. Opt-in: `none` is valid (file not in catalog).
+ * Dual encodings (comment + visible, etc.) or empty payloads are errors.
+ */
+export declare function parseSsot(content: string): SsotParseResult;
+/** Rewrite a legacy banner to the preferred HTML comment form. */
+export declare function rewriteLegacySsotToComment(content: string): string | null;
+export declare function preferredSsotComment(summary: string): string;

package/dist/audit/fix/anchors.d.ts

@@ -0,0 +1,6 @@
+import type { AuditContext } from "../core/context.ts";
+import type { FixEdit } from "../core/fix.ts";
+declare function replaceExactLinkTarget(content: string, from: string, to: string): string;
+export declare function collectAnchorFixes(ctx: AuditContext): FixEdit[];
+/** Exported for unit tests. */
+export { replaceExactLinkTarget };

package/dist/audit/fix/doc-meta.d.ts

@@ -0,0 +1,4 @@
+import type { AuditContext } from "../core/context.ts";
+import type { FixEdit } from "../core/fix.ts";
+export declare function bumpDocMetaLastReviewed(content: string, gitDate: string): string | null;
+export declare function collectDocMetaFixes(ctx: AuditContext): FixEdit[];