Documentation contradicts shipped behaviour: schema-discovery boundary, JSON version claim, and the stem-health check list

[pablontiv]

Description

Nine documentation statements across CLAUDE.md, README.md, docs/ and one shipped source string describe behaviour the binary does not have. They are grouped here because they share a root cause — doc surfaces were not updated when the discovery model, the health-check set, and the JSON envelopes changed — and because fixing them is one coherent editing pass.

The list is ordered by impact.

1. The schema-discovery boundary model is documented wrong, and it is the upstream cause of the most common runtime failure.
   internal/rules/discovery.go:70 (WalkUp) collects .stem files upward and terminates on stem.Root (discovery.go:99) or the filesystem root. It never consults .git. When the walk reaches the filesystem root without a root: true marker, the preflight turns that into a hard error on every governed command.
   Four doc sites still teach the old model:

   • CLAUDE.md:33 — ".stem file loading, walk-up discovery (target → .git root)". Factually wrong.
   • CLAUDE.md contains zero occurrences of root: true, "root marker", or "boundary" (grep -n -i "root: true\|root marker\|boundary\|\.git root" CLAUDE.md returns nothing). The single concept a new project must know is absent from the file contributors are told to read first.
   • README.md:114 — "Without an explicit marker, discovery continues to the filesystem root." It does not; the preflight makes it a hard error. README.md:109 frames the marker as one of two equally valid stopping conditions.
   • docs/validate.md:18 — "The walk continues to the filesystem root if no marker is found." Same false claim.
   • docs/explain.md:75 — "up to the root: true marker (or the filesystem root)" — stale parenthetical.

   internal/infer/schema_coverage.go:48 also ships the old model inside a user-facing inference message: "Directory contains %d markdown file(s) but no .stem schema (checked walk-up to .git root)". (Note: this branch requires WalkUp to fail for a scanned directory and was not reachable in testing — but the stale wording is in the shipped string either way, and the branch being unreachable is itself worth a look.)

   Consequence: users place a .stem at the repo root, expect it to work because the docs say discovery reaches the filesystem root, and instead hit a hard error on every command at once. Commit fb79448 began this cleanup; these sites were missed.

   Two .git walks do remain in the tree, and neither bounds discovery: internal/rules/discovery.go:174 (projectBoundaryHint, explicitly documented as advisory and used only by ProposeRootDirectory) and internal/migrate/source.go:58 (findGitRoot, used for git show). The docs describe the boundary as if it were projectBoundaryHint's job; it is not.

2. CLAUDE.md:56 "All JSON output carries "version": 1 for contract stability" is false. tree emits version: 2 (cmd/rootline/tree.go:96). A consumer written against this sentence and asserting version == 1 breaks on tree. The identical claim was already corrected in README.md by commit 08ba2f8; CLAUDE.md was not updated in the same pass. docs/tree.md:46 is correct.

3. CLAUDE.md:31 attributes working behaviour to an operation that does not exist. The file states that update_stem "now grows the .stem by creating field nodes for newly-observed fields (field_type/enum_values/required_field/constant_field), closing the analyze --incremental → schema apply loop". grep -rn 'update_stem' --include='*.go' cmd internal finds only a struct comment (cmd/rootline/schema.go:25) and a test fixture. No producer sets it: generateSchemaProposals emits only create_stem. No consumer handles it: cmd/rootline/schema.go:269 branches on create_stem alone, and anything else falls through with no error, no warning, and no skipped entry. The field-growth behaviour is real but lives in internal/infer.ApplySchemaInferences (internal/infer/apply.go:52-97), keyed on inference types. A reader implementing against CLAUDE.md emits update_stem proposals and watches them silently vanish.

