@csark0812/skeleton 4.0.1 → 5.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 <!-- source-of-truth: Package overview -->
 
-<!-- doc-meta: owner=eng | last-reviewed=2026-09-02 -->
+<!-- doc-meta: owner=eng | last-reviewed=2026-09-13 -->
 
 <!-- review-deps: paths=src/cli.ts,package.json -->
 
@@ -10,7 +10,7 @@ Agent repos get messy fast. Skills get copied around, docs disagree, links go st
 
 Skeleton is an SSOT linter for that layer. Define the contract once; Skeleton checks it locally and in CI. If a canonical doc disappears, SSOT markers drift, a skill index stops matching disk, or a local link breaks, the audit fails before merge.
 
-Think ESLint — for the docs and skills your agents rely on. Primary CLI from `src/cli.ts`: `audit`, `validate`, `catalog`, `init`, and `build-plugin` (plus `customize` / `hook` when using overlays). Commands dispatch through that entry file.
+Think ESLint — for the docs and skills your agents rely on. Primary CLI from `src/cli.ts`: `audit`, `validate`, `catalog`, `init`, and `build-plugin`. Commands dispatch through that entry file.
 
 Skeleton is **not** a runtime agent harness. It doesn't execute tools, enforce permissions, or manage memory. It checks whether the repo around those systems still holds together.
 
@@ -78,7 +78,7 @@ npm install -D @csark0812/skeleton
 npx skeleton init --skills
 ```
 
-That writes `skeleton.toml`, ensures `.skeleton/customize/`, adds validation scripts, and may wire **optional** customize hooks for Cursor, Claude Code, and Codex.
+That writes `skeleton.toml`, adds validation scripts, and writes `.pre-commit-config.yaml`.
 
 Edit `skeleton.toml` for your repo layout, then verify:
 
@@ -119,9 +119,7 @@ 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
+└── plugins/           # optional consumer audit plugins (.ts + built .mjs)
 ```
 
 Legacy `.skeleton/config.yaml` still loads when no TOML is present.
@@ -138,18 +136,17 @@ Then refresh the agent index:
 skeleton catalog
 ```
 
-Synced skills stay pristine. Project overrides live in `.skeleton/customize/<slug>.md` and inject when the skill is read — no editing copied `SKILL.md` files.
+Edit synced skills in the owning toolbox repo. Consumer copies stay read-only.
 
 ## Commands
 
 ```bash
