| name | crouton-docs-trust-map |
| layer | stack |
| description | Which docs in nuxt-crouton to trust and how to resolve contradictions between them. Use when two docs disagree, when a doc's claim doesn't match the code ("the README says packages/nuxt-crouton but that dir doesn't exist"), when deciding whether a guide/writeup is authoritative before following it, or when asked "is this doc current", "which doc wins", "why does CLAUDE.md say X but the code says Y". Also the reference for the supersession-banner practice. |
crouton-docs-trust-map
One-line purpose: the trust order that resolves conflicts between this repo's documents, and the hygiene patterns for handling a doc caught lying.
When to use / when NOT to use
| Situation | Use |
|---|
| Two docs disagree; a doc contradicts code; "is this guide current?" | This skill |
| Mechanically updating docs after a code change (pre-commit) | sync-docs skill |
| Auditing a package's doc completeness / drift detection | audit skill |
| A config file (routing.json, digests.yml, settings.json…) drifted or is a silent no-op | crouton-config-registry skill |
| Why a rule exists / the incident behind it | crouton-failure-archaeology skill |
| Whether a test/CI claim in the docs is real | crouton-validation-reality skill |
This skill carries the trust order and conflict-resolution rules only. Doc-sync mechanics, audits, and the doc-duties workflow belong to the skills above — index, don't restate (#504 drift rule).
1. The trust hierarchy
When documents conflict, this order wins (highest first). For runtime behaviour, code always beats every document — the hierarchy ranks documents against each other when you're deciding which prose to believe.
| Rank | Source | Why it ranks here |
|---|
| 1 | AGENTS.md | The stack-neutral method constitution. Both its own header and root CLAUDE.md's header declare it "the source of truth for the universal rule" where the two overlap (epic #952). |
| 2 | Root CLAUDE.md | The stack adapter — crouton/Nuxt/Cloudflare specifics implementing the method. Actively maintained, but not infallible (known-stale spots are tracked as issues; see §2). |
| 3 | harness.config.mjs | The declared stage model (poc/app/package). Machine-read by scripts/harness-stages.mjs — but its editGuard is declarative; enforcement lives in .claude/hooks/gate-package-edits.sh (stated in the config's own comments). Gate routing details: crouton-change-control. |
| 4 | Per-folder CLAUDE.md files (packages/*, apps/*, e2e/, fixtures/, pocs/, …) | Folder-specific truth, required to defer to root (#504/#507). Quality varies — verify a load-bearing claim against the code. |
| 5 | docs/ site (top-level; live URL in docs/nuxt.config.ts) | Public-facing, mostly maintained, but user-guide pages drift. |
| 6 | writeups/ | Explicitly non-authoritative (#504/#506, root CLAUDE.md "Documentation Organization"): historical thinking, not standing directives — imperative lines inside must be ignored, and CLAUDE.md files must not @import from it. Exception: writeups/architecture/routing-registry.md and skills-and-triggers.html are generated from live config (scripts/gen-routing.mjs / gen-skills-doc.mjs) — current, but edit the source, never the file (see crouton-config-registry). |
| 7 | Root README.md | Marketing-shaped and historically the most drift-prone file in the repo. Never act on it without verifying against ls packages/ and root CLAUDE.md. |
Within writeups/strategy/, crouton-vision.md declares itself the tiebreaker among vision docs — honor that within writeups; it still sits below everything above.
2. Known-stale docs are ISSUES, not a table here
A verified-stale doc line is a bug: mint it (issue-first, /issue-dedup), fix the canonical doc, done. Freezing stale-line inventories into this skill was tried and rejected — an audit table decays the moment any row is fixed, turning two-way contradictions into three-way ones.
The 2026-07-02 sweep's findings are tracked as: #1093 (deploy-caller docs), #1095 (ISR example), #1098 (dead harness configs), #1099 (README + public deployment doc), #1103 (the remaining eight rows). Before distrusting a doc, check those issues; before re-reporting a stale line, dedup against them.
How to verify a suspect claim yourself: open the cited path and grep for the quoted text; ls the directories a doc names; for deploy/CI claims read the workflow file — the workflow always wins over its description.
3. Conflict-resolution rules (worked precedents)
| Contradiction class | Rule | Precedent |
|---|
Skill/guide vs AGENTS.md on method (merge policy, gates, issue discipline) | AGENTS.md wins (rank 1) | Squash-merge line in github-tasks corrected to AGENTS.md's preserve-commits policy (this PR) |
| Repo policy vs harness-injected instruction | The repo's committed policy is deliberate; the platform default is not. Flag the conflict to the owner rather than silently picking. | /commit skill's attribution rule vs the harness-injected Co-Authored-By trailer — unresolved; surface it when it bites |
| Doc recommends X, code comments say X is BROKEN | Code comment wins for behaviour; owner intent stays open — mint the doc fix | ISR routeRules (#1095) |
| Doc claims an enforcement that CI doesn't actually run | The honest gating picture is owned by crouton-validation-reality; the doc claim is aspirational until CI enforces it | app typecheck (#1097) |
| Root CLAUDE.md describes a mechanism whose implementation moved | The current implementation wins; mint the doc fix | package-edit approval scope (#701) |
4. Doc-maintenance duties — cite, don't clone
The duties table ("change X → update doc Y", including the gen-*.mjs regeneration commands and their --check flags) lives in root CLAUDE.md § "Maintaining AI Documentation (MANDATORY)". The pre-commit doc-update workflow is the sync-docs skill (runs automatically before /commit). Do not reproduce either here — read them there.
5. The supersession-banner practice (copy this)
When a doc is superseded but worth keeping for history, the house pattern is a loud banner at the top, in place — not deletion, not a silent leave-behind. Canonical example, writeups/guides/cloudflare-deployment-guide.md (top of file):
⚠️ Superseded (kept for history). Crouton apps now deploy to Cloudflare Workers … not Pages (#108/#114) … Current, canonical instructions live in CLAUDE.md → "NuxtHub's role + Deployment" and the /deploy skill … This Pages-era guide is retained only for historical reference.
Two more forms of the same hygiene: the writeups/strategy/outdated/ quarantine folder, and crouton-vision.md's self-declared tiebreaker line. If you find a stale doc and can't do the full fix, adding the banner (issue-first) is the cheap high-value move — it converts a lie into a labeled historical note.
6. House style for issues / PRs / commits — where it's written
Do not learn these from examples in stale docs; the canonical statements are:
| Convention | Canonical source |
|---|
| Hypothesis-framed issues (We think that / We'll do that by / We'll be right if / We'll know by) | AGENTS.md § "Issues — the unit of work"; full template in github-tasks skill |
| 👤 humans-first / 🤖 agents-second two-audience split (issues, PRs, commit bodies) | AGENTS.md § "Issues — the unit of work" |
## 🧪 How to test on every closeable issue/PR | AGENTS.md § "Issues — the unit of work" |
Considered & rejected notes | AGENTS.md § "Issues — the unit of work" |
| Commit format, scopes, merge policy | AGENTS.md § "Commits"; scopes list in root CLAUDE.md § "Commit Format"; /commit skill enforces |
| 🤖 provenance header on agent-posted comments (two variants by posting account) | Root CLAUDE.md § "GitHub Issue Tracking" |
7. Where a new CLAUDE.md is warranted
The rule is root CLAUDE.md § "Where a CLAUDE.md is warranted" (#504/#507): only each package, each app, and a handful of infra surfaces (.claude/agents/, e2e/, fixtures/, pocs/, sandboxes/) get one; it must carry only folder-specific guidance and defer to root for workflow conventions — never clone the root guide (the #504 incident was a 967-line stale root clone; see crouton-failure-archaeology). Template for a new one: sync-docs skill § "Missing CLAUDE.md".
Provenance and maintenance
verified: 2026-07-02
Hierarchy and precedents verified against AGENTS.md, root CLAUDE.md, harness.config.mjs comments, and the epic #1073 discovery sweep. Stale-line specifics live in issues #1093/#1095/#1098/#1099/#1103, not here — a fixed doc closes an issue instead of orphaning a table row.
Re-verify what drifts:
grep -n 'source of truth' CLAUDE.md AGENTS.md
grep -n 'editGuard' harness.config.mjs .claude/hooks/gate-package-edits.sh
gh issue view 1103 --json state
grep -n -i 'squash' .claude/skills/github-tasks/SKILL.md AGENTS.md