4. docs/validate.md:35-46 documents three health checks that do not exist and omits four that do. The doc lists version-deprecated (line 43), domain-type-compat (line 44) and domain-missing-attrs (line 45). None appears in any Go file, test, or roadmap record. The real set from internal/rules/stemhealth.go is twelve: stem-files-exist (:56), yaml-valid (:69/:76), scope-match (:112), type-consistency (:140), enum-values (:161), rule-field-exists (:191), field-override (:221), aggregated-required (:244), aggregate-formula-coverage (:302), monotonic-violations (:355), unknown-check-keys (:377), nested-root-marker (:423). The doc omits four of them.
   docs/validate.md:42 additionally inverts the polarity of a real check: it says "aggregated-required — required fields have aggregate expressions", but stemhealth.go:244-252 warns precisely when a field is both required and aggregated ("required is auto-skipped on index files — consider removing required or using excludes"). A reader takes a warning as a requirement.

5. CLAUDE.md:33 says 11 stem-health checks; there are 12. The enumeration omits nested-root-marker (internal/rules/stemhealth.go:423), which is live and user-visible in validate --all output.

6. docs/describe.md documents two result keys the command never emits. docs/describe.md:38 shows a "levels" object, :62 shows a "structural" object, and :85 lists structural in the Sections table. internal/rules/describe.go (DescribeResult) has neither field. A consumer reading .levels or .structural always gets null. The prose at docs/describe.md:72-74 correctly describes layers and provenance, but the JSON example above it omits both — so the example is wrong in both directions.

7. docs/migrate.md:53 states a kind no code path produces, and omits a real key. The doc shows "kind": "rootline/migrate". The three real kinds are rootline/migrate-diff (internal/migrate/diff.go), rootline/migrate-rename (internal/migrate/rename.go) and rootline/migrate-batch (cmd/rootline/migrate.go). A consumer dispatching on kind against the doc never matches. The documented example also omits stem_path, which the real payload does carry.

8. docs/stats.md contradicts itself in the same file. Line 6: "rootline stats shows aggregate counts by estado and tipo frontmatter fields." Line 27: "stats is field-agnostic: it reports the total record count and makes no assumptions about which frontmatter fields exist." Line 52 confirms the two maps "are reserved in the output contract but are currently always empty". The binary settles it in favour of lines 27 and 52; line 6 is the stale one.

