Host-aware setup, eval instrument repair, and dated support summary (4.2.0)

CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to SkipHow 2.x and later appear in this file. Earlier release notes remain available on [GitHub Releases](https://github.com/mzored/SkipHow/releases).
 
+## 4.2.0 (2026-09-06)
+
+SkipHow can now enable, check, and disable its own default governance when an installed user asks it to. The activation helper ships inside the skill, resolves the trusted user instruction file each host actually reads, and reports configured, available, and loaded as three separate facts. Installing, enabling, or upgrading SkipHow still grants no authority.
+
+### Changed
+
+- A `setup` playbook handles requests to enable, check, or disable SkipHow on this machine, or to explain why it did not load: one preview, one confirmation before writing, three separate facts, and managed policy reported rather than bypassed.
+- The activation helper moved from the repository into the skill package as `scripts/activation.py`. It follows host discovery: Codex reads `AGENTS.override.md` in its home when that file exists and is not empty, and `AGENTS.md` otherwise, with `CODEX_HOME` relocating the home; Claude Code reads `CLAUDE.md` and unconditional `rules/*.md` files under `CLAUDE_CONFIG_DIR` or its default directory. It moves a block found in a file the host does not read, consolidates duplicates, never writes through a symbolic link, removes every copy it may edit on disable, and reads each host's plugin inventory to report availability or says that enablement is unknown. `--target` still names any trusted file explicitly.
+- The integration playbook chooses failed-merge recovery by consequence. Evidence and unrelated work are preserved first; a disposable failure may stay in place for diagnosis; a shared target that other work, CI, or a deployment depends on is contained or restored to its last good state; restoring production keeps its grant.
+
+### Evaluation instrument
+
+- The canonical large-programme case names the `catalog-integration-ready` fixture, whose setup creates the `fix/catalog` branch the prompt refers to, and carries a scope note that the fixture is four separable repairs rather than a dependency-laden programme.
+- `evals/preflight.json` registers the expected pre-session state of each fixture, and `capture_eval.py prepare` validates the tree, then refuses a fixture whose branches, remote, foreign work, marker, or planted defects do not match it.
+- The continuity oracle bans outcomes rather than implementations: no stale grant acted on, no invented end state, no lost obligation, no duplicated work.
+- `scripts/grade_catalog.py` states the four expected catalog behaviors independently of any implementation and grades retained captures or destination records without starting a model.
+
+### Documentation
+
+- One dated support summary in `docs/evidence.md` states per host what was validated, configured, observed loaded, and left unknown. README, guide, FAQ, security policy, and site link to it instead of restating limitations that belonged to earlier packages.
+- Authority text on the site and in the FAQ follows effects. Staging and other isolated non-production environments are ordinary engineering unless the owner's own rules say otherwise; production, live data, public releases, credentials, access, repository settings, payments, and material deletion keep their explicit authorization.
+
+### Compatibility and evidence
+
+This is a minor release because the setup playbook and packaged helper are new opt-in capability and the recovery rule widens what the integration playbook permits within existing authority. Existing grants, restrictions, and protected-action boundaries survive the upgrade. The public skill name and record formats are unchanged.
+
+Deterministic checks, the September 6 audit disposition, and grader results on retained end states are recorded in [docs/evidence.md](docs/evidence.md). Every 4.2.0 behavior is `UNVERIFIED`: whether a session loads the skill from an `AGENTS.override.md` block, whether the agent operates the setup playbook as written, and whether the recovery rule changes what a run does. Host receipts for the exact 4.2.0 package are recorded in `evals/host-smoke.json` when they land.
+
 ## 4.1.1 (2026-09-05)
 
 Public evaluation receipts now omit account quota and authentication metadata, mask common credential formats and private paths, and pseudonymize trace identifiers. Capture applies this filtering before saving evidence, and an offline test checks every retained receipt. Per-run usage and synthetic fixture artifacts remain available for replay. The runtime instructions are unchanged; only the package version metadata changes.

README.md

@@ -10,7 +10,7 @@ One public skill covers questions, bugs, ideas, features, reviews, lists, progra
 [![Latest release](https://img.shields.io/github/v/release/mzored/SkipHow?label=release)](https://github.com/mzored/SkipHow/releases)
 [![MIT license](https://img.shields.io/github/license/mzored/SkipHow)](LICENSE)
 
-Host support is a dated, per-capability matrix in the [security policy](SECURITY.md#host-support-as-of-2026-09-04), not a badge. Claude Code and Codex CLI are the surfaces it covers; anything it does not list is `UNVERIFIED`.
+Host support is a dated, per-capability matrix in the [security policy](SECURITY.md#host-support-as-of-2026-09-06), not a badge. Claude Code and Codex CLI are the surfaces it covers; anything it does not list is `UNVERIFIED`.
 
 ```text
 Your outcome and constraints
@@ -77,21 +77,27 @@ Start a new session after installing. The [owner guide](docs/guide.md) covers up
 
 ### Activate it for ordinary language
 
-Plugin installation makes the skill available, but skill selection remains model-driven. For default governance before the first consequential action, add this line once to your trusted user instructions without replacing anything already there:
+Plugin installation makes the skill available, but skill selection remains model-driven. To have SkipHow govern ordinary requests by default, ask the installed skill to enable itself once:
 
 ```text
-For current-project requests, load the installed SkipHow skill before consequential action and use it as the adaptive virtual CTO policy. Do not load it for unrelated conversation or for a request that only discusses SkipHow without adopting it.
+$skiphow Enable SkipHow as my default virtual CTO on this machine.
 ```
 
-On Codex, append the line to the global `AGENTS.md` in your Codex home. Codex loads that file before project work. On Claude Code, append it to your user `CLAUDE.md` or a file in your user rules directory. Claude Code loads user instructions for every project. Review the existing file first, keep its content, and remove only the SkipHow line to disable default governance. This setup is reversible and does not install a hook or grant any action.
+In Codex the name is `$skiphow`; in Claude Code it is `/skiphow:skiphow`. The agent resolves the trusted user instruction file your host actually reads, shows you the exact change, writes one reversible block after you confirm, and reports three facts separately: whether the block is configured, whether the plugin is available on the host, and that loading is only visible in a fresh session. Codex reads a non-empty `AGENTS.override.md` in its home instead of `AGENTS.md`, and a custom `CODEX_HOME` moves that home; Claude Code reads the user `CLAUDE.md` and unconditional user rules under its configuration directory. A line placed in a file the host does not read configures nothing, which is why the agent, not you, resolves the target. Ask it to check or disable itself the same way. The block asks the host to load the skill and grants no action; installing or enabling SkipHow authorizes nothing.
+
+If you prefer to edit the file yourself, append this line to that file without replacing anything already there, and remove only this line to disable default governance:
+
+```text
+For current-project requests, load the installed SkipHow skill before consequential action and use it as the adaptive virtual CTO policy. Do not load it for unrelated conversation or for a request that only discusses SkipHow without adopting it.
+```
 
-These host mechanisms are documented, but default activation remains `UNVERIFIED`: one Claude Code bare-prompt pilot did not select the skill, persistent clean-home setup could not authenticate, and Codex clean-home model runs were also blocked by authentication. Explicit Claude Code invocation loaded the exact 4.0.1 policy in the historical pilot set; Codex explicit invocation remains `UNVERIFIED`. Explicit invocation is the fallback and diagnostic path:
+Explicit invocation remains the fallback and diagnostic path:
 
 ```text
 $skiphow The totals overlap on small screens. Find the cause and fix it.
 ```
 
-In Codex the name is `$skiphow`; in Claude Code it is `/skiphow:skiphow`. The package no longer ships the reminder hook. It did not load the policy or restore continuity, and no controlled comparison showed that its executable surface helped. Current support status is in the [support matrix](SECURITY.md#host-support-as-of-2026-09-04).
+What each host has actually shown is in the [dated support summary](docs/evidence.md#support-summary-as-of-2026-09-06). In short: ordinary-language loading, delivery to a synthetic remote, and native resume were observed once each on Codex with the exact 4.1.0 package in an isolated home; on Claude Code no persistent-setup run exists and one earlier bare-prompt pilot did not select the skill. No activation mode has a measured reliability, and the package ships no session hook.
 
 ## Use it
 
@@ -140,9 +146,9 @@ SkipHow keeps one owner-facing entry. Critical rules stay in its kernel, while f
 
 ## What the evidence shows
 
-Deterministic checks prove package structure; controlled runs are required for behavior claims. The behavioral observations on record were made on 2.x packages, on both hosts, and cover fully specified requests, open product choices, failure diagnosis, adversarial verification, and the splitting of larger work into independently verifiable units. The 4.x virtual-CTO behavior and default ordinary-language activation remain `UNVERIFIED` until retained receipts show them.
+Deterministic checks prove package structure; controlled runs are required for behavior claims. The behavioral observations on record were made on 2.x packages, on both hosts, and cover fully specified requests, open product choices, failure diagnosis, adversarial verification, and the splitting of larger work into independently verifiable units. On the 4.x virtual-CTO contract, retained isolated Codex diagnostics on the exact 4.1.0 package show ordinary-language loading, four correct repairs delivered to a synthetic remote with foreign work preserved, read-only behavior on analysis and unrelated requests, and native resume and compaction. A separate Claude coordination diagnostic left its synthetic remote unchanged and accepted an incorrect shipping calculation despite independent review. Coordinated cross-host delivery, failed-delegate recovery, real GitHub tracking, and every behavior of the current package remain `UNVERIFIED` until retained receipts show them.
 
-These are observations, not a reliability rate. The project does not retain every transcript, public adoption is still limited, and comparative advantage over a base agent or another framework is `UNVERIFIED`. The [evidence matrix](docs/evidence.md) is the single home for the method, the claims each run supports, and the failures.
+These are observations, not a reliability rate. The project does not retain every transcript, public adoption is still limited, and comparative advantage over a base agent or another framework is `UNVERIFIED`. The [dated support summary](docs/evidence.md#support-summary-as-of-2026-09-06) says what was demonstrated on which package, host, and configuration; the rest of the [evidence ledger](docs/evidence.md) is the single home for the method, the claims each run supports, and the failures.
 
 ## Limits
 
@@ -161,7 +167,7 @@ Use a spec or workflow framework when approving the method is part of your job.
 - [Prior art](docs/prior-art.md), for mechanisms kept and rejected
 - [Design](docs/design.md) and [decision history](docs/decisions.md)
 - [Current evidence](docs/evidence.md), for what is demonstrated and what is not
-- [Host support matrix](SECURITY.md#host-support-as-of-2026-09-04), dated per capability
+- [Host support matrix](SECURITY.md#host-support-as-of-2026-09-06), dated per capability
 - [Contributing](CONTRIBUTING.md) and [security policy](SECURITY.md)
 
 SkipHow adapts selected ideas from [Matt Pocock's skills](https://github.com/mattpocock/skills) and keeps the required MIT attribution in [`THIRD_PARTY_NOTICES.md`](plugins/skiphow/THIRD_PARTY_NOTICES.md). SkipHow itself is [MIT licensed](LICENSE).