Repository navigation
Conversation
A scan tool (not a task list) for holding new designs against the durable directions of v4 — the goals/invariants a design must not drop, circumvent, or antagonize. Each item is a conformance question with a battle-tested circumvention "tell" (✗); each cluster cites its authority (THESIS / INVARIANTS / ROADMAP / MODELING / ctrl planning docs) and defers to it — this is a derived index, not a parallel ledger. Covers: the 7 fast-scan questions; A identity (closed/total typed graph, structural correctness, compiler-as-homomorphism, coercion=emit=ingest, six-connectives/five-behaviors, epistemic stacking, fail-closed, decidability); B homomorphism & bidirectionality (emit↔ingest via one find_witness, three surfaces, round-trip faithfulness, witness-or-located-refusal); C programmatic access read/write roof (real reflection by execution, not metaprogramming); D substrate modeling (files out of pipeline, construction>convention, grounding/ fact-bundles, names/homes/parents, no hand-rolled derived ops, layer DAG); E enforcement & opacity keystone; F measurement discipline (consumer invariant, green-for-right-reason, no-bridge-as-steady-state, tests-as-data, white-box=DELETE); G spine & sequencing; H product & payoff (omni-emission Shape A/B, audience duality, adoption by economics). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
briansrls
pushed a commit
that referenced
this pull request
Jun 7, 2026
…s, add reference-resolver gate Establishes the single-authority rule for docs (one fact, one canonical home; every other mention links, never restates) — P2/M2 applied to prose. - Refreshes docs/thesis/doc-authority.md from a stale docs/thesis-only contract (its prior version cited a ROADMAP structure — "Release R1 Program", lane table, tracked-debt ledger at fixed line numbers — that no longer exists) into the whole-tree doc map + rule, with the sound mode-tagging discipline kept. - Fold-DELETEs the two duplicate maps (THESIS "How the docs connect", ROADMAP "How to read the tree") to one-line links to doc-authority.md. - Adds scripts/check_doc_refs.py — the construction-tier detection: every Markdown reference must resolve. Census: 99 dangling refs across 87 files; per the touch-driven discipline those clear on touch, not by sweep. Fixes ROADMAP's own 2 dead links (the doc touched here). CI wiring (--changed origin/main) pending operator OK per the CI single-authority rule. Scoped to the ratified W1 core. Tracked follow-ups in the same sub-lane: coercion-mismatch taxonomy re-home (ROADMAP -> docs/design), planning/ -> ctrl per-doc, DIRECTION-CHECKLIST inline authority refs (after #4518 merges), ci.yml wiring. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
briansrls
pushed a commit
that referenced
this pull request
Jun 7, 2026
…the reference gate into CI Combines PR #4518 (DIRECTION-CHECKLIST.md) into this PR so the doc-direction work is one change (operator: "put 4518 and 4519 together so we don't miss it"). - DIRECTION-CHECKLIST.md added with a per-item authority ref ("-> home") on every item, proving it is a deferring view, not a 9th authority (operator ask). Refs are plain-text section pointers, not links -- terse, and they don't create 40 new link-maintenance points the reference gate would police. - docs/thesis/doc-authority.md: DIRECTION-CHECKLIST promoted from in-flight [target] to a live link (it's now in this PR). - .github/workflows/ci.yml: new doc_refs job runs scripts/check_doc_refs.py --changed origin/main on every non-draft PR and rolls into the `ci` aggregator (fail-closed). Touch-driven: a touched doc with an unresolved reference fails the gate -- no repo-wide sweep, no ratchet baseline. Promoting doc_refs to a branch-protection required check is the operator's step. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
Author
briansrls
added a commit
that referenced
this pull request
Jun 7, 2026
…ence-resolver gate (#4519) * WIP: mgmt * docs: consolidate doc authority — one rule, fold-DELETE duplicate maps, add reference-resolver gate Establishes the single-authority rule for docs (one fact, one canonical home; every other mention links, never restates) — P2/M2 applied to prose. - Refreshes docs/thesis/doc-authority.md from a stale docs/thesis-only contract (its prior version cited a ROADMAP structure — "Release R1 Program", lane table, tracked-debt ledger at fixed line numbers — that no longer exists) into the whole-tree doc map + rule, with the sound mode-tagging discipline kept. - Fold-DELETEs the two duplicate maps (THESIS "How the docs connect", ROADMAP "How to read the tree") to one-line links to doc-authority.md. - Adds scripts/check_doc_refs.py — the construction-tier detection: every Markdown reference must resolve. Census: 99 dangling refs across 87 files; per the touch-driven discipline those clear on touch, not by sweep. Fixes ROADMAP's own 2 dead links (the doc touched here). CI wiring (--changed origin/main) pending operator OK per the CI single-authority rule. Scoped to the ratified W1 core. Tracked follow-ups in the same sub-lane: coercion-mismatch taxonomy re-home (ROADMAP -> docs/design), planning/ -> ctrl per-doc, DIRECTION-CHECKLIST inline authority refs (after #4518 merges), ci.yml wiring. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * WIP: mgmt * docs+ci: combine direction-checklist into the consolidation PR; wire the reference gate into CI Combines PR #4518 (DIRECTION-CHECKLIST.md) into this PR so the doc-direction work is one change (operator: "put 4518 and 4519 together so we don't miss it"). - DIRECTION-CHECKLIST.md added with a per-item authority ref ("-> home") on every item, proving it is a deferring view, not a 9th authority (operator ask). Refs are plain-text section pointers, not links -- terse, and they don't create 40 new link-maintenance points the reference gate would police. - docs/thesis/doc-authority.md: DIRECTION-CHECKLIST promoted from in-flight [target] to a live link (it's now in this PR). - .github/workflows/ci.yml: new doc_refs job runs scripts/check_doc_refs.py --changed origin/main on every non-draft PR and rolls into the `ci` aggregator (fail-closed). Touch-driven: a touched doc with an unresolved reference fails the gate -- no repo-wide sweep, no ratchet baseline. Promoting doc_refs to a branch-protection required check is the operator's step. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs+ci: generate the actual doc-chain diagram into doc-authority.md check_doc_refs.py gains a graph mode: it renders the doc *chain* (which doc references which) as a Mermaid diagram computed from the real Markdown links — not hand-drawn — so the "actual chain" can be checked against the declared authority DAG instead of trusted. - --graph prints the Mermaid block (36 nodes / 93 edges over root + docs/**) - --write-graph regenerates the block embedded in docs/thesis/doc-authority.md - --check-graph fails if the embedded block is stale (drift gate) doc-authority.md gains a "The doc chain as it actually is (generated)" section holding the diagram between do-not-hand-edit markers. The doc_refs CI job now also runs --check-graph, so the diagram cannot silently drift from the link structure. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * WIP: mgmt * WIP: mgmt * docs: strip dangling subdoc citations from INVARIANTS.md + MODELING.md The two biggest rule docs cited ~61 subdocs (docs/invariants/*, docs/modeling/*, docs/design-*, docs/debt/*, _internal/*) that don't exist -- the rationale they pointed at was either inline or never authored. Per the operator's err-toward-deletion call: - INVARIANTS.md: removed 6 inline dead citations, dropped the entirely-dead "Subdoc" column from the appendix ID table (kept ID / principle / short-form + the #id anchors used by "violates C-8"-style refs), and trimmed the Pointers section to the one live target (docs/thesis/). - MODELING.md: rewritten to the genuine slim rule surface -- M1-M10 and every principle statement verbatim; removed all dead "See docs/modeling/X" pointers and the empty Exemplary-models / Per-file-findings / Deleted-files / Known-future-work / Appendix scaffolding sections (which existed only to point at nonexistent subdocs). No rule text changed; only dead pointers and empty scaffolding removed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: DIRECTION-CHECKLIST v1.1 — THESIS/INVARIANTS gap audit Add scannable items for dependency-graph default parallelism, ownership, two groundings, CX/structural-termination checker, grounding completeness, model-before-implement gate, map-vs-territory discipline, and single doc authority. Fast scan grows to 8 questions (grounding + load-bearing gate). Co-authored-by: Cursor <cursoragent@cursor.com> * WIP: mgmt * WIP: Emit-generalization SCOPING phase (DESIGN-ONLY, no-GO; operator 'get wor * docs(ci): address #4519 manager review — split doc_refs CI gate - Revert ci.yml doc_refs job + aggregator wiring (hold for operator GO follow-up) - doc-authority: script [live], CI wiring [target]; remove stale [proposed] drift Co-authored-by: Cursor <cursoragent@cursor.com> * docs(authority): flip CI-wiring status [proposed] -> [live] Review (still-raven-546): doc-authority.md Enforcement still read the CI wiring as [proposed] / "pending operator OK", but this PR wires doc_refs into the ci aggregator (fail-closed) and the operator authorized it in-session. The doc now matches what it ships. (check_doc_refs.py resolves references, not status tags, so this drift slipped its own net -- caught in review.) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * WIP: mgmt * WIP: Emit-generalization SCOPING phase (DESIGN-ONLY, no-GO; operator 'get wor * docs: strip remaining dangling citations (7 component/template/historical files) Completes the dangling-reference cleanup so the whole tree resolves (0 across 88 docs) and the doc_refs gate is green repo-wide -- no pre-existing-violation surprises for future PRs that touch these files. - README.md: dropped dead docs/v3-spec.md + docs/v4-compilation-milestones.md citations. - src/v2/tests/testing-strategy.md: fixed wrong-depth INVARIANTS.md path (../ -> ../../../), dropped stale "§Verifiability Invariant" anchor (folded into P4). - src/v3/compiler/benches/tier3_fixtures/README.md: dropped dead r3-pb brief link. - dsl/ctrl/README.md: dropped dead r4-ctrl audit/plan/brief links (planning lives in ctrl). - src/v3/DOWNSTREAM_REQUIREMENTS.md: dropped dead docs/history + docs/design-m2 links (kept the live ROADMAP.md ref). - .github/PULL_REQUEST_TEMPLATE.md: delinked the dead _internal/{INVARIANTS,ROADMAP}_OPS.md citations (internal-repo docs absent here) to backtick text. - dsl/std/runtime/bin_shims/README.md: delinked the dead r3-pb briefs + design-pb-runtime-interpreter.md citations (frozen-v3 framework placeholder). Delete-by-default per operator; live links preserved. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * WIP: Emit-generalization SCOPING phase (DESIGN-ONLY, no-GO; operator 'get wor * WIP: mgmt * WIP: Emit-generalization SCOPING phase (DESIGN-ONLY, no-GO; operator 'get wor * WIP: mgmt * WIP: Emit-generalization SCOPING phase (DESIGN-ONLY, no-GO; operator 'get wor * WIP: mgmt * WIP: Emit-generalization SCOPING phase (DESIGN-ONLY, no-GO; operator 'get wor * WIP: mgmt * WIP: Emit-generalization SCOPING phase (DESIGN-ONLY, no-GO; operator 'get wor * WIP: mgmt * WIP: mgmt * docs: address review (cursor/composer-2.5) — delete dead refs, don't delink The prior pass delinked dead Markdown links to bare backtick paths, which sidesteps check_doc_refs.py (it only checks [text](path) links) and leaves dead prose pointers. Fixing properly: - src/v3/DOWNSTREAM_REQUIREMENTS.md: removed the self-contradiction left by the strip ("was pruned from this file" ... "Retained there for audit traceability") and the two remaining prose references to the nonexistent docs/history enumeration file. - dsl/std/runtime/bin_shims/README.md: replaced the dead-ref scaffolding (frozen-v3 PB-runtime program; all referenced briefs/design docs were deleted in #4192) with a concise stub keeping only the live anchors (bin_shim.dag, process.dag, INVARIANTS). - .github/PULL_REQUEST_TEMPLATE.md: reverted to main (un-touched). Its dead _internal/* + briefs/debt references are pre-existing main debt for a wholesale-deleted internal apparatus; a proper trim of the v3-census-gate sections is a separate process-template decision, not a delink in this PR. Touch-driven gate leaves untouched-file debt alone. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Brian Searls <briansearls1@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
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.
What
Adds
DIRECTION-CHECKLIST.mdat repo root — a scan tool (not a task list) for holding any new design/brief/PR against the durable directions of v4: the goals and invariants a design must not drop (silently omit), circumvent (technically pass without doing the real thing), or antagonize (work against).Shape
✗) — scanning for the anti-pattern is usually faster than proving the positive.THESIS/INVARIANTS/ROADMAP/MODELING/ ctrlgoals-by-horizon) and the doc explicitly defers to them — if it disagrees with an authority, the authority wins and this file is the bug. It points at facts, it doesn't restate them (per the ledger standing principle inCLAUDE.md).goals-by-horizon(the when/what); this is the must-not-violate.Contents
find_witness) · C programmatic-access read/write roof (real reflection by execution, not metaprogramming) · D substrate modeling · E enforcement & opacity keystone · F measurement discipline · G spine & sequencing · H product & payoffReconciles two independently-authored drafts (operator's v4-specific version + a thesis-spine completeness pass): adds the substrate-shape / epistemic-stacking / fail-closed / decidability identity items (A5–A8), the grounding / naming / DFS / no-hand-rolled-derived-op modeling tells (D6–D8), the dissolution + tests-as-data + white-box-DELETE discipline (F8–F10), and audience-duality/adoption-by-economics (H6).
Docs-only; no code paths touched.
🤖 Generated with Claude Code