9. The JSON contract is not discoverable from the CLI, and the shapes are mutually inconsistent. CLAUDE.md sells the versioned contract as a feature, but no --help output for query, graph, validate, tree, or stats names a single JSON key (the only near-match is --limit's "limit number of results", which is prose). Meanwhile the top-level shapes disagree with each other:

   command	row collection	count/summary	notable keys
   query	rows	meta.count	—
   validate --all	results	summary	drift_warnings
   graph	nodes / edges	—	edge fields are source/target
   stats	—	total	by_lifecycle_state, by_record_type
   tree	root (nested)	root.total	—

   The predictable result is consumers guessing: .to/.from on graph edges (real: source/target), .files[] on validate (real: results), and treating query output as a top-level array (real: an object with rows). A contract that cannot be enumerated from the CLI is a contract in name only.

Steps to Reproduce

Build a self-contained fixture. Requires jq and a rootline on PATH.

rm -rf /tmp/rootline-repro && mkdir -p /tmp/rootline-repro/docs
cd /tmp/rootline-repro && git init -q .
cat > docs/.stem <<'EOF'
version: 2
scope:
  match: "*.md"
schema:
  estado:
    type: enum
    values: [Pending, Done]
EOF
printf -- "---\nestado: Pending\n---\n\n# a\n" > docs/a.md
printf -- "---\nestado: Done\n---\n\n# b\n" > docs/b.md

(1) Boundary model — a .stem inside a git repo, with no root: true:

$ rootline validate docs/a.md -o json
Error: Schema discovery reached the filesystem root without finding a declared boundary.

No .stem in this project declares where the project starts.

Fix: add this line to /tmp/rootline-repro/docs/.stem

  root: true

Discovery then stops there and never reads .stem files above it.
Run rootline in a terminal to be prompted and have this applied for you.

The git init is deliberate: a .git directory sits directly above docs/, and discovery walks straight past it to the filesystem root. README.md:114 and docs/validate.md:18 both state this cannot happen. Unblock the fixture for the rest of the steps:

printf 'root: true\n' >> docs/.stem

(2) tree emits version: 2:

$ rootline tree docs -o json | jq -c '{version,kind}'
{"version":2,"kind":"rootline/tree"}

(3) update_stem exists nowhere (run from a source checkout):

$ grep -rn 'update_stem' --include='*.go' cmd internal
cmd/rootline/schema.go:25:	Operation     string  `json:"operation"` // "create_stem", "update_stem", etc.
cmd/rootline/render_tables_test.go:70:			{ID: "p2", Operation: "update_stem", ...}

A struct comment and a test fixture. No producer, no consumer.

(4 and 5) Health-check names — the twelve real ones, from a source checkout:

$ grep -n 'Name:\s*"' internal/rules/stemhealth.go
56:			Name:    "stem-files-exist",
69:				Name:    "yaml-valid",
76:				Name:   "yaml-valid",
112:				Name:    "scope-match",
140:						Name:    "type-consistency",
161:					Name:    "enum-values",
191:						Name:    "rule-field-exists",
221:					Name:    "field-override",
244:					Name:   "aggregated-required",
302:					Name:    "aggregate-formula-coverage",
355:				Name:    "monotonic-violations",
377:				Name:    "unknown-check-keys",
423:				Name:    "nested-root-marker",

Twelve distinct names (yaml-valid appears at two call sites). version-deprecated, domain-type-compat, domain-missing-attrs are absent from the whole tree; CLAUDE.md:33 lists eleven and omits nested-root-marker.

(6) describe result keys:

$ rootline describe docs -o json | jq -c 'keys'
["aggregate","applies","derive","kind","layers","links","path","provenance","schema","scope","validate","version"]

No levels, no structural.

(7) migrate kind:

$ rootline migrate docs --dry-run -o json | jq -c '{version,kind,keys:(keys)}'
{"version":1,"kind":"rootline/migrate-diff","keys":["breaking_count","changes","kind","stem_path","total_count","version"]}

Kind is rootline/migrate-diff, not rootline/migrate; stem_path is present and undocumented.

(8) stats is field-agnostic:

$ rootline stats docs -o json | jq -c .
{"version":1,"kind":"rootline/stats","by_lifecycle_state":{},"by_record_type":{},"total":2}

(9) Contract discoverability:

$ for c in query graph validate tree stats; do
    echo -n "$c: "; rootline $c --help 2>&1 | grep -ci 'rows\|edges\|"kind"'
  done
query: 0
graph: 0
validate: 0
tree: 0
stats: 0

$ rootline graph docs -o json | jq -c '.edges[0]'
{"source":"a.md","target":"b.md","type":"reference","line":3}

Expected Behavior

• CLAUDE.md, README.md, docs/validate.md and docs/explain.md describe discovery as terminating at a root: true marker, and state plainly that reaching the filesystem root without one is a hard error. CLAUDE.md names root: true at least once.
• CLAUDE.md states that each payload carries its own version (the wording README.md already uses after 08ba2f8), not a blanket version: 1.
• CLAUDE.md describes the analyze → schema apply growth path by the mechanism that implements it, and does not name update_stem.
• docs/validate.md lists exactly the twelve health checks the binary implements, with correct polarity for aggregated-required.
• CLAUDE.md says 12 checks and enumerates nested-root-marker.
• docs/describe.md's JSON example matches DescribeResult exactly — including layers and provenance, excluding levels and structural.
• docs/migrate.md documents all three real kind values and the stem_path key.
• docs/stats.md states the field-agnostic behaviour once, consistently.
• The JSON keys of each command are enumerable from the CLI itself.

Actual Behavior

Every statement above is contradicted by the shipped binary, as captured in Steps to Reproduce. Item 1 is the load-bearing one: it is the documented model for a mechanism that every governed command depends on, and the doc's version of it cannot be made to work.

Environment

• Rootline version: dev (source build at b3c3d52). The doc text and the source lines cited are unchanged since 4.0.16, where the drift was first established.
• OS: macOS (darwin)
• Go version: 1.26+

Proposed fix

Documentation-only for items 1–8; item 9 needs a design decision.

• Boundary model — rewrite CLAUDE.md:33 (drop "target → .git root", state the root: true termination and the hard-error case), README.md:109 and README.md:114, docs/validate.md:18, docs/explain.md:75. Fix the shipped string at internal/infer/schema_coverage.go:48. While there, check whether that missing_schema branch is reachable at all — with the preflight in place, WalkUp returning empty for a scanned subdirectory looks unreachable, and if so the branch should be removed rather than reworded.
• Version claim — CLAUDE.md:56, adopt the README.md wording from 08ba2f8.
• update_stem — rewrite CLAUDE.md:31 to describe internal/infer.ApplySchemaInferences. Separately decide whether cmd/rootline/schema.go:269 should reject unknown operations instead of dropping them; today an unhandled operation is neither applied nor reported.
• Health checks — regenerate the docs/validate.md:35-46 list from internal/rules/stemhealth.go, correct the aggregated-required description, update the count in CLAUDE.md:33 to 12 and add nested-root-marker. A test asserting that the documented names match the Name: literals in stemhealth.go would stop this recurring.
• describe — regenerate the docs/describe.md JSON example from rules.DescribeResult.
• migrate — document all three kinds and stem_path in docs/migrate.md.
• stats — delete or rewrite docs/stats.md:6.
• Contract discoverability — needs a design decision first. Options are a rootline schema --contract style subcommand that dumps the envelope shape per command, per-command --help sections naming the top-level keys, or generated JSON Schema files checked into docs/. Normalizing the envelopes themselves (rows vs results, meta vs summary) is a breaking change and belongs in its own discussion, not in this issue.

Chained PR series

One work unit per PR.

1. Boundary model across all doc surfaces — CLAUDE.md, README.md, docs/validate.md, docs/explain.md. Single coherent edit; no code.
2. internal/infer/schema_coverage.go:48 message — code change, and the reachability question above. Separated from PR 1 because it may turn into a deletion rather than a reword.
3. CLAUDE.md version and update_stem claims — items 2 and 3. Both are single-paragraph rewrites in the same file.
4. Health-check documentation — docs/validate.md:35-46, CLAUDE.md:33, plus the drift test that keeps the list honest.
5. Per-command reference docs — docs/describe.md, docs/migrate.md, docs/stats.md. Mechanical, verified against captured output.
6. Contract discoverability — blocked on the design decision. Should not be bundled with 1–5.

PRs 1–5 are independent of each other and can land in any order. PR 6 should not start until the mechanism is agreed.

[pablontiv]

A remaining docs/migrate.md result-shape drift survives the fix described here: scaffold mode emits a fourth, unversioned shape that is absent from the three-kind table at docs/migrate.md:50-56.

Classification: documentation drift. The docs say verbatim: “migrate emits three kind values, one per mode”. A fresh valid v2 fixture reaches real record validation, then scaffold returns neither version nor kind:

rm -rf /tmp/rootline-migrate-shape && mkdir -p /tmp/rootline-migrate-shape
cd /tmp/rootline-migrate-shape
cat > .stem <<'YAML'
version: 2
root: true
scope:
  match: "*.md"
schema:
  title:
    type: string
    required: true
  summary:
    type: section
    heading: "## Summary"
    required: true
    default: "Describe this document."
YAML
printf '%s\n' '---' 'title: A' '---' '# A' > a.md
rootline validate --all . -o json
rootline migrate . --scaffold --dry-run -o json

Validation reaches a.md and reports only the expected missing summary requirement, proving this is not a version-0 or discovery failure. The scaffold command exits 0 and emits:

{"files_scaffolded":1,"sections_added":1,"details":[{"file":"a.md","heading":"## Summary","dry_run":true}]}

An agent dispatching on the documented version/kind contract cannot classify this successful result. The docs should include scaffold mode's actual shape, or the CLI should first decide to normalize it separately. Verified with Rootline 9.12.1, equal to master at 7d95e35, on macOS arm64.

[pablontiv]

A second remaining docs/migrate.md:50-56 result-shape drift belongs here: split mode also falls outside the documented three-kind contract.

Classification: documentation drift. The docs say verbatim, “migrate emits three kind values, one per mode”. A fresh version 2 fixture reaches real validation for all six records, then --split --dry-run -o json exits 0 but emits a plain multi-document YAML preview rather than any JSON envelope or kind:

rm -rf /tmp/rootline-migrate-split-shape
mkdir -p /tmp/rootline-migrate-split-shape/{E01-infra,E02-platform}/{F01-net,F02-store}
cd /tmp/rootline-migrate-split-shape
cat > .stem <<'YAML'
version: 2
root: true
scope:
  match: "*.md"
schema:
  id:
    type: sequence
    prefix: E
    digits: 2
  estado:
    type: enum
    required: true
    values: [Pending, Completed]
    severity: error
  tipo:
    type: enum
    values: [feature, historia]
    severity: warn
derive:
  slug: "slugify(estado)"
aggregate:
  total: "len(descendants)"
YAML
for e in E01-infra E02-platform; do
  printf '%s\n' '---' 'estado: Completed' '---' "# $e" > "$e/README.md"
  for f in F01-net F02-store; do
    printf '%s\n' '---' 'estado: Pending' 'tipo: feature' '---' "# $f" > "$e/$f/README.md"
  done
done
rootline validate --all . -o json
rootline migrate . --split --dry-run -o json

Validation reports "summary":{"total":6,"valid":6,"invalid":0,...}. The split output starts exactly as follows and continues with # --- E01-infra/.stem --- and # --- E02-platform/.stem --- sections:

# --- .stem ---
version: 2
root: true
scope:
  match: "*.md"

schema:
  id:
    type: sequence
    prefix: E
    digits: 2

An agent requesting -o json cannot dispatch on the documented versioned/kinded result contract. The docs should include split mode's actual preview shape and state that the output flag does not make it JSON, or output normalization should be considered separately. Verified with Rootline 9.12.1, equal to master at 7d95e35, on macOS arm64.

[pablontiv]

A third remaining result-shape drift in docs/migrate.md:81-106 belongs here: targeting a directory does not always produce the documented batch envelope.

Classification: documentation drift. The docs say verbatim, “Pointing migrate at a directory wraps those diffs in a batch envelope” and illustrate rootline/migrate-batch with stems_checked: 1. A fresh version 2 fixture reaches real validation, but a directory containing one discovered .stem returns the single-diff shape:

rm -rf /tmp/rootline-migrate-single-batch
mkdir -p /tmp/rootline-migrate-single-batch
cd /tmp/rootline-migrate-single-batch
cat > .stem <<'YAML'
version: 2
root: true
scope:
  match: "*.md"
schema:
  title:
    type: string
    required: true
YAML
cp .stem old.stem
cat > a.md <<'MARKDOWN'
---
title: Alpha
---
# Alpha
MARKDOWN
rootline validate --all . -o json
rootline migrate . --from old.stem --dry-run -o json

Validation proves the fixture is governed and valid:

{"version":2,"kind":"rootline/validate-batch","results":[{"version":1,"kind":"rootline/validate","path":"a.md","valid":true,"errors":[],"warnings":[]}],"structural":[],"stem_health":[],"drift_warnings":[],"notices":[],"summary":{"total":1,"valid":1,"invalid":0,"errors_count":0,"warnings_count":0,"drift_warnings_count":0,"structural_errors_count":0,"structural_warnings_count":0,"stem_health_errors_count":0,"stem_health_warnings_count":0,"stem_health_info_count":0}}

The directory migration exits 0 and emits:

{"version":1,"kind":"rootline/migrate-diff","stem_path":"/tmp/rootline-migrate-single-batch/.stem","changes":null,"breaking_count":0,"total_count":0}

The envelope therefore depends on the number of discovered stems, not merely whether the argument is a directory. A consumer following the documented directory contract will look for results and summary on a valid single-stem project and fail. The docs should state the cardinality rule or the CLI should normalize directory targets separately. Verified with Rootline 9.12.1, equal to master at 7d95e35, on macOS arm64.

[pablontiv]

A fourth remaining docs/migrate.md:35-46 drift belongs here: the change table says severity_changed breaking status “Depends” on whether severity was tightened or loosened, but the CLI marks both directions non-breaking.

Classification: documentation drift. The implementation and its focused test deliberately assign breaking: false to every severity change, so the reference table overstates direction-sensitive behavior.

A fresh version 2 fixture validates successfully before either migration comparison:

rm -rf /tmp/rootline-severity-change
mkdir -p /tmp/rootline-severity-change
cd /tmp/rootline-severity-change
cat > a.md <<'MARKDOWN'
---
status: Pending
---
# A
MARKDOWN
cat > old.stem <<'YAML'
version: 2
root: true
scope:
  match: "*.md"
schema:
  status:
    type: string
    required: true
    severity: warn
YAML
sed 's/severity: warn/severity: error/' old.stem > .stem
rootline validate --all . -o json
rootline migrate .stem --from old.stem --dry-run -o json
mv .stem old-error.stem
sed 's/severity: error/severity: warn/' old-error.stem > .stem
rootline validate --all . -o json
rootline migrate .stem --from old-error.stem --dry-run -o json

Both validations report "total":1,"valid":1,"invalid":0. Tightening warn to error emits:

{"kind":"severity_changed","field":"status","breaking":false,"before":"warn","after":"error","message":"field status severity changed from warn to error","affected_files":0}

Loosening error to warn also emits "breaking":false, with the before/after values reversed. In both envelopes, breaking_count is 0.

A consumer following the documented “Depends” classification cannot distinguish tightening from loosening because the result contract does not implement that distinction. The table should state the actual always-non-breaking behavior, or direction-sensitive classification should be designed as a separate CLI change. Verified with Rootline 9.12.1, equal to master at 7d95e35, on macOS arm64.

[pablontiv]

A remaining shipped agent-reference drift survived the stats contract cleanup described here and belongs with this documentation issue.

Classification: documentation drift. .claude/skills/rootline/ref-query.md:190 still says verbatim:

JSON contains counts grouped by estado, tipo, and total records.

Rootline 9.12.1 intentionally emits only the versioned kind and filtered total. A fresh version-2 fixture proves record validation before the stats command is judged:

FIXTURE="$(mktemp -d)"
cat > "$FIXTURE/.stem" <<'STEM'
version: 2
root: true
scope:
  match: "*.md"
schema:
  estado:
    type: enum
    values: [Pending, Completed]
    required: true
  tipo:
    type: enum
    values: [task, outcome]
    required: true
STEM
cat > "$FIXTURE/a.md" <<'DOC'
---
estado: Completed
tipo: task
---
# A
DOC
cat > "$FIXTURE/b.md" <<'DOC'
---
estado: Pending
tipo: outcome
---
# B
DOC
cat > "$FIXTURE/c.md" <<'DOC'
---
estado: Completed
tipo: task
---
# C
DOC

rootline validate --all "$FIXTURE" --field summary
rootline stats "$FIXTURE" -o json
rootline stats "$FIXTURE" --where "estado == 'Completed'" -o json

Validation exits 0 and reaches all three records:

{"drift_warnings_count":0,"errors_count":0,"invalid":0,"stem_health_errors_count":0,"stem_health_info_count":0,"stem_health_warnings_count":0,"structural_errors_count":0,"structural_warnings_count":0,"total":3,"valid":3,"warnings_count":0}

The unfiltered and filtered stats outputs are respectively:

{"version":2,"kind":"rootline/stats","total":3}
{"version":2,"kind":"rootline/stats","total":2}

No grouped estado or tipo dimensions exist. This is deliberate rather than a CLI defect: PR #135 removed the empty stats dimensions, cmd/rootline/stats.go tests exactly the three-key envelope, and docs/stats.md:28,41-51 now documents the field-agnostic contract correctly. The shipped .claude reference was missed by that synchronization pass.

Agents following the stale sentence will look for fields the runtime no longer emits instead of using --where to obtain field-specific slices. The reference should match docs/stats.md and describe total-only output plus filtering.

Verified with Rootline 9.12.1, corresponding to source revision 7d95e35.