Classify documentation and publish readiness from one engine result

AGENTS.md

@@ -69,4 +69,5 @@ Universal rules. Obey host precedence; among recognized instruction files, the m
 - Documentation starts at `docs/README.md`; current verified status is `docs/STATE.md`.
 - Canonical source lives under `skills/docs/`; do not hand-edit generated adapters.
 - Run the repository checker before claiming completion.
+- Use proactive proof, not reactive patching: before any behavior change, identify the adjacent input, state, and output classes, then test the invariant at the changed boundary instead of waiting for review to reveal siblings. For Markdown, MDX, and other multi-syntax evidence formats, define the supported syntax family before implementation, add table-driven invariant tests across every relevant form with live controls, and audit every consumer of the shared boundary. If review exposes a missed form, expand the family-level proof instead of patching only that example.
 - During the unreleased 0.1.8 PR train, classify a review finding as blocking only when it affects my daily-driver behavior, safety, privacy, data integrity, ability to understand or use the product, or an explicit PR contract. Park hypothetical-user polish and precision-only improvements instead of interrupting the current PR.

ARCHITECTURE.md

@@ -11,7 +11,12 @@ The canonical product lives in `skills/docs/`. Everything under `adapters/` and
 - `_docs_checker/scan.py` measures maintained Markdown, MarkdownX, links, anchors, titles, and reachability without executing repository code.
 - `_docs_checker/paths.py` confines every path to the repository and rejects unsafe reparse boundaries.
 - `_docs_checker/selection.py` is the one place that decides which documentation a read command measures: the boundary, the map route, and — with the manifest — the entry route. The repository is the default; only an explicit human request narrows it, and that selection is recorded as partial. It reads directory listings and the repository inventory the manifest needs, never local operational state.
-- `_docs_checker/manifest.py` builds the additive, immutable documentation manifest: repository-complete accounting, the recorded measured boundary with its map and provider entry routes, classification facts, exclusions, limits, and a deterministic identity over normalized routes and inspected-body digests. It reuses `health.normalized_content_digest` rather than defining a second content identity. Every read command route through `check.py` builds exactly one and publishes its identity, selected routes, and coverage completeness. `evidence_receipt.py` still takes its own explicit map and scope from the pinned corpus manifest and does not build one.
+- `_docs_checker/manifest.py` builds the additive, immutable documentation manifest: repository-complete accounting, the recorded measured boundary with its map and provider entry routes, exclusions, limits, and a deterministic identity over normalized routes and inspected-body digests. It reuses `health.normalized_content_digest` rather than defining a second content identity. Every read command route through `check.py` builds exactly one. `evidence_receipt.py` still takes its own explicit map and scope from the pinned corpus manifest and does not build one.
+- `_docs_checker/documentation_policy.py` parses the selected map's current working-tree `docs:policy` block, applies exact-over-directory precedence, preserves hand-authored order during edits, and reports committed, uncommitted, or non-Git provenance.
+- `_docs_checker/document_classification.py` assigns each accounted document one evidence-bounded role plus independent `never_edit` and repository-status facts. Selected map/current-truth routes and declared generator evidence can decide a role; filenames, folders, and ordinary links cannot.
+- `_docs_checker/readiness.py` calculates the unweighted readiness-v3 fraction from per-document reachability, link/anchor, title, and confinement facts. Trust and stored rubric-v2 state stay separate.
+- `_docs_checker/documentation_result.py` assembles the one ordered `documentation` ledger, deterministic groups, unresolved cards, coverage, policy provenance, and write facts consumed by Map, Check, Doctor, Audit, and Init.
+- `_docs_checker/resolution.py` previews and exactly applies one selected-map policy edit through a single-use short code and compare-before-write drift checks. `_docs_checker/treatment_policy.py` owns write and purpose-backed link eligibility without changing classification or readiness.
 - `_docs_checker/memory.py` reads the optional `.diataxis/` control plane.
 - `_docs_checker/lifecycle.py` decides whether a requested state change is authorized; `lifecycle_io.py` performs the transactional write.
 - `init_adoption.py` and the closeout modules bind a preview to the exact evidence that must still be true at apply time.
@@ -22,12 +27,12 @@ The `.diataxis/` directory stores routes, stable finding identities, verificatio
 
 The adapter generator packages the same checker with thin host-specific entrypoints. Codex and Claude receive an umbrella plus focused command skills; static and web adapters receive only the command contract they need. Generated files are parity-checked and must never be edited by hand.
 
-The structural percentage, Trust state, semantic findings, unavailable evidence, and byte telemetry remain separate evidence classes. An unsupported or ambiguous documentation surface is unmeasured rather than guessed.
+Readiness v3, transitional rubric-v2 health, Trust state, semantic findings, unavailable evidence, and byte telemetry remain separate evidence classes. Readiness never compares itself with rubric-v2 state. An unsupported or ambiguous documentation surface is unmeasured or `unresolved` rather than guessed.
 
-## The known structural defect
+## Repaired read-model boundary and remaining integration
 
 Boundary selection used to be spread across several routes that could disagree: `check.py` defaulted an omitted `--scope` to `docs`, the stateless Doctor baseline ran its own discovery, an initialized Doctor used its recorded state, and the prompt contract asked the host model to supply the map and current-truth paths. Those routes now share `selection.py` and one manifest per invocation.
 
-What remains: the public result envelope still carries no document inventory, so a displayed map tree is assembled by the model rather than by the engine, and every role outside the measured surface is still `unresolved` rather than classified. The reproduced evidence is in [current state](docs/STATE.md); the target is in the [product constitution](PRODUCT.md).
+The public result envelope now carries the complete documentation ledger, classification, grouping, policy provenance, and readiness facts. What remains is integration at the interface boundary: the installed Map contract does not render that ledger, legacy rubric-v2 health remains beside readiness v3, and `context`, `write`, and `update` still lack matching deterministic engine entrypoints. The reproduced evidence is in [current state](docs/STATE.md); the target is in the [product constitution](PRODUCT.md).
 
 For module diagrams and design rationale, see the [Architecture wiki page](https://github.com/Statusnone420/Skills/wiki/Architecture). For measured limits and current proof, see [BENCHMARK.md](BENCHMARK.md).

BENCHMARK.md

@@ -6,12 +6,12 @@ This is the sole ledger for changing test counts, prompt sizes, dogfood results,
 
 | Evidence | Result |
 | --- | --- |
-| Windows deterministic groups | Current partition: 1,087 tests — 457 core, 451 lifecycle, and 179 trajectory. The focused PR 2 correction suites pass locally; the complete current Windows matrix is delegated to PR CI and is not claimed here before it runs. The prior 1,059-test snapshot passed with 3 lifecycle cases skipped as POSIX-only and 6 strict expected failures naming the later phase that owns each unmet contract. |
-| Windows lifecycle feedback | Five local shards passed the prior 438-test lifecycle snapshot in 182.1 s. The current 451-test lifecycle partition is delegated to PR CI. Hosted sharding is measured separately: PR #27's `validate` run completed in 3m21s, and its slowest Windows lifecycle shard took 3m08s, against PR 0's final serial CI runs of 11m41s–12m06s. Those are single-run host counters for this repository on GitHub-hosted runners, not a general throughput claim. |
-| Generated adapter prompts | 3,557–34,971 UTF-8 bytes |
+| Windows deterministic groups | Current partition: 1,187 tests — 556 core, 452 lifecycle, and 179 trajectory. The complete review-fix local matrix passed; the 99 focused PR 3 contracts are green, and two strict expected failures remain assigned to the beginner-interface phase. Hosted results for this snapshot are tracked by PR #30's validate checks. |
+| Windows lifecycle feedback | The current 452-test lifecycle partition passed across five local shards in 187.2 s. Hosted sharding is measured separately: PR #27's `validate` run completed in 3m21s, and its slowest Windows lifecycle shard took 3m08s, against PR 0's final serial CI runs of 11m41s–12m06s. Those are single-run host counters for this repository on GitHub-hosted runners, not a general throughput claim. |
+| Generated adapter prompts | 3,523–34,973 UTF-8 bytes |
 | Generator regression guard | 45,000 bytes; packaging telemetry, not a product or health limit |
-| Repository documentation check | The default and explicit `--scope .` routes both measure boundary `.`: 89%; 151/151 links valid; all 41 non-generated maintained pages reachable; remaining 20 unreachable and 7 duplicate-title findings are generated marketplace copies. |
-| Full Linux rerun for this branch | The pre-guidance 906-test snapshot passed on Ubuntu/Python 3.14.4 in 94 s. The current 1,087-test snapshot has not run on Linux yet; fresh CI remains required before release. |
+| Repository documentation check | A fresh checkout exits 0 with repository-complete accounting for 61 documentation paths — 2 maintained, 20 generator-declared outputs, and 39 unresolved. Readiness v3 is 2 of 2 eligible documents; `accounted_documents` is 61, `nonignored_unresolved` is 39, and `denominator_representative` is false, so that 100% eligible fraction is not whole-repository health. Local working copies with ignored drafts account for those additional paths by name and count while leaving their bodies unread. The 7 remaining published findings carry target role and write-eligibility facts; generated cold documents no longer surface as repair findings. Transitional rubric v2 remains separately visible at 89% until the beginner-interface phase removes it. |
+| Full Linux rerun for this branch | The pre-guidance 906-test snapshot passed on Ubuntu/Python 3.14.4 in 94 s. The 1,149-test snapshot passed on hosted Ubuntu and Windows in PR #30's `validate` run #297; that PR's checks are authoritative for later snapshots. |
 | Installed-package no-state retry | Pass: 49/49 links valid, a stateless approval receipt was produced, and the repository remained unchanged without `.diataxis/` |
 | Installed-package guided recovery | Pass outside the source tree: foreign-only, tracked-missing, merge-conflicted, and absent-state fixtures selected the expected four outcomes with zero writes and no private sentinel exposure |
 | Installed-package treatment canary | Pass: exact stateless preview → one-file apply → candidate and installed verification clean; zero control writes, no `.diataxis/`, unchanged real Git index, and only the intended disposable worktree file changed |
@@ -56,7 +56,7 @@ This proves routing and safety contracts for those fixtures. It does not prove a
 
 - A 2026-07-17 Claude/Cline canary showed that a tracked Mintlify/MDX corpus could be misread as empty. The repair made MarkdownX inert text, protected unsupported provider surfaces, and reports unmeasured evidence instead of a misleading zero.
 - A 2026-07-27 no-state dogfood run exposed an uninitialized-lifecycle conflict: Doctor produced a valid read-only scan, then closeout treated absent `.diataxis/` state as corruption and recovery offered no action. The 0.1.8 candidate now distinguishes a genuinely stateless repository from partial or malformed controls, and the installed-package retry passed.
-- A 2026-07-27 measurement reproduced a command boundary divergence on this repository at commit `da02ba2`: two default command routes disagreed about which documentation exists, with no repository change between runs. The current PR 2 candidate repairs that divergence locally: the default checker, explicit repository boundary, first-contact Doctor, and Init routes consume the same repository selection and manifest identity. Hosted Linux and installed-host proof remain pending. The three-route comparison is tabulated in [docs/STATE.md](docs/STATE.md), against the contract in [PRODUCT.md](PRODUCT.md).
+- A 2026-07-27 measurement reproduced a command boundary divergence on this repository at commit `da02ba2`: two default command routes disagreed about which documentation exists, with no repository change between runs. The current 0.1.8 candidate repairs that divergence locally: the default checker, explicit repository boundary, first-contact Doctor, and Init routes consume the same repository selection, documentation result, and readiness result. Hosted Linux and installed-host proof remain pending. The three-route comparison is tabulated in [docs/STATE.md](docs/STATE.md), against the contract in [PRODUCT.md](PRODUCT.md).
 - A 2026-07-27 adversarial audit reproduced the same dead end for non-transactional corruption: missing, malformed, merge-conflicted, or foreign-only `.diataxis` evidence failed closed but recovery returned `action: none`. The candidate now returns one zero-write operator action, never applies it automatically, and preserves exact-approved transaction recovery unchanged.
 
 Failures remain in this ledger after repair so the safety story cannot be rewritten as uninterrupted success.

COMMANDS.md

@@ -18,7 +18,7 @@ Unknown or missing commands return help without side effects.
 
 ## Init: one-time adoption
 
-Init's first response is a read-only preview built by the deterministic engine. It first measures the same repository reality as Map and Doctor, then reports any narrower setup choice separately. The model presents that verified result rather than improvising one. The engine builds a repository-wide inventory but does not yet publish its full path list in the result, so a displayed map *tree* is still assembled by the model from the engine's summary ([gap 2](PRODUCT.md#what-the-current-candidate-does-not-do-yet)). The preview covers the measured repository, the proposed setup map, the `.diataxis/` memory files, and a complete disposition manifest. `--scope <repository-relative-directory>` is the only public component override. Nothing is written until you approve the exact preview.
+Init's first response is a read-only preview built by the deterministic engine. It first measures the same repository reality as Map and Doctor, then reports any narrower setup choice separately. The engine result now publishes the complete documentation path ledger, classification, policy provenance, deterministic groups, and readiness facts; the installed Map presentation does not render that ledger yet. The preview covers the measured repository, the proposed setup map, the `.diataxis/` memory files, a complete disposition manifest, and the initial user-owned `never-edit` choice. Repeated `--never-edit <repository-relative-path>` values provide explicit entries instead of the default `.github/` suggestion; host integrations can also pass an explicit empty choice to decline the suggestion. `--scope <repository-relative-directory>` is the only public component override. Nothing is written until the exact preview is approved, and approved Init writes the policy into the selected map.
 
 ## Doctor: ongoing diagnosis
 
@@ -29,7 +29,9 @@ Doctor reports every finding in the evidenced scope, groups them into treatments
 
 ## Check: the score
 
-`check` reports the structural percentage separately from Trust coverage (are declared current-truth routes verified?) and hash freshness. A route counts as declared current truth when your documentation map marks it: append `<!-- docs:current -->` (or `<!-- docs:authoritative -->`) to the end of the map line that links your current-state document. The engine reads that marker; it never infers a current-truth route from prose, and a map that declares none reports Trust as `unverified` rather than guessing. Byte measurements are telemetry with provenance — never a score input, a health failure, or a reason to delete anything.
+`check` now returns readiness v3 as an unweighted ready/eligible fraction with every per-document failed fact. Trust coverage (are declared current-truth routes verified?), hash freshness, and byte telemetry stay separate. The envelope temporarily also carries rubric-v2 structural health for compatibility; the two percentages are different contracts and are never compared. A route counts as declared current truth when your documentation map marks it: append `<!-- docs:current -->` (or `<!-- docs:authoritative -->`) to the end of the map line that links your current-state document. The engine reads that marker; it never infers a current-truth route from prose, and a map that declares none reports Trust as `unverified` rather than guessing.
+
+The canonical checker exposes role-resolution writes through two machine-output flags. `--resolve-preview` reads one UTF-8 JSON decisions mapping from standard input, bounded to 1 MiB before parsing, and returns the exact zero-write map-policy diff plus its `DOCS-R-` approval. `--resolve-apply APPROVAL` reads the same bounded mapping in a later process, recomputes the binding from the current snapshot, and applies only the matching current code; oversized or malformed input uses the existing input-error envelope, successful previews and applies exit 0, and refusals exit 2 with zero writes.
 
 ## Boundaries
 
@@ -41,9 +43,9 @@ These never move:
 - Approved structural changes carry exact IDs, fingerprints, a recovery boundary, and one complete disposition for every removed file or unique section.
 - Failed verification becomes a rollback or an explicit conflict — never a silent success.
 
-### Not settled yet
+### Ignored documentation
 
-When a repository has no `docs/README.md`, the map and check fallback probes read root files by name — including `PLAN.md`. A private, Git-ignored file with one of those names can therefore be selected as documentation evidence and read into a host transcript. Until the discovery privacy rule lands, keep private working notes out of the repository root or under a name the probe does not list.
+Git-ignored or explicitly excluded documentation is represented by repository-relative path, name, and count, but its body is not read and it receives no classification card. Nonignored root documents are inventoried regardless of filename; a conventional name may help select an entry but cannot decide whether a document exists or assign its role.
 
 ## More detail