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            # ranks 1-2 still declare the split
grep -n 'editGuard' harness.config.mjs .claude/hooks/gate-package-edits.sh  # rank 3 enforcement split
gh issue view 1103 --json state                          # stale-row sweep still open?
grep -n -i 'squash' .claude/skills/github-tasks/SKILL.md AGENTS.md          # §3 precedent row