-skeleton init [--skills] [--force-hooks]
+skeleton init [--skills]
 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 customize resolve <slug>
 ```
 
 **Validate changed** routes git diffs to the right audit:
@@ -157,15 +154,15 @@ skeleton customize resolve <slug>
 | Path                                                                                | Action                                        |
 | ----------------------------------------------------------------------------------- | --------------------------------------------- |
 | Docs in scan perimeter                                                              | path-scoped audit                             |
-| Owned skill bodies (`SKILL.md` trees)                                               | exit 1 → run `audit skills`                   |
+| Owned skill bodies (`SKILL.md` trees)                                               | run `audit skills`                            |
 | 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                   |
 | Any repository file                                                                 | native gates where applicable + audit documents whose `review-deps` path or glob matched |
 
-Pre-commit: `skeleton validate changed --staged` (path-scoped, fast).
+Pre-commit: `skeleton validate changed --staged` (index bytes, coverage, owning papers).
 
-CI: `skeleton validate changed --base origin/main` (global rules first, then changed files).
+CI: `skeleton validate changed --base origin/main` (global rules first, then changed files, same coverage fail).
 
 ## Ecosystem
 
@@ -186,7 +183,6 @@ See [tiers](docs/tiers.md). Related work: [Toolbox](https://github.com/csark0812
 - [Validation](docs/developer/validation.md)
 - [Audit rules](docs/developer/audit.md)
 - [Plugins](docs/developer/plugins.md)
-- [Customize](docs/developer/customize.md)
 - [Authoring conventions](docs/authoring.md)
 
 ## Development
@@ -200,8 +196,8 @@ bun run check
 
 `bun run check` = lint + test + typecheck + build + `audit:self`.
 
-`validate:changed` does not replace code tests. It classifies code separately and also audits every scanned document whose `review-deps` declaration matches a changed file. Owned skill-body edits need `audit skills`. Code-only changes with no linked document still exit non-zero locally and point to native gates.
+`validate:changed` does not replace code tests. It classifies code separately and also audits every scanned document whose `review-deps` declaration matches a changed file. A coverage-candidate path with no owning paper fails on local and CI runs. Owned skill-body edits run the skills suite. `--staged` reads git index bytes.
 
 For code: `bun test`, `bun run typecheck`, `bun run build`.
 
-Optional: `brew install pre-commit` (or `pipx install pre-commit`), then `pre-commit install` to wire `.pre-commit-config.yaml`.
+`skeleton init` writes `.pre-commit-config.yaml`. Install [pre-commit](https://pre-commit.com/) once (`brew install pre-commit` or `pipx install pre-commit`), then `pre-commit install`.

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

@@ -8,10 +8,6 @@ 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.
@@ -24,6 +20,13 @@ export interface SkillOwnershipConfig {
     /** Force these slugs foreign even if absent from the lockfile / local. */
     foreignSlugs?: string[];
 }
+/** Files that must appear in at least one scanned document's review-deps. */
+export interface ReviewCoverageConfig {
+    /** Repo-relative globs that require an owning paper. Empty include disables the gate. */
+    include?: string[];
+    /** Globs removed from the coverage set. */
+    exclude?: 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. */
@@ -51,9 +54,9 @@ export interface SkeletonConfig {
     /** 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;
+    reviewCoverage?: ReviewCoverageConfig;
     docsLint?: DocsLintConfig;
     /**
      * Plugin entry paths relative to `.skeleton/` (e.g. `plugins/example.ts`).

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

@@ -1,5 +1,6 @@
 import type { SkeletonConfig } from "../config/types.ts";
 import type { PolicyFile } from "../policies/types.ts";
+import type { FileSource } from "./repo-files.ts";
 import { type SkillIndex } from "./skill-roots.ts";
 import type { SsotForm } from "./ssot.ts";
 import { type SsotFileEntry } from "./ssot-collect.ts";
@@ -30,6 +31,8 @@ export interface AuditContext {
     lockedSkillSlugs: Set<string>;
     /** Compiled prose policies from plugins (empty when no plugins / no policy globs). */
     policies: PolicyFile[];
+    /** Read document and dependency bytes from the worktree or the git index. */
+    fileSource?: FileSource;
 }
 export interface AuditOptions {
     root?: string;
@@ -42,5 +45,7 @@ export interface AuditOptions {
      * matches path-scoped / validate `--base` prove.
      */
     includeExcludedSkillTrees?: boolean;
+    /** When `index`, review-proof and coverage reads use `git show :path`. */
+    fileSource?: FileSource;
 }
 export declare function createContext(options?: AuditOptions): AuditContext;

package/dist/audit/core/repo-files.d.ts

@@ -0,0 +1,5 @@
+export type FileSource = "worktree" | "index";
+/** Read a repo-relative file from the worktree or the git index. */
+export declare function readRepoText(root: string, relPath: string, source?: FileSource): string | null;
+/** True when worktree bytes differ from HEAD, including new untracked files. */
+export declare function pathDiffersFromHead(root: string, relPath: string): boolean;

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

@@ -29,3 +29,4 @@ export declare function issue(rule: string, file: string, details: string | Issu
 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;
+export declare function isRereadIssue(item: Issue): boolean;

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

@@ -0,0 +1,18 @@
+import type { SkeletonConfig } from "../config/types.ts";
+import { type FileSource } from "./repo-files.ts";
+import type { SkillIndex } from "./skill-roots.ts";
+export declare const DEFAULT_REVIEW_COVERAGE_INCLUDE: string[];
+export declare const DEFAULT_REVIEW_COVERAGE_EXCLUDE: string[];
+export declare function reviewCoveragePatterns(config: SkeletonConfig): {
+    include: string[];
+    exclude: string[];
+};
+export declare function pathRequiresReviewCoverage(relPath: string, config: SkeletonConfig): boolean;
+export declare function collectReviewDependencyPatterns(input: {
+    root: string;
+    config: SkeletonConfig;
+    skillIndex: SkillIndex;
+    fileSource?: FileSource;
+}): string[];
+export declare function pathHasReviewOwner(relPath: string, patterns: string[]): boolean;
+export declare function collectReviewCoverageFiles(root: string, config: SkeletonConfig): string[];

package/dist/audit/rules/review-coverage.d.ts

@@ -0,0 +1,8 @@
+import type { AuditContext } from "../core/context.ts";
+import { type Issue } from "../core/report.ts";
+export declare function runReviewCoverageRule(ctx: AuditContext): Issue[];
+export declare const reviewCoverageRule: {
+    id: string;
+    global: boolean;
+    run: typeof runReviewCoverageRule;
+};