Release Diátaxis Docs 0.1.8

.claude-plugin/marketplace.json

@@ -23,7 +23,7 @@
       "name": "diataxis-docs",
       "repository": "https://github.com/Statusnone420/Skills",
       "source": "./adapters/claude",
-      "version": "0.1.7"
+      "version": "0.1.8"
     }
   ]
 }

.github/workflows/validate.yml

@@ -1,12 +1,93 @@
 name: validate
 on:
   push:
+    branches: [main]
   pull_request:
+  workflow_dispatch:
+concurrency:
+  group: validate-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 permissions:
   contents: read
 jobs:
-  tests:
-    name: Tests (${{ matrix.os }} / ${{ matrix.group }})
+  pr_tests:
+    name: Tests (${{ matrix.os }} / ${{ matrix.label }})
+    if: github.event_name == 'pull_request' && github.base_ref != 'main'
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            group: core
+            label: core
+            shard_count: 1
+            shard_index: 0
+          - os: ubuntu-latest
+            group: lifecycle
+            label: lifecycle
+            shard_count: 1
+            shard_index: 0
+          - os: ubuntu-latest
+            group: trajectory
+            label: trajectory
+            shard_count: 1
+            shard_index: 0
+          - os: windows-latest
+            group: core
+            label: core
+            shard_count: 1
+            shard_index: 0
+          - os: windows-latest
+            group: lifecycle
+            label: lifecycle 1/5
+            shard_count: 5
+            shard_index: 0
+          - os: windows-latest
+            group: lifecycle
+            label: lifecycle 2/5
+            shard_count: 5
+            shard_index: 1
+          - os: windows-latest
+            group: lifecycle
+            label: lifecycle 3/5
+            shard_count: 5
+            shard_index: 2
+          - os: windows-latest
+            group: lifecycle
+            label: lifecycle 4/5
+            shard_count: 5
+            shard_index: 3
+          - os: windows-latest
+            group: lifecycle
+            label: lifecycle 5/5
+            shard_count: 5
+            shard_index: 4
+          - os: windows-latest
+            group: trajectory
+            label: trajectory
+            shard_count: 1
+            shard_index: 0
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.14"
+      - name: Verify test partition
+        run: python -B tools/run_tests.py verify
+      - name: Run ${{ matrix.label }} tests
+        run: >-
+          python -B tools/run_tests.py ${{ matrix.group }}
+          --shard-count ${{ matrix.shard_count }}
+          --shard-index ${{ matrix.shard_index }}
+      - name: Verify generated adapters
+        if: matrix.group == 'core'
+        shell: bash
+        run: python -B tools/build_adapters.py --check --output adapters
+
+  full_tests:
+    name: Tests (${{ matrix.os }} / ${{ matrix.group }} / serial)
+    if: github.event_name != 'pull_request' || github.base_ref == 'main'
     strategy:
       fail-fast: false
       matrix:
@@ -26,19 +107,29 @@ jobs:
         if: matrix.group == 'core'
         shell: bash
         run: python -B tools/build_adapters.py --check --output adapters
+
   tests_gate:
     name: Tests
     if: always()
-    needs: tests
+    needs: [pr_tests, full_tests]
     runs-on: ubuntu-latest
     steps:
-      - name: Require complete matrix success
+      - name: Require the selected validation mode to pass
         shell: bash
         env:
-          MATRIX_RESULT: ${{ needs.tests.result }}
+          PR_RESULT: ${{ needs.pr_tests.result }}
+          FULL_RESULT: ${{ needs.full_tests.result }}
         run: |
-          if [ "$MATRIX_RESULT" != "success" ]; then
-            echo "::error::Test matrix result was $MATRIX_RESULT."
+          if [ "$PR_RESULT" != "success" ] && [ "$PR_RESULT" != "skipped" ]; then
+            echo "::error::Pull-request validation was $PR_RESULT."
+            exit 1
+          fi
+          if [ "$FULL_RESULT" != "success" ] && [ "$FULL_RESULT" != "skipped" ]; then
+            echo "::error::Full validation was $FULL_RESULT."
+            exit 1
+          fi
+          if [ "$PR_RESULT" = "skipped" ] && [ "$FULL_RESULT" = "skipped" ]; then
+            echo "::error::No validation mode passed (PR=$PR_RESULT, full=$FULL_RESULT)."
             exit 1
           fi
-          echo "All test matrix jobs passed."
+          echo "Selected validation mode passed (PR=$PR_RESULT, full=$FULL_RESULT)."

AGENTS.md

@@ -66,5 +66,8 @@ Universal rules. Obey host precedence; among recognized instruction files, the m
 
 ## Project rules
 
+- 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.
+- 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 0.1.8 seven-day public-alpha trial, classify a 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 release contract. Record confirmed limitations in `docs/KNOWN_ISSUES.md`; park hypothetical-user polish and precision-only improvements instead of patching the release mid-trial.

ARCHITECTURE.md

@@ -1,17 +1,38 @@
 # Architecture
 
