feat(0.2): docs-linkcheck binary + schema field tiers (Tracks 9.8/9.12)#151
Open
feat(0.2): docs-linkcheck binary + schema field tiers (Tracks 9.8/9.12)#151
Conversation
Two release-readiness deliverables that lift the contract Terrain
makes with adopters: links in user-facing docs go where they say
they go, and JSON fields carry an explicit stability promise.
Track 9.8 — Make docs-linkcheck
New `cmd/terrain-docs-linkcheck/main.go` walks docs/ and verifies
that every `[label](relative.md)` link resolves to a real file.
Skips external (http/https/mailto), same-page anchors (#foo),
and — by default — the docs/internal/ + docs/legacy/ subtrees
whose link discipline is inherited debt (run with
`-include-internal` to scan them anyway).
Resolves directory links to <dir>/README.md when present;
reports "directory link with no README.md" otherwise.
Wired into the Makefile as `make docs-linkcheck`. Same posture
as `make docs-verify` — fails with `::error::N broken links`
+ per-link source:line:target output suitable for CI annotation.
Initial run on the public docs surface caught 3 real broken
links (README.md → legacy/, quickstart.md → examples/,
release-notes.md → ../architecture/) — all fixed in this PR by
pointing at concrete files. The remaining 39 links inside
docs/internal/planning/ are pre-0.2 inherited debt, deliberately
skipped pending a separate cleanup PR.
Track 9.12 — Schema field stability tiers
New `docs/schema/FIELD_TIERS.md` documents the three-tier
contract Terrain commits to per JSON field:
Stable — name + type + semantics won't change without a
major schema bump; safe for long-lived tooling
Beta — name + type stable for the next minor; semantics
may evolve as calibration corpora arrive
Internal — diagnostic / debug fields; treat as scratch space
Spells out concrete examples per tier (snapshotMeta.schemaVersion
is stable; signals[].confidence is beta; metadata.diagnostics.*
is internal); names the precedence order for telling a field's
tier (name pattern → x-terrain-tier annotation → this page);
defines the promotion path internal → beta → stable.
Adopter guidance section: pin the schemaVersion, defensively
read beta fields with fallbacks, never branch on internal.
`docs/schema/README.md` linked from the new page so adopters
reach the contract via the canonical schema entry point.
Verification: `make docs-linkcheck` passes; `make docs-verify`
clean; `go build ./cmd/terrain-docs-linkcheck/` clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
[INFO] Terrain — Informational only
Coverage gaps in changed code
Recommended tests1 test(s) selected via structural heuristics. 1 unit(s) remain uncovered. 1 impacted unit(s) have no covering tests in the selected set.
Limitations
Generated by Terrain · Targeted Test ResultsTerrain selected 1 test(s) instead of the full suite. |
Terrain AI Risk Review
Decision: PASS — AI surfaces are covered. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two release-readiness deliverables that lift the contract Terrain
makes with adopters:
cmd/terrain-docs-linkcheckbinary +make docs-linkcheckMakefile target. Walks docs/ and verifies every intra-repo
markdown link resolves. Caught + fixed 3 broken links in the
public docs surface.
docs/schema/FIELD_TIERS.mddefines Stable / Beta / Internaltiers per JSON field, with concrete examples and a promotion
path. Linked from
docs/schema/README.md.What changed
New code:
cmd/terrain-docs-linkcheck/main.go— link checker (~210 lines,zero deps)
New docs:
docs/schema/FIELD_TIERS.md— three-tier contract per JSON fieldEdited:
Makefile—docs-linkchecktarget wireddocs/README.md— fixed legacy/ → legacy/legacy-notes.mddocs/quickstart.md— fixed examples/ → examples/analyze-report.mddocs/release/release-notes.md— fixed ../architecture/ → 00-overview.mddocs/schema/README.md— added pointer to FIELD_TIERS.mdWhy these together
Both close release-readiness gaps the parity plan flagged: 9.8
gives CI a way to catch link rot before adopters do; 9.12 gives
adopters a clear contract for what they can build long-lived
tooling against. Both are docs/infra additions with no behavior
change.
Test plan
go build ./...cleanmake docs-linkcheckpasses — all public-surface linksresolve
make docs-verifyclean — manifest unchangedgo test ./...clean — no test impactWhat's NOT covered (intentional)
#section-name) — out of scope today;would need slug-aware heading parsing per markdown flavor
adds CI-time network dependency for diminishing returns
broken links there are skipped by default; cleanup is its own
PR. Run
make docs-linkcheckwith-include-internal(viathe binary directly) to see them.
Plan tracker
Closes Track 9.8 + 9.12 from the parity plan. Track 9 remaining:
9.1-9.6 + 9.7 (truth-verify) + 9.10 (memory bench). All
explicitly post-0.2.0-blocking but safe to land in either window.
🤖 Generated with Claude Code