The document grammar: REVIEW.md rules are bans and duties, ARCHITECTURE.md carries the statements

[borisbat]

Behavior change: the SDK bundle no longer carries any repo-internal rule or record document, and daslib comments are no longer formatter-stripped.

Every folder-scoped REVIEW.md now reads the same way: each rule is a ban ("never X - do Y instead", "a diff that adds X is a defect") or a duty ("a diff that changes X also does Y, in the same change"), in plain English. Sentences that described the system instead of binding a diff moved to the folder's architecture doc. REVIEW_COMMON.md states the new form; a new ARCHITECTURE_COMMON.md is the contract for the other side: architecture docs carry present-tense statements - charters, mechanisms, definitions, inventories, the exception ledger - with numbered citable sections. What happened lives in /history. The dasSpirv and dasMetal MASTERPLANs were split along that line: their implementation logs went to /history, the surviving reference content became each module's ARCHITECTURE.md, with stale claims corrected against the logs.

Two mechanical guards land with the grammar. LINT025: a folder whose .lint_config sets [docs] rule_docs_only = true may hold only REVIEW*.md, ARCHITECTURE*.md, and LAWS.md - armed for daslib and every module implementation folder. The install side: the root manifest gate and the bundle smoke test ban all rule/record document classes from the SDK; REVIEW_COMMON.md and ARCHITECTURE_COMMON.md at the install root are the two vendoring exceptions, and nano/ARCHITECTURE.md stops shipping. daslib's force_clean_comments is off: comments are harvested into the documents by process now, not deleted by the formatter.

Where to look: REVIEW_COMMON.md and ARCHITECTURE_COMMON.md for the contracts; utils/lint/main.das (the LINT025 folder pass) and daslib/lint_config.das (the [docs] reader, plus a leak fix in the config parser); the root CMakeLists.txt install gate; CLAUDE.md "The document system".

Validation, claims, ledger

Validation

• The full preflight run went red on four gates from local interference: a concurrent bundle-smoke run hid the build tree's lib/ mid-chain (that script's restore race is fixed in this PR). Every failed slice was revalidated targeted and green: the interp trio (lsp, mcp, dasfmt masks), the five JIT files, the sequence smoke, and the full AOT suite (13,060 tests, 13,059 passed, 1 skipped, 0 failed). CI proves the tip.
• Install gate + bundle smoke were run against a real fresh-configure install: gate passes, bundle layout and no internal rule/record docs both OK. Three smoke rows fail locally (vulkan-example, vulkan-tutorial, third-party licenses Z3/VULKAN_HEADERS/VOLK) because this box's build omits those vendored modules; the failing rows exercise nothing this diff touches.
• The lint suites ran green locally: tests/lint 41/41, utils/lint (including the new LINT025 tests) 12/12 in the fixture file, 78+ in the folder suite.
• A TDD audit with negative controls covered the code surface: 12 of 19 branches distinguished or controlled by tests; it found the install gate red on its own branch (nano/ARCHITECTURE.md), fixed here.
• An external codex round found two LINT025 invocation gaps (file positionals, das-free folders); both fixed with test arms.
• The 49-checklist translation was produced by per-file rewrite agents under a meaning-preserving charter, then audited by one fresh dragon per document; ~180 findings were judged and applied, with three dragon findings refuted against code and recorded.

Claims - stated, not tested

• The tightened bundle checks on a fully-provisioned release build are CI's to prove; the local bundle lacks the vulkan/Z3 modules.
• The platform matrix rides this PR's CI; the diff carries no C++ or engine-semantics change, so interp/JIT/AOT behavior is expected identical.

Not done

