Add the Version 1.1 governed learning layer

.clean-docs.yml

@@ -88,6 +88,51 @@ bindings:
     doc: docs/SECURITY_MODEL.md
     anchor: process-controls
     source: {path: src/clean_docs/isolation.py, symbol: run_isolated_process}
+  - id: tutorial-outcomes
+    type: region
+    doc: docs/learn/tutorial-catch-a-lying-doc.md
+    region: tutorial-outcomes
+    extractor: json
+    source:
+      path: .clean-docs/learning/tutorial-evidence.json
+      pointer: /steps
+    renderer: markdown-table
+    columns: [moment, command, exit, meaning]
+  - id: postmortem-measurements
+    type: region
+    doc: docs/learn/postmortem-the-readme-that-lied.md
+    region: postmortem-measurements
+    extractor: json
+    source:
+      path: .clean-docs/learning/ultra-csm-hygiene.json
+      pointer: /measurements
+    renderer: markdown-table
+    columns: [measure, before, after]
+  - id: postmortem-examples
+    type: region
+    doc: docs/learn/postmortem-the-readme-that-lied.md
+    region: postmortem-examples
+    extractor: json
+    source:
+      path: .clean-docs/learning/ultra-csm-hygiene.json
+      pointer: /examples
+    renderer: markdown-table
+    columns: [case, before, after]
+  - id: deterministic-seam-evidence
+    type: symbol
+    doc: docs/learn/deep-dive-the-deterministic-seam.md
+    anchor: evidence-authority
+    source: {path: src/clean_docs/engine.py, symbol: evaluate}
+  - id: deterministic-seam-phrasing
+    type: symbol
+    doc: docs/learn/deep-dive-the-deterministic-seam.md
+    anchor: phrasing-boundary
+    source: {path: src/clean_docs/phrasing.py, symbol: build_model_record}
+  - id: deterministic-seam-gate
+    type: symbol
+    doc: docs/learn/deep-dive-the-deterministic-seam.md
+    anchor: gate-authority
+    source: {path: src/clean_docs/outcomes.py, symbol: build_outcome_receipt}
 projections:
   llms_txt:
     output: llms.txt
@@ -105,6 +150,10 @@ projections:
       - docs/SECURITY_MODEL.md
       - docs/SUPPORT.md
       - docs/SURFACE.md
+      - docs/learn/index.md
+      - docs/learn/tutorial-catch-a-lying-doc.md
+      - docs/learn/postmortem-the-readme-that-lied.md
+      - docs/learn/deep-dive-the-deterministic-seam.md
       - skill/SKILL.md
   bundles:
     - id: contributor

.clean-docs/context/contributor.md

@@ -1,13 +1,13 @@
 # Context bundle: contributor
 
 - Source ref: `WORKTREE`
-- Corpus sha256: `74f0d42c8d758125d6fbe9878054b8bd5abeb7b32477a26274e99f776128be01`
+- Corpus sha256: `4de14e204a537a326c3881119c5d39f9efea575cf1c7355f9a573d1a8c85c279`
 - Content: exact canonical document bytes
 
 ## Canonical document: README.md
 
 - Source: [README.md](../../README.md)
-- Content sha256: `4289b0409955e0ce025e67cdf718814f0c0d77971663fe779809a64aa8e39d05`
+- Content sha256: `b3d947ea15bd363b589a256b91affbd9d954b8b78667aa34432e8d0478cc5358`
 
 <!-- clean-docs:canonical README.md begin -->
 # clean-docs
@@ -17,6 +17,13 @@ clean-docs is a source-bound documentation engine and CLI for maintainers whose
 <!-- clean-docs:end purpose -->
 <!-- clean-docs:allow doc-length reason="The canonical overview keeps installation, first protection, manifest shape, and current boundaries in one reader path" -->
 
