Verified Work Plane V2

.github/workflows/ci.yml

@@ -61,7 +61,7 @@ jobs:
         # disagree about what the limit is.
         run: |
           set -e
-          for dir in tools skills hooks scripts; do
+          for dir in tools skills hooks scripts ainative; do
             echo "--- $dir"
             (cd "$dir" && node ../hooks/pretool-loc-gate/run_gate.js --all)
           done
@@ -91,6 +91,127 @@ jobs:
         shell: bash
         run: python -m unittest discover -s hooks/tests -p "test_*.py" -v
 
+  workplane-v2:
+    name: Verified Work Plane V2 (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+
+      # The V2 kernel shipped its whole hardening sequence with no CI job at
+      # all: every gate was a local run on one machine, on one OS, on one
+      # Python. A verdict engine that only ever ran where it was written has
+      # no evidence it is deterministic anywhere else.
+      - name: Contracts, controller and snapshot
+        run: python -m unittest tests.test_workplane_contracts tests.test_workplane_controller tests.test_workplane_snapshot -v
+
+      - name: Runner, trust, freshness, traceability and convergence
+        run: python -m unittest tests.test_workplane_runner_convergence tests.test_workplane_substance tests.test_workplane_authorization tests.test_workplane_traceability tests.test_workplane_convergence_history -v
+
+      - name: Adversarial matrix A01-A53
+        run: python -m unittest tests.test_workplane_adversarial -v
+
+      - name: Authority matrix A54-A70, through the production boundary
+        run: python -m unittest tests.test_workplane_authority tests.test_workplane_authority_origin -v
+
+      - name: CLI, integrations and local pilot harnesses
+        run: python -m unittest tests.test_workplane_cli tests.test_workplane_integrations_metrics tests.test_workplane_pilot tests.test_workplane_harness_matrix tests.test_workplane_historical_case -v
+
+      - name: The package installs and exposes its console entry point
+        shell: bash
+        run: |
+          set -e
+          python -m pip install --disable-pip-version-check --no-deps -e .
+          ainative work --help > /dev/null
+          ainative converge --help > /dev/null
+
+      - name: Deterministic gates must also reproduce outside the test runner
+        # bash, not the Windows default shell: PowerShell only propagates the
+        # exit code of the last line, which would hide a failure in the first
+        # two commands.
+        shell: bash
+        run: |
+          set -e
+          python scripts/workplane_structural_regression.py
+          python scripts/workplane_harness_matrix.py
+          python scripts/workplane_pilot.py --self-check
+
+      - name: The complexity budget AGENTS.md declares blocking
+        # It was published and never measured: traceability.analyze shipped at
+        # ~32 branches, in the module every convergence verdict passes through.
+        run: python scripts/check_complexity_budget.py
+
+  lifecycle:
+    name: Distribution lifecycle (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # The lifecycle layer deletes files in a user's project. Every gate below
+      # runs on all three platforms because path handling, links, case folding
+      # and process liveness are exactly where they differ.
+      - name: Transition matrix, round trips and idempotence
+        run: python -m unittest tests.test_lifecycle_matrix -v
+
+      - name: Ownership, user modifications and external config
+        run: python -m unittest tests.test_lifecycle_ownership -v
+
+      - name: Path traversal, link escape, tampered state, archive safety
+        run: python -m unittest tests.test_lifecycle_security -v
+
+      - name: Interruption, rollback, recovery, locking and legacy adoption
+        run: python -m unittest tests.test_lifecycle_transactions -v
+
+      - name: Update check, apply, conflict, recovery and rollback
+        run: python -m unittest tests.test_lifecycle_update -v
+
+      - name: CLI contract, exit codes, JSON and the layer boundary
+        run: python -m unittest tests.test_lifecycle_cli -v
+
+      - name: Non-vacuity — each guard must actually block
+        # A protection nobody has seen refuse is a comment. This reverts each
+        # guard in a scratch copy and asserts the matching test then fails.
+        run: python scripts/lifecycle_non_vacuity.py
+
+  clean-install:
+    name: Clean install E2E (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+
+      # As a user, not as a developer: build the wheel, install it into a
+      # throwaway venv, and drive the console script from a directory that has
+      # never heard of this checkout. No PYTHONPATH, no repo on sys.path. The
+      # failure mode this catches is a lifecycle layer that only works from
+      # inside its own source tree — and a wheel whose staged payload installs
+      # something different from what a checkout installs.
+      #
+      # One cross-platform script rather than three dialects of shell: the
+      # same gate runs here and on a developer's machine.
+      - name: Build a wheel, install it, and use it as a user would
+        run: python scripts/lifecycle_clean_install.py
+
   installers:
     name: Installers (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
@@ -124,7 +245,7 @@ jobs:
         shell: bash
         run: python scripts/install_agents.py --home "$HOME/stack-ci/fakehome" --check
 
-      - name: Per-project installer — into a throwaway git repo
+      - name: Per-project bootstrap — the pre-lifecycle flags still work
         shell: bash
         run: |
           set -e
@@ -136,24 +257,62 @@ jobs:
           echo "print('hi')" > src/main.py
           git add -A && git commit -qm init
           cd "$GITHUB_WORKSPACE"
-          python install.py --project-root "$HOME/stack-ci/proj" --skip-gstack
+          # --project-root and --skip-gstack are the names the old installer
+          # used; a script written against it must keep running.
+          python install.py --profile standard \
+            --project-root "$HOME/stack-ci/proj" --skip-gstack
           test -f "$HOME/stack-ci/proj/AGENTS.md"
           test -f "$HOME/stack-ci/proj/conventions.json"
           test -d "$HOME/stack-ci/proj/.claude/skills/verify-ai-docs"
           test -d "$HOME/stack-ci/proj/.agents/skills/verify-ai-docs"
+          test -f "$HOME/stack-ci/proj/.ai-native/lifecycle/state.json"
 
-      - name: A re-install prunes files removed upstream
+      - name: A re-install prunes a managed file removed upstream — and only that
         shell: bash
         run: |
           set -e
-          # A plain copy leaves a file deleted upstream sitting in every
-          # project that installed it earlier — the drift this stack exists
-          # to prevent.
-          touch "$HOME/stack-ci/proj/.claude/skills/verify-ai-docs/OBSOLETE.md"
-          python install.py --project-root "$HOME/stack-ci/proj" --skip-gstack
-          if [ -f "$HOME/stack-ci/proj/.claude/skills/verify-ai-docs/OBSOLETE.md" ]; then
-            echo "a file removed upstream survived a re-install"; exit 1
+          PROJ="$HOME/stack-ci/proj"
+          SKILL="$PROJ/.claude/skills/verify-ai-docs"
+
+          # A file the stack recorded, that the distribution no longer ships,
+          # must not survive: that is the drift this stack exists to prevent.
+          # A file it never wrote must survive: deleting it is the drift the
+          # ownership model exists to prevent (ADR-0009 §3).
+          echo "# added by me" > "$SKILL/MY-NOTES.md"
+          MANAGED="$(python - "$PROJ" <<'PY'
+          import json, sys
+          from pathlib import Path
+          state = json.loads((Path(sys.argv[1]) / ".ai-native/lifecycle/state.json")
+                             .read_text(encoding="utf-8"))
+          print(next(entry["path"] for entry in state["managed_files"]
+                     if entry["path"].startswith(".claude/skills/verify-ai-docs/")))
+          PY
+          )"
+          echo "managed file under test: $MANAGED"
+
+          python install.py --profile standard --project-root "$PROJ" --skip-gstack
+          test -f "$PROJ/$MANAGED"        # still shipped, still present
+          test -f "$SKILL/MY-NOTES.md"    # never ours, never removed
+
+          # Now make it disappear from the source and re-install: it must go.
+          rm -rf "$GITHUB_WORKSPACE/skills/verify-ai-docs"
+          python install.py --profile standard --project-root "$PROJ" --skip-gstack
+          if [ -f "$PROJ/$MANAGED" ]; then
+            echo "a managed file removed upstream survived a re-install"; exit 1
           fi
+          test -f "$SKILL/MY-NOTES.md"
+          git -C "$GITHUB_WORKSPACE" checkout -- skills/verify-ai-docs
+
+      - name: Uninstall leaves the user's work, then reinstall works
+        shell: bash
+        run: |
+          set -e
+          PROJ="$HOME/stack-ci/proj"
+          python -m ainative.cli uninstall --project "$PROJ"
+          test -f "$PROJ/src/main.py"
+          test -f "$PROJ/.claude/skills/verify-ai-docs/MY-NOTES.md"
+          python install.py --profile standard --project-root "$PROJ" --skip-gstack
+          test -f "$PROJ/AGENTS.md"
 
       - name: v4 governance block — six harness get vault block; user content survives
         # Build a throwaway v4 vault, point the installer at it via

.gitignore

@@ -29,3 +29,10 @@ calibration_report.md
 
 # Vault sync sentinel (per-machine state, never committed)
 scripts/vault_last_sync_date.txt
+
+# Build artefacts from `pip install .`
+build/
+*.egg-info/
+
+# Lifecycle payload staged at build time by _build_backend.py — never tracked.
+ainative/_payload/

AGENTS.md

@@ -170,18 +170,28 @@ Central unread modules (>5 incoming imports): none
 
 ### This project — ai-native-dev-stack
 
-Measured 2026-08-30 via `git ls-files` (image excluded). Re-measure with
-`python3 scripts/measure_scope.py`; CI fails when these figures drift.
+Measured 2026-09-04 (distribution & lifecycle v1) via `git ls-files` (image excluded). Re-measure
+with `python3 scripts/measure_scope.py`; CI fails when these figures drift.
 
 | Scope | Tokens (÷4) | Files | Strategy |
 |---|---|---|---|
-| Core stack (excl. anti-debt) | ~127 000 | 75 | **Layered read** — cartography first, then targeted reads |
-| Anti-debt agent | ~130 000 | 118 | Read its `AI_CONTEXT.md` and ADRs before its sources |
-| Whole repo | ~246 000 | 191 | **Multi-phase workflow** — never a single direct read |
+| Core stack (excl. anti-debt) | ~396 860 | 194 | **Layered read** — cartography first  then targeted reads |
+| Anti-debt agent | ~129 648 | 118 | Read its `AI_CONTEXT.md` and ADRs before its sources |
+| Whole repo | ~526 509 | 312 | **Multi-phase workflow** — never a single direct read |
 
-Do **not** read the whole repo in one pass: at ~246k tokens it does not fit,
+Do **not** read the whole repo in one pass: at ~527k tokens it does not fit,
 and the strategy table above applies in full. Pick the scope the task needs —
-most work touches only one of the two halves.
+most work touches only one of the three halves below.
+
+The core stack is itself two independent halves, and almost no task needs both:
+
+| Half | Entry points | What it decides |
+|---|---|---|
+| **Distribution & lifecycle** (`ainative/`) | `docs/DISTRIBUTION-LIFECYCLE.md`, ADR-0009 | what is installed, and what may be replaced or deleted |
+| **Verified Work Plane** (`ainative_workplane/`) | `docs/VERIFIED-WORK-PLANE.md`, ADR-0001…0008 | whether declared work has converged |
+
+The dependency runs one way: lifecycle may invoke the Work Plane, never the
+reverse. Reading either half without the other is correct.
 
 > This block said "~22 000 tokens, 11 files, direct read always" until
 > 2026-08-27, measured ten weeks and 178 files earlier. Every agent read that

CHANGELOG.md

@@ -8,6 +8,56 @@ project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+#### Distribution & Lifecycle Manager v1
+
+- **Two profiles, `standard` and `verified`**, declared in
+  `ainative/lifecycle/data/profiles.json`. `verified` extends `standard` and
+  lists only what it adds; the resolver computes the effective component set.
+  The dependency runs one way — the lifecycle layer may invoke the Verified
+  Work Plane, never the reverse, and installing Standard loads no authority
+  module. Proved by inspecting `sys.modules`, not by convention.
+- **`ainative` as a top-level dispatcher** — `init`, `profile status|switch|purge`,
+  `status`, `doctor`, `repair`, `uninstall`, `update check|apply|rollback`, plus
+  the unchanged Verified surface (`trust`, `work`, `verify`, `converge`,
+  `debug`), handed over verbatim with their own exit codes.
+- **Recorded file ownership.** Four classes (`MANAGED_IMMUTABLE`,
+  `MANAGED_MUTABLE`, `USER_DATA`, `EXTERNAL_CONFIG`) and a SHA-256 per managed
+  file taken at the moment the stack writes it. This is what makes uninstall and
+  update possible at all: a file the stack wrote is now distinguishable from a
+  file the user rewrote.
+- **Transactional mutations** — backup, apply, verify, then commit the install
+  state *last*, with a journal at `.ai-native/lifecycle/transactions/`. An
+  interruption leaves the old valid state or the new one; `ainative repair`
+  completes the rollback. An `O_EXCL` lock with liveness-checked stale detection
+  keeps two mutations from interleaving.
+- **Non-destructive downgrade.** `profile switch standard` deactivates Verified
+  governance and preserves `.ai-native/{trust,work,runs}` as dormant state.
+  Deleting it is a separate, explicit `ainative profile purge verified`.
+- **Update lifecycle** — cached detection (24 h TTL, bounded timeout, `OFFLINE`
+  is not fatal), transactional application with archive digest and path-safety
+  verification, `.new` files instead of merges for user-modified content, and
+  `ainative update rollback` for the project's assets. Detection is automatic;
+  application never is, and no authority command ever reaches the network.
+- **Legacy adoption.** A project installed before the lifecycle existed is
+  detected and adopted on the next `init`. A file is claimed only when its bytes
+  match what the distribution ships; anything else is tracked but never replaced
+  and never removed.
+- `--dry-run` on every mutation, `--yes` on every confirmation, `--json` on
+  every command a script would parse, and stable exit codes (0/1/2/3).
+- `docs/DISTRIBUTION-LIFECYCLE.md` and
+  [ADR-0009](docs/adr/0009-distribution-profiles-and-lifecycle-ownership.md).
+- `scripts/lifecycle_non_vacuity.py` — reverts each guard in a scratch copy and
+  requires the matching test to fail. Three cases were reported VACUOUS on the
+  first run and were real: two guards were layered so removing one proved
+  nothing, and one test could not see commit ordering at all.
+- `scripts/lifecycle_clean_install.py` + a CI job on all three OSes — builds the
+  wheel, installs it into a throwaway venv, and drives the console script from a
+  directory with no `PYTHONPATH` and no checkout, asserting that the staged
+  payload installs exactly what a checkout installs.
+- An in-tree PEP 517 backend (`_build_backend.py`) that stages the installable
+  payload into the wheel, so the repository keeps one copy of its own method and
+  a user with no checkout can still install a profile.
+
 - `conventions.json` — machine-readable twin of the size/complexity thresholds
   declared in `AGENTS.md`. Every enforcement point now reads it instead of
   carrying its own copy of the numbers.
@@ -84,6 +134,26 @@ project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Changed
 
+- **One authority for the lifecycle.** `install.py` is now a bootstrap for the
+  one situation `pip` cannot cover — a fresh machine — and delegates to
+  `ainative init`; `install.sh` and `install.ps1` find a Python and hand over.
+  Its pre-lifecycle flags (`--project-root`, `--skip-gstack`, `--with-gstack`,
+  `--gstack-ref`, `--dry-run`) still work.
+- **`install.py` no longer prunes a file it did not write.** `copy_tree` deleted
+  anything under a managed directory that the source no longer had, including a
+  skill the user had edited. Pruning is now decided per file by the digest
+  recorded at install time.
+- `scripts/stack-update-check.sh` and `scripts/stack-upgrade.sh` are documented
+  as what they are — *clone*-level operations. The project-level update is
+  `ainative update`. There is no second project updater.
+- The console entry point moved from `ainative_workplane.cli:main` to
+  `ainative.cli:main`, which dispatches. Every Verified command keeps its
+  grammar, output and exit codes.
+- The distribution is now `ainative-dev-stack` and ships both packages; the
+  lifecycle CLI requires Python 3.11+ (the AI-docs tooling it installs still
+  runs on 3.8+). `docs/DISTRIBUTION-LIFECYCLE.md` states the three surfaces.
+- `scripts/check_complexity_budget.py` measures the lifecycle package too, and
+  the CI LOC gate covers `ainative/`.
 - **One implementation of the LOC rule.** `scripts/loc_gate.ps1` is merged into
   `hooks/pretool-loc-gate/run_gate.js`, which now offers all three modes
   (single file, `--staged`, `--all`). The CI job calls that same script, so CI