• ~25 RECOMMEND-LINT proposals from the dragon round (each would shrink a checklist to its weakening residue) are ledgered for a follow-up arc, not landed here.
• The [arch] annotation + enforce_arch lint (code-to-architecture-doc binding) and the comment-harvest trial are the next arcs, built on these contracts.
• Open rulings ledgered: whether a skills/*.md may serve as a checklist's architecture doc; a utils/ architecture doc; the daslib linq-family routing scope; a possible daslib/REVIEW_LINT.md split.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR formalizes a repo-wide “document grammar” split: REVIEW.md becomes diff-binding bans/duties only, ARCHITECTURE.md becomes present-tense system statements (with numbered sections), and historical/log material is moved under /history. It also adds a new lint folder rule (LINT025) plus install/bundle guards to keep repo-internal rule/record documents out of the shipped SDK, and turns off daslib comment-stripping to support comment-harvest workflows.

Changes:

• Introduces ARCHITECTURE_COMMON.md and rewrites many REVIEW.md checklists to the ban/duty form described by the updated REVIEW_COMMON.md.
• Adds LINT025 (“rule docs only” folders) to the lint runner, with a dedicated dastest that drives the CLI over a planted tree.
• Tightens install/bundle validation (CMake + bundle smoke test) to exclude repo-internal rule/record documents from shipped artifacts; updates related documentation/routing.

Reviewed changes

Copilot reviewed 103 out of 104 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
web/examples/ui/samples/examples/boulder-dash/REVIEW.md	Rewrites sample checklist rules into ban/duty form.
web/examples/ui/REVIEW.md	Adds sample-source verifier rule; rewrites routing.
utils/REVIEW.md	Rewrites tooling checklist rules into ban/duty form.
utils/mcp/REVIEW.md	Clarifies MCP shipping prohibition and run mode.
utils/lsp/REVIEW.md	Clarifies LSP shipping prohibition and run mode.
utils/lint/tests/lint025_rule_docs_only.das	Adds CLI-driven tests for new LINT025 folder pass.
utils/lint/REVIEW.md	Updates lint checklist to cover new invariants.
utils/lint/REVIEW.das	Extends rule-module scan set to include LINT025 emitter.
utils/lint/README.md	Documents LINT025 behavior and folder property semantics.
utils/lint/main.das	Implements LINT025 folder scan + integrates into driver mode.
utils/internal/dasweb-verify/REVIEW.md	Rewrites checklist rules into ban/duty form.
utils/internal/dasweb-verify/browser/REVIEW.md	Rewrites checklist rules; expectations.json emphasis.
utils/internal/dasweb-playground/REVIEW.md	Rewrites service checklist rules into ban/duty form.
utils/internal/dasweb-buildd/REVIEW.md	Rewrites buildd checklist; clarifies sandbox/token rules.
utils/internal/dasweb-buildd/README.md	Adds note about end-to-end checkpoint scope.
utils/internal/dasllama-ladder/REVIEW.md	Rewrites ladder checklist rules into ban/duty form.
utils/detect-dupe/REVIEW.md	Rewrites shipped-exe decision-record rule into duty form.
utils/daspkg/REVIEW.md	Rewrites release/test/ship rules into ban/duty form.
utils/dasllama-server/REVIEW.md	Rewrites fixture + routing + gate rules into ban/duty form.
utils/dascov/REVIEW.md	Rewrites shipped-exe rule into defect/duty form.
utils/das-fmt/REVIEW.md	Rewrites shipped-exe rule into defect/duty form.
utils/benchctl/REVIEW.md	Rewrites shipped-exe conditions into defect form.
tree-sitter-daslang/REVIEW.md	Rewrites generator/canary rules into defect/duty form.
tests/msl/REVIEW.md	Updates architecture-doc pointer and clarifies census rationale.
tests/metal/test_metal_mul_ab.das	Updates architecture reference in comment.
tests/metal/REVIEW.md	Updates architecture-doc pointer + adds Metal live-object rule.
tests/lint/test_lint_config.das	Updates expectation: daslib no longer strips comments.
tests/dasPUGIXML/parity_xml_order_distinct_group.das	Updates reference to linq_fold architecture location.
tests-cpp/small/REVIEW.md	Rewrites pin-test weakening rule into duty form.
tests-cpp/big/REVIEW.md	Tightens wording about “big” label not covered by CI.
src/parser/REVIEW.md	Rewrites tree-sitter sync rule into duty form.
src/builtin/REVIEW.md	Rewrites bind-flavor rules; clarifies inline-module policy.
skills/internal/doc_archiving.md	Updates archiving guidance to ARCHITECTURE.md terminology.
site/tests/playground/REVIEW.md	Adds checklist for Playwright tests requiring WASM runtime.
site/REVIEW.md	Rewrites site rules; routes Playwright specs to tests checklist.
site-dasllama/REVIEW.md	Rewrites site-dasllama rules into defect/bans.
REVIEW_COMMON.md	Updates contract: checklists are bans/duties, not statements.
plans/msl-flatten.md	Updates references from MASTERPLAN to ARCHITECTURE.md.
plans/daslib_comment_sweep.md	Adds follow-up ledger for comment-sweep surfaced items.
nano/REVIEW.md	Rewrites nano checklist into ban/duty form.
modules/REVIEW_SHADER_EMITTERS.md	Rewrites shared emitter rules into ban/duty form.
modules/dasVulkan/tutorials/REVIEW.md	Rewrites tutorial viewer duty into ban/duty form.
modules/dasVulkan/ROADMAP.md	Updates reference to dasSpirv ARCHITECTURE doc.
modules/dasVulkan/REVIEW.md	Rewrites generator/hand-edit rules and gate wording.
modules/dasVulkan/generator/REVIEW.md	Clarifies skip_report growth duty + rationale.
modules/dasVulkan/daslib/.lint_config	Arms [docs] rule_docs_only for LINT025 in module daslib.
modules/dasVulkan/CLAUDE.md	Tightens wording around windowed tutorial driver guidance.
modules/dasTreeSitter/daslib/.lint_config	Arms [docs] rule_docs_only for LINT025 in module daslib.
modules/dasTerminal/daslib/.lint_config	Arms [docs] rule_docs_only for LINT025 in module daslib.
modules/dasSQLITE/daslib/.lint_config	Arms [docs] rule_docs_only for LINT025 in module daslib.
modules/dasSpirv/REVIEW.md	Updates architecture pointer; adds new defect rules.
modules/dasSMT/daslib/.lint_config	Arms [docs] rule_docs_only for LINT025 in module daslib.
modules/dasPUGIXML/daslib/linq_fold_xml.das	Updates references to linq_fold architecture section.
modules/dasPUGIXML/daslib/.lint_config	Arms [docs] rule_docs_only for LINT025 in module daslib.
modules/dasMetal/REVIEW.md	Updates architecture pointer; rewrites rules; adds MSL ban.
modules/dasLLVM/REVIEW.md	Rewrites performance/tune/env rules into ban/duty form.
modules/dasLLVM/daslib/.lint_config	Arms [docs] rule_docs_only for LINT025 in module daslib.
modules/dasLLAMA/REVIEW.das	Updates role-partition wording + points to ARCHITECTURE doc.
modules/dasLLAMA/REVIEW_VISION.md	Rewrites vision rules into defect/bans/duties.
modules/dasLLAMA/REVIEW_AUDIO.md	Rewrites audio rules into defect/bans/duties.
modules/dasLLAMA/performance/REVIEW.md	Rewrites performance/exchange rules into defect/bans/duties.
modules/dasLLAMA/ARCHITECTURE.md	Adds conflict-resolution rule for placement charters.
modules/dasImgui/tests/REVIEW.md	Rewrites test portability rule into ban form.
modules/dasImgui/REVIEW.md	Tightens test-location + preflight duties.
modules/dasImgui/daslib/.lint_config	Arms [docs] rule_docs_only for LINT025 in module daslib.
modules/dasClipboard/daslib/.lint_config	Arms [docs] rule_docs_only for LINT025 in module daslib.
LAWS.md	Records rulings related to the document system changes.
include/daScript/simulate/REVIEW.md	Rewrites hot-path + layout-change rules into duty/defect form.
history/README.md	Updates “what stays” examples; adds archive log entries.
history/linq_fold/linq_fold.md	Marks linq_fold masterplan as archived; adds context header.
history/dasSpirv/MASTERPLAN_LOG.md	Archives plan/log content with new header and rationale.
doc/source/reference/language/lint.rst	Documents new LINT025 rule.
doc/reflections/das2rst.das	Exposes rule_docs_only_at in docs grouping.
dastest/REVIEW.md	Rewrites helper-sync rule into duty form.
daslib/lint_config.das	Adds [docs] table reader + fixes TOML parse-tree lifetime.
daslib/linq_fold_table.das	Updates references to linq_fold architecture section.
daslib/linq_fold_sql.das	Updates references to linq_fold architecture section.
daslib/linq_fold_json.das	Updates references to linq_fold architecture section.
daslib/linq_fold_decs.das	Updates references to linq_fold architecture section.
daslib/linq_fold_common.das	Updates references to linq_fold architecture section.
daslib/linq_fold_array.das	Updates references to linq_fold architecture section.
daslib/.lint_config	Disables comment stripping; arms [docs] rule_docs_only for LINT025.
CMakeLists.txt	Installs ARCHITECTURE_COMMON; extends install leak gate; excludes nano ARCHITECTURE.md.
CLAUDE.md	Adds “document system” section describing REVIEW/ARCH/history roles.
ci/smoke_test_bundle.sh	Hardens lib restore against races; bans internal rule/record docs in bundle.
ci/REVIEW.md	Rewrites bundle-smoke weakening rule into defect form.
ARCHITECTURE_COMMON.md	Adds repo-root contract for folder-scoped architecture docs.
.github/workflows/REVIEW.md	Rewrites CI gate-step rules into defect/duty form.
.claude/agents/janitor.md	Adds janitor agent spec for rewriting one checklist file.
.claude/agents/harvester.md	Adds harvester agent spec for comment harvesting workflow.
.claude/agents/dragon.md	Updates dragon audit criteria for statements/idioms/arch docs.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.