@csark0812/skeleton 1.5.7 → 1.6.1

package/README.md

@@ -1,12 +1,12 @@
 # Skeleton
 
-**Source of truth for** Package overview.
+<!-- source-of-truth: Package overview -->
 
-<!-- doc-meta: owner=eng | last-reviewed=2026-07-17 -->
+<!-- doc-meta: owner=eng | last-reviewed=2026-08-16 -->
 
 Agent repos get messy fast. Skills get copied around, docs disagree, links go stale, and nobody remembers which file is actually canonical.
 
-Skeleton is an SSOT linter for that layer. Define the contract once; Skeleton checks it locally and in CI. If a canonical doc disappears, a registry drifts, a skill index stops matching disk, or a generated reference gets edited by hand, the audit fails before merge.
+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 generated reference gets edited by hand, the audit fails before merge.
 
 Think ESLint — for the docs and skills your agents rely on.
 
@@ -20,7 +20,7 @@ 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, missing registry rows, stale doc-meta, banned artifacts |
+| 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                                 |
 | Pre-commit + CI gate                                    | `--staged` pre-commit + `--base` CI gate                                               |
 
@@ -36,7 +36,7 @@ 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 registry / conflict structure and context profile.
+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.
 
 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.
 
@@ -50,7 +50,7 @@ Full method: [refs/llm-harness.md](refs/llm-harness.md). Suites: [agent-suites/R
 
 On tasks that depend on an intact SSOT, the clean fixture was both more accurate and cheaper:
 
-- **Contested grounding** — In every paired run, clean settled on the registry canonical; messy never did (McNemar p = 0.002). Clean hops the registry; messy thrashes across conflicting docs.
+- **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).
 - **Token cost** — Across grounding tasks, messy used a median **~312k** more tokens than clean (bootstrap 95% CI on the mean excludes 0). Pass rate alone understates the gap: messy can still luck into an answer while spending far more.
 
@@ -76,50 +76,59 @@ npm install -D @csark0812/skeleton
 npx skeleton init --skills
 ```
 
-That writes `.skeleton/`, adds the validation scripts, and wires customize hooks for Cursor, Claude Code, and Codex.
+That writes `skeleton.toml`, ensures `.skeleton/customize/`, adds validation scripts, and may wire **optional** customize hooks for Cursor, Claude Code, and Codex.
 
-Edit `.skeleton/config.yaml` for your repo layout, then verify:
+Edit `skeleton.toml` for your repo layout, then verify:
 
 ```bash
-npx skeleton audit self
+npx skeleton catalog
+npx skeleton audit docs
 ```
 
 Flag details: [install](docs/developer/install.md).
 
 ## What it checks
 
-- **Registry integrity** — `.skeleton/registry.md` topic → canonical file pointers; banner format on registered docs
+- **SSOT markers** — opt-in `source-of-truth` (comment or visible); dual/malformed forms fail; legacy banners accepted
+- **Near-duplicate docs** — shingle overlap + duplicate SSOT summaries (warn / `--strict`)
+- **SSOT summary fit** — heuristic overlap between the one-liner and the body (warn / `--strict`)
 - **Link audit** — broken refs, skill links, anchors in scanned markdown
 - **Skill index** — disk matches taxonomy READMEs in detected skill roots
-- **Banned paths** — session artifacts and other files that must not exist
+- **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 index and registry-listed files
+- **Doc meta + stale dates** — owner and `last-reviewed` on indexes and SSOT-bearing files
 - **Prose policy** (optional plugins) — YAML pattern rules; idle with no plugins
 - **Shell / JSON syntax** — lightweight checks on changed `.sh` and `.json` files
 
+Agents skim `.skeleton/catalog.md` (generated, gitignored) before opening full papers.
+
 Skeleton doesn't replace your code gates. Keep TypeScript, Python, Nx, pytest, and the rest in the repo that owns them.
 
-## The `.skeleton/` contract
+## The contract
+
+Config lives in **`skeleton.toml`** at the repo root (preferred). Optional under `.skeleton/`:
 
 ```
+skeleton.toml          # scan perimeter, deny.paths, docsLint, …
 .skeleton/
-├── config.yaml      # scan perimeter (required)
-├── registry.md      # topic → canonical file (required)
-├── plugins/         # optional consumer audit plugins (.ts + built .mjs)
-└── customize/       # project-specific skill overrides (optional)
+├── catalog.md         # generated by `skeleton catalog` (gitignored)
+├── plugins/           # optional consumer audit plugins (.ts + built .mjs)
+└── customize/         # project-specific skill overrides (optional)
     └── code-review.md
 ```
 
-Every canonical doc carries a banner:
+Legacy `.skeleton/config.yaml` still loads when no TOML is present.
+
+Every canonical doc opts into the catalog with a marker:
 
 ```markdown
-**Source of truth for** Backend API conventions.
+<!-- source-of-truth: Backend API conventions -->
 ```
 
-Register it:
+Then refresh the agent index:
 
 ```bash
-skeleton register docs/developer/api.md
+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.
@@ -128,8 +137,8 @@ Synced skills stay pristine. Project overrides live in `.skeleton/customize/<slu
 
 ```bash
 skeleton init [--skills] [--force-hooks]
-skeleton register <path> [--topic=…]
-skeleton audit docs|skills|self [--strict] [--paths=a,b] [--fix[=doc-meta|anchors]] [--dry-run]
+skeleton catalog [--check]
+skeleton audit docs|skills|self [--strict] [--paths=a,b] [--fix[=doc-meta|anchors|ssot]] [--dry-run]
 skeleton build-plugin [path] [--check]
 skeleton validate changed [--staged | --base <ref>] [paths…]
 skeleton references sync|check