+[![CI](https://github.com/owieschon/clean-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/owieschon/clean-docs/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/owieschon/clean-docs?display_name=tag&sort=semver)](https://github.com/owieschon/clean-docs/releases/latest)
+[![License: MIT](https://img.shields.io/badge/license-MIT-25225f.svg)](LICENSE)
+
+**[Start here](docs/learn/index.md)** for the product map, runnable drift tutorial, real-repository
+postmortem, and deterministic-boundary explanation.
+
 ## Why clean-docs exists
 
 <!-- clean-docs:begin product-overview -->

.clean-docs/learning/tutorial-evidence.json

@@ -0,0 +1,35 @@
+{
+  "schema": "clean-docs.tutorial-evidence.v1",
+  "steps": [
+    {
+      "command": "clean-docs check",
+      "exit": 0,
+      "meaning": "The bound page matches source.",
+      "moment": "Protected baseline"
+    },
+    {
+      "command": "clean-docs check",
+      "exit": 1,
+      "meaning": "The status-actions binding is stale.",
+      "moment": "Source changed alone"
+    },
+    {
+      "command": "clean-docs drive",
+      "exit": 0,
+      "meaning": "Only the bound region changes.",
+      "moment": "Declared region repaired"
+    },
+    {
+      "command": "clean-docs project",
+      "exit": 0,
+      "meaning": "llms.txt receives the repaired page digest.",
+      "moment": "Projection refreshed"
+    },
+    {
+      "command": "clean-docs verify",
+      "exit": 0,
+      "meaning": "Bindings and projections are current.",
+      "moment": "Repository verified"
+    }
+  ]
+}

.clean-docs/learning/ultra-csm-hygiene.json

@@ -0,0 +1,63 @@
+{
+  "examples": [
+    {
+      "after": "relocated into the archive convention the repo already used, history intact",
+      "before": "an agent-to-agent handoff sat in the tracked doc tree a reader browses",
+      "case": "process exhaust off the reader surface"
+    },
+    {
+      "after": "only the version `src/ultra_csm/agent1/slot_b.py:38` loads remains on the surface",
+      "before": "four versions of one prompt tracked side by side, each a near-duplicate of the last",
+      "case": "one canonical home for a versioned prompt"
+    },
+    {
+      "after": "each passage is equally true, with the authoring history removed",
+      "before": "a worldbuilding reference tagged its content with the program that authored it",
+      "case": "provenance stripped from a reader-facing reference"
+    }
+  ],
+  "measurements": [
+    {
+      "after": "73 (all justified in `NOTES.md`)",
+      "before": "280",
+      "measure": "Total findings"
+    },
+    {
+      "after": "10 (cited evidence, per `docs/README.md`)",
+      "before": "91",
+      "measure": "surface (process artifact on reader surface)"
+    },
+    {
+      "after": "33 (genuine long references)",
+      "before": "93",
+      "measure": "section-length"
+    },
+    {
+      "after": "7 (shared concepts across separate docs)",
+      "before": "54",
+      "measure": "near-dup"
+    },
+    {
+      "after": "21 (genuine long references)",
+      "before": "22",
+      "measure": "doc-length"
+    },
+    {
+      "after": "1 (a run-ledger table cell)",
+      "before": "11",
+      "measure": "provenance"
+    },
+    {
+      "after": "0",
+      "before": "7",
+      "measure": "audience"
+    },
+    {
+      "after": "1",
+      "before": "2",
+      "measure": "restatement"
+    }
+  ],
+  "schema": "clean-docs.learning-evidence.v1",
+  "source": "docs/archive/v0/ultra-csm-before-after.md"
+}

.clean-docs/reader-trial-rubric-v1.1.yml

@@ -0,0 +1,30 @@
+version: 1
+context:
+  - README.md
+  - docs/learn/index.md
+  - docs/learn/tutorial-catch-a-lying-doc.md
+  - docs/learn/postmortem-the-readme-that-lied.md
+  - docs/learn/deep-dive-the-deterministic-seam.md
+profiles:
+  - id: anthropic-opus-4-8
+    provider: anthropic
+    model: Opus 4.8
+  - id: codex-gpt-5-6-sol-high
+    provider: codex
+    model: GPT 5.6 Sol High
+tasks:
+  - id: route-orientation
+    instruction: Starting from the README first screen and learning index, choose the page that explains what clean-docs is and why source-bound documentation matters.
+    passes_when: The reader chooses the README overview for product orientation, then identifies the learning index thesis that documentation drift is a source-derivation problem.
+  - id: route-hands-on
+    instruction: Starting from the learning index, choose the page for learning the repair loop by doing it.
+    passes_when: The reader chooses the catch-a-lying-doc tutorial and states that it establishes a baseline, creates source drift, observes failure, repairs the declared region, refreshes projections, and verifies the result.
+  - id: route-mechanism
+    instruction: Starting from the learning index, choose the page that explains who owns facts, phrasing, and the gate result.
+    passes_when: The reader chooses the deterministic-seam deep dive and assigns evidence selection and pass-or-fail authority to deterministic code while limiting a model to phrasing supplied evidence.
+  - id: run-tutorial
+    instruction: Run the published tutorial against the candidate in a fresh repository and record each command exit and declared file change.
+    passes_when: The baseline passes, deliberate source drift fails first with the named binding, drive changes the declared documentation region, project refreshes llms.txt, and final check and verify exit zero.
+  - id: explain-authority-boundary
+    instruction: Explain why a model cannot select facts, widen scope, or decide whether clean-docs passes, using only the published learning pages.
+    passes_when: The answer preserves the evidence-to-phrasing-to-gate sequence, names deterministic code as the authority on inputs and outcomes, and does not grant the model merge-gate authority.

.github/workflows/ci.yml

@@ -39,6 +39,14 @@ jobs:
       - run: clean-docs --root . release --from v0.4.0 --to HEAD --format json
       - run: python scripts/record_demo.py --out /tmp/clean-docs-demo-evidence.json
       - run: cmp .clean-docs/demo/evidence.json /tmp/clean-docs-demo-evidence.json
+      - run: python scripts/build_learning_evidence.py --out /tmp/clean-docs-learning-evidence.json
+      - run: cmp .clean-docs/learning/ultra-csm-hygiene.json /tmp/clean-docs-learning-evidence.json
+      - run: >-
+          python scripts/record_learning_tutorial.py
+          --clean-docs "$(command -v clean-docs)"
+          --out /tmp/clean-docs-tutorial-evidence.json
+      - run: cmp .clean-docs/learning/tutorial-evidence.json /tmp/clean-docs-tutorial-evidence.json
+      - run: python scripts/render_social_preview.py --check
       - run: python scripts/trusted_self_check.py
 
   public-dogfood:
@@ -224,6 +232,32 @@ jobs:
           path: clean-docs-v10-acceptance.json
           if-no-files-found: error
 
+  acceptance-v1-1:
+    needs: test
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install ".[dev]"
+      - run: >-
+          python scripts/run_acceptance.py
+          --registry tests/v11-acceptance.yml
+          --out clean-docs-v11-acceptance.json
+      - if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: clean-docs-v1.1-acceptance-${{ matrix.os }}-${{ github.sha }}
+          path: clean-docs-v11-acceptance.json
+          if-no-files-found: error
+
   performance-v1-0:
     needs: test
     runs-on: ${{ matrix.os }}

README.md

@@ -5,6 +5,13 @@ clean-docs is a source-bound documentation engine and CLI for maintainers whose
 <!-- clean-docs:end purpose -->
 <!-- clean-docs:allow doc-length reason="The canonical overview keeps installation, first protection, manifest shape, and current boundaries in one reader path" -->
 
+[![CI](https://github.com/owieschon/clean-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/owieschon/clean-docs/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/owieschon/clean-docs?display_name=tag&sort=semver)](https://github.com/owieschon/clean-docs/releases/latest)
+[![License: MIT](https://img.shields.io/badge/license-MIT-25225f.svg)](LICENSE)
+
+**[Start here](docs/learn/index.md)** for the product map, runnable drift tutorial, real-repository
+postmortem, and deterministic-boundary explanation.
+
 ## Why clean-docs exists
 
 <!-- clean-docs:begin product-overview -->

docs/RELEASES.md

@@ -33,4 +33,11 @@ The factual Markdown and JSON remain unchanged when narrative validation fails.
 
 Release extraction is static and snapshot-bound. First-party and configured discoverer plugins run once per ref in disposable copies. The active worktree, its installed dependencies, and narrative output cannot change the typed delta.
 
-Release-candidate builds rehearse the published reader tasks in CI. A stable release additionally requires one content-addressed trial from each model profile declared in the rubric: Anthropic Opus 4.8, Anthropic Sonnet 5, Codex GPT 5.5 High, and Codex GPT 5.6 Sol High. Every profile runs in a fresh session with only the rubric's published context, completes every task, and binds its evidence by SHA-256. Profiles cannot share conversation history or prior trial output. The receipt also names the exact candidate commit and wheel digest. `scripts/verify_reader_trial.py` checks `.clean-docs/reader-trial.json`; `scripts/build_release.py` reconstructs the candidate wheel and permits only the version and reader receipts to differ in the stable release. It refuses absent, duplicate, substituted, incomplete, stale, tampered, or untried evidence.
+Release-candidate builds rehearse the published reader tasks in CI. A stable release additionally requires one content-addressed trial from each profile in that release line's rubric:
+
+| Release line | Independent reader set | Evidence contract |
+| --- | --- | --- |
+| `1.0` | Anthropic Opus 4.8, Anthropic Sonnet 5, Codex GPT 5.5 High, and Codex GPT 5.6 Sol High | Product identification, installation, protection, repair, and limitation tasks |
+| `1.1` | Anthropic Opus 4.8 and Codex GPT 5.6 Sol High | Learning-path routing, tutorial execution, and deterministic-authority tasks |
+
+Every profile runs in a fresh session with only the rubric's published context, completes every task, and binds its evidence by SHA-256. Profiles cannot share conversation history or prior trial output. The receipt also names the exact candidate commit and wheel digest. `scripts/verify_reader_trial.py` selects the versioned rubric and evidence namespace; `scripts/build_release.py` reconstructs the candidate wheel and permits only the version and matching reader receipts to differ in the stable release. It refuses absent, duplicate, substituted, incomplete, stale, tampered, or untried evidence.

docs/SURFACE.md

@@ -9,12 +9,12 @@ The catalog binding catches additions, removals, and replacements across the det
 <!-- clean-docs:begin repository-surface -->
 | surface | discovered | examples |
 | --- | ---: | --- |
-| api-symbol | 175 | `AcceptanceCase`, `Assertion`, `AuditFinding`, and 172 more |
+| api-symbol | 184 | `AcceptanceCase`, `Assertion`, `AuditFinding`, and 181 more |
 | cli-command | 19 | `audit`, `benchmark`, `check`, and 16 more |
-| cli-option | 50 | `--accept-hygiene-baseline`, `--base`, `--binding`, and 47 more |
+| cli-option | 55 | `--accept-hygiene-baseline`, `--base`, `--binding`, and 52 more |
 | package | 1 | `clean-docs` |
 | runtime-constraint | 1 | `Python >=3.10` |
-| test-suite | 47 | `scripts/test_release_lifecycle.py`, `tests/test_audit.py`, `tests/test_changed_check.py`, and 44 more |
+| test-suite | 49 | `scripts/test_release_lifecycle.py`, `tests/test_audit.py`, `tests/test_changed_check.py`, and 46 more |
 
-<!-- clean-docs:inventory-sha256 61e11d87a96877a70108487792853e5c73e9e755a7d69489890d1bbf39942895 -->
+<!-- clean-docs:inventory-sha256 24238579bd4089d5ec516ee344e83bad956e5cbd1b29d8eba1b99ad6a6ff78a6 -->
 <!-- clean-docs:end repository-surface -->