-The canonical source is `skills/docs/SKILL.md`, routed to `references/commands.md` and, when needed, `references/memory.md`. The source defines explicit routing, evidence-first writing, adaptive memory, and a result contract. The product is a repository documentation operating system: Diátaxis supplies the organization compass, while the map/highway, scope evidence, Trust routes, freshness hashes, and lifecycle control plane make the behavior auditable.
+This describes how the current 0.1.8 release is built. What it is *supposed* to guarantee is the [product constitution](PRODUCT.md).
 
-`skills/docs/scripts/check.py` is an optional network-free orchestration façade over cohesive `_docs_checker` modules. The checker confines paths to the repository, rejects reparse points, treats `.md`, `.markdown`, and `.mdx` as one inert document policy, selects one bounded navigation surface, resolves the supported Mintlify provider contract from the manifest's actual parent, uses tracked authority when Git visibility exists, parses Markdown links and anchors, reports unreachable pages and duplicate titles, evaluates state-declared hash freshness and Trust coverage, and reports provenance-tagged map/current-state bytes. Malformed, unsafe, ambiguous, or unsupported provider surfaces are unmeasured without a fallback score. The deterministic surface result is shared by Map, Check, Doctor, Audit, and Init; Init binds provider facts, provider findings, and the authority digest into preview/apply revalidation for both Git and non-Git repositories. Semantic model findings remain a labeled ceiling above provider facts. The 16,384-byte value is only `provisional_target_bytes`, not an enforced budget, health input, or deletion mandate.
+The canonical product lives in `skills/docs/`. Everything under `adapters/` and `plugins/diataxis-docs/` is generated installation output.
 
-`_docs_checker/evidence.py` owns sanitized evidence receipt v1. It copies existing deterministic health output without recalculating it, preserves category raw/earned/available values and score gates, and keeps deterministic, semantic, unresolved, Doctor, write, Git, and unavailable evidence in separate typed lanes. `evidence_receipt.py` is a stdout-first façade. The corpus preparation tool writes only newly owned, ignored sparse checkouts; the separate corpus runner requires clean detached exact commits, reads configuration as bounded bytes, executes no documentation or provider code, and proves target Git state is unchanged.
+## Main boundaries
 
-Discovery owns bounded metadata and selection policy; `init_adoption.py` owns the deterministic, engine-owned first-run adoption (scope selection, corpus accounting, preview construction, and receipt binding); `paths.py` owns confinement, normalization, reparse checks, and prune primitives; `memory.py` is read-only inspection; `lifecycle.py` owns pure authorization/state policy; and `lifecycle_io.py` owns transactional filesystem I/O. The dependency direction is one-way and the CLI façade stays thin. The committed `.diataxis/` control plane stores normalized routes, stable findings, verified hashes, disposition identity, and event history—never document bodies, prompts, hidden reasoning, or local-only filenames.
+- `SKILL.md` routes explicit commands to focused contracts under `references/`.
+- `scripts/check.py` is the network-free entrypoint to the deterministic checker.
+- `_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, 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.
 
-Every generated adapter packages the complete canonical checker resource tree. Generic web prompts are composed per command from a shared safety core, one selected command contract, and required supporting rules; they do not concatenate the entire playbook. The 0.1.4 historical range was 3,484–24,679 UTF-8 bytes. The measured 0.1.7 range is 3,460–31,992 bytes, with a 42,000-byte generator regression guard and 10,008 bytes of headroom.
+The `.diataxis/` directory stores routes, stable finding identities, verification hashes, dispositions, and events. It does not store document bodies, prompts, hidden reasoning, or private local filenames. A repository that has never initialized this control plane can still complete an approved Doctor treatment statelessly: the engine verifies the named document changes but does not create memory implicitly.
 
-The repository Codex marketplace lives at `.agents/plugins/marketplace.json` and routes to the generated `plugins/diataxis-docs` package. Its folder, marketplace entry, and `.codex-plugin/plugin.json` all use the same `diataxis-docs` identity. The package contains the shared `docs` engine plus 13 thin `docs-<command>` routing skills; each focused skill embeds only its own selected command contract and hard-binds the sibling engine checker, without copying the checker or any full playbook. Claude receives equivalent thin skills with its explicit-only invocation metadata. The umbrella remains compatible on both hosts.
+## Distribution
 
-Fresh no-map Doctor is a presentation and routing boundary, not a new rubric. Complete, untruncated scope metadata can yield an authoritative provider measurement, a provisional existing-entry candidate, or a tracked-root-README orientation fallback; content-batch limits do not block the engine's structural scan or grant semantic reads. The fallback states that the README is not a maintained map, recommends Init, and writes nothing. Unsafe or metadata-incomplete evidence remains unavailable. Rubric v2 and provider scoring are unchanged.
+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.
 
-Adapters under `adapters/` and the Codex package under `plugins/diataxis-docs` are generated outputs. Do not hand-edit them; regenerate from the canonical source and test their documented invocation tier.
+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.
+
+## 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.
+
+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).