@softspark/ai-toolkit 4.32.3 → 4.33.0

package/llms-full.txt

@@ -84,7 +84,7 @@
 - **a11y-validate**: Accessibility validator: WCAG 2.1 AA, EN 301 549, EAA. Triggers: a11y, accessibility, WCAG, EAA, ARIA, contrast, keyboard, screen reader.
 - **agent-creator**: Creates new specialized agents with frontmatter, tools, delegation. Triggers: new agent, create agent, agent scaffold, specialized agent.
 - **analyze**: Analyzes code quality, complexity, patterns across codebase. Triggers: quality report, hotspot scan, code analysis, architecture signal.
-- **api-patterns**: REST/GraphQL API design: naming, versioning, pagination, idempotency, OpenAPI. Triggers: API design, REST, GraphQL, OpenAPI, Swagger, idempotency, rate limit.
+- **api-patterns**: API design: naming, versioning, pagination, idempotency, OpenAPI, error contracts and safe retries. Triggers: API design, REST, GraphQL, OpenAPI, Swagger, error response, HTTP status, rate limit.
 - **app-builder**: App scaffolding: Next.js, Vite, Nuxt, Astro, FastAPI, Django, Laravel, RN, Flutter. Triggers: scaffold, bootstrap, new project, starter, dashboard, mobile app.
 - **architecture-audit**: Audits codebase for architectural friction, shallow modules; proposes RFCs. Triggers: improve architecture, shallow modules, deepen modules, reduce coupling.
 - **architecture-decision**: Architecture decisions in ADR/RFC/RFD format: context, constraints, options, recommendation. Triggers: ADR, RFC, RFD, trade-offs, design choice, pick between, evaluate approach.
@@ -7721,10 +7721,10 @@ title: "SOP: Post-Release Testing"
 category: procedures
 service: ai-toolkit
 tags: [sop, post-release, smoke-test, npm, sandbox, plugin-pack, provenance, isolation]
-version: "1.2.0"
+version: "1.2.1"
 created: "2026-07-26"
-last_updated: "2026-08-19"
-description: "Smoke-test a published @softspark/ai-toolkit release from npm in an isolated HOME and npm prefix, without touching the maintainer's real install. Covers provenance, CLI, doctor, per-skill script resolution, scanner wiring, and the full plugin-pack lifecycle including the degraded-install path. Written for v4.18.0 and not run; v4.18.0 shipped a pack that broke every command it touched. First actually run on v4.22.0, which added Phases 4b and 4c after that release fixed four skills whose documented script path had never resolved and two that shipped a scanner nothing invoked."
+last_updated: "2026-09-06"
+description: "Smoke-test a published @softspark/ai-toolkit npm artifact in a disposable container or VM with its default HOME, no host settings or credential mounts, host-side configuration fingerprints, and retained evidence. Covers provenance, CLI, doctor, installed skill scripts, scanner wiring, and the plugin-pack lifecycle."
 ---
 
 # SOP: Post-Release Testing
@@ -7734,73 +7734,147 @@ actually install, from npm, rather than the working tree.
 
 Sibling procedures exist for `jira-mcp` and `legal-pl-pack`; this is the
 ai-toolkit equivalent. It complements
-[Release Verification](sop-release-verification.md), which checks the toolkit
-from the maintainer's own installed copy. The difference that matters: this one
-never writes to the maintainer's `~/.claude` or `~/.softspark`.
+[Release Verification](sop-release-verification.md), whose cross-editor checks
+must use the same isolated published artifact. Neither procedure installs or
+updates the maintainer's working copy.
 
 **Time:** 10 minutes.
 
 ## Why isolation is the first step, not a detail
 
-The toolkit installs into `$HOME`. Testing a release against your own HOME
-means the test either pollutes your working setup or, worse, passes because of
-state your setup already had. Both make the result meaningless.
+The toolkit writes settings beneath the current user's home directory. Run the
+published artifact in a disposable Docker container or VM with its normal HOME.
+Do not override host HOME, CODEX_HOME, or another editor's configuration root as
+a substitute for isolation. Do not expose the host home, credentials, SSH agent,
+Docker socket, or existing toolkit installation to the test environment.
 
-Every command below runs against a throwaway HOME and a throwaway npm prefix.
-Nothing is global.
+## Phase 1: Create and verify an isolated test environment
 
-## Phase 1: Sandbox
+The recipe below uses Docker. A disposable VM is equivalent only when host shared
+folders and authentication forwarding are absent. The host needs Docker and
+Python 3; the container prerequisites are installed separately below.
+
+**Host terminal:** keep this terminal open for Phases 7 and 8. The fingerprint
+reads only these toolkit-managed settings files and records hashes and presence,
+never their contents. Add a path only after verifying that the tested installer
+actually manages it.
 
 ```bash
-SB=$(mktemp -d)
-mkdir -p "$SB/home" "$SB/npm"
-export HOME="$SB/home"
-AT="$SB/npm/bin/ai-toolkit"
-echo "sandbox: $SB"
+set -o pipefail
+VERSION="X.Y.Z"
+EVIDENCE=$(mktemp -d "${TMPDIR:-/tmp}/ai-toolkit-release-${VERSION}.XXXXXX")
+SMOKE_CONTAINER=$(python3 -c 'import uuid; print("ai-toolkit-smoke-" + uuid.uuid4().hex)')
+
+fingerprint_host() {
+  python3 - <<'PY'
+import hashlib
+import json
+import os
+from pathlib import Path
+
+home = Path.home()
+managed = [
+    ".claude/settings.json",
+    ".claude.json",
+    ".softspark/ai-toolkit/plugins.json",
+    ".codex/config.toml",
+    ".cursor/mcp.json",
+    ".gemini/settings.json",
+    ".config/opencode/opencode.json",
+]
+rows = {}
+for relative in managed:
+    path = home / relative
+    row = {"exists": path.exists() or path.is_symlink()}
+    if path.is_symlink():
+        row["link_sha256"] = hashlib.sha256(os.readlink(path).encode()).hexdigest()
+    if path.is_file():
+        row["sha256"] = hashlib.sha256(path.read_bytes()).hexdigest()
+    rows[relative] = row
+print(json.dumps({
+    "host_home_sha256": hashlib.sha256(str(home).encode()).hexdigest(),
+    "files": rows,
+}, sort_keys=True, indent=2))
+PY
+}
+
+fingerprint_host > "$EVIDENCE/host-before.json"
+docker run -d --name "$SMOKE_CONTAINER" \
+  --label "org.softspark.release-smoke=$SMOKE_CONTAINER" \
+  --env "VERSION=$VERSION" \
+  node:22-bookworm sleep infinity
+docker inspect "$SMOKE_CONTAINER" > "$EVIDENCE/container-before.json"
+python3 - "$EVIDENCE/container-before.json" <<'PY'
+import json
+import sys
+
+container = json.load(open(sys.argv[1], encoding="utf-8"))[0]
+assert container["Mounts"] == [], "Smoke container must have no mounts"
+host = container["HostConfig"]
+assert not host["Privileged"], "Privileged containers are forbidden"
+assert host["NetworkMode"] != "host", "Do not share the host network namespace"
+assert host["PidMode"] != "host", "Do not share host processes"
+PY
+docker exec "$SMOKE_CONTAINER" bash -lc \
+  'test "$HOME" = "$(getent passwd "$(id -u)" | cut -d: -f6)"'
+docker exec "$SMOKE_CONTAINER" bash -lc \
+  'apt-get update && apt-get install -y --no-install-recommends python3 python3-yaml git coreutils jq bats shellcheck ca-certificates curl util-linux' \
+  2>&1 | tee "$EVIDENCE/bootstrap.log"
+```
+
+Install any additional prerequisite declared by the pack under test only inside
+the container. GNU coreutils supplies timeout; util-linux supplies the session
+recorder. Use docker cp for evidence transfer, not host temporary-directory bind
+mounts: a remote Docker daemon may not see the host's /private/tmp.
+
+**Enter the container, then run Phases 2 through 6 there:**
+
+```bash
+docker exec -it "$SMOKE_CONTAINER" bash
 ```
 
-Record the real state now, so Phase 7 can prove it is unchanged:
+Inside that container shell:
 
 ```bash
-python3 -c "
-import json, pathlib
-p = pathlib.Path('$SB/../real-before.json')
-import os
-home = pathlib.Path(os.path.expanduser('~'))
-" 2>/dev/null
-# Simpler: note what exists today.
-cat ~/.softspark/ai-toolkit/plugins.json 2>/dev/null
+SB=/tmp/ai-toolkit-smoke
+AT="$SB/npm/bin/ai-toolkit"
+mkdir -p "$SB/npm" "$SB/evidence"
+export SB AT
+exec script -q -e -a "$SB/evidence/session.log" -c 'bash --noprofile --norc'
 ```
 
+Keep HOME at the container user's default. VERSION was passed when the container
+was created; SB and the npm prefix are disposable container paths. No command in
+Phases 2 through 6 runs in the host shell.
+
 ## Phase 2: Provenance
 
 Do this before installing anything: an unsigned publish is a release-blocking
 regression, and there is no point smoke-testing a build you would have to redo.
 
 ```bash
-VERSION="X.Y.Z"
-npm view "@softspark/ai-toolkit@${VERSION}" --json \
-  | python3 -c "
+npm view "@softspark/ai-toolkit@${VERSION}" --json > "$SB/evidence/npm-view.json"
+python3 -c "
 import json, sys
-d = json.load(sys.stdin); att = d['dist'].get('attestations', {})
+d = json.load(open(sys.argv[1], encoding='utf-8')); att = d['dist'].get('attestations', {})
 pt = att.get('provenance', {}).get('predicateType')
 assert pt == 'https://slsa.dev/provenance/v1', f'NO PROVENANCE: {pt}'
 print('PROVENANCE OK:', att['url'])
-"
+" "$SB/evidence/npm-view.json"
 ```
 
 ## Phase 3: Install from npm
 
 ```bash
 npm install -g --prefix "$SB/npm" "@softspark/ai-toolkit@${VERSION}"
-"$AT" --version    # must equal VERSION
+"$AT" --version | tee "$SB/evidence/version.txt"    # must equal VERSION
 "$AT" --help >/dev/null && echo "help OK"
 ```
 
 ## Phase 4: Core surfaces
 
 ```bash
-"$AT" install            # full global install into the sandbox HOME
+"$AT" install            # global install inside the container's default HOME
 "$AT" doctor             # must end: Errors: 0 | Warnings: 0
 "$AT" status
 "$AT" plugin list        # pack count must match app/plugins/
@@ -7838,8 +7912,13 @@ for D in "$HOME"/.claude/skills/*/; do
   rel=${ref##*\$\{CLAUDE_SKILL_DIR\}/}
   printf '%-22s %-10s %-26s ' "$s" "$interp" "$rel"
   [ -f "$D/$rel" ] || { echo 'PATH DOES NOT RESOLVE'; continue; }
-  out=$(CLAUDE_SKILL_DIR="$D" timeout 20 "$interp" "$D/$rel" --help </dev/null 2>&1 | head -1)
-  printf 'rc=%s %s\n' "$?" "$(echo "$out" | cut -c1-40)"
+  if out=$(CLAUDE_SKILL_DIR="$D" timeout 20 "$interp" "$D/$rel" --help </dev/null 2>&1); then
+    rc=0
+  else
+    rc=$?
+  fi
+  printf '%s\n' "$out" > "$SB/evidence/skill-$s.log"
+  printf 'rc=%s %s\n' "$rc" "$(printf '%s\n' "$out" | head -1 | cut -c1-40)"
 done
 ```
 
@@ -7980,37 +8059,59 @@ again, pointing its source-override variable at a dead URL:
 - [ ] `plugin status` says the pack is inert and names the fix
 - [ ] Re-installing without the broken source recovers
 
-## Phase 7: Prove the real environment is untouched
+## Phase 7: Verify the host configuration
+
+Exit the recorded container shell. This returns to the unchanged host terminal
+from Phase 1. Run fingerprint_host there, not through docker exec and not in a
+shell that changed HOME:
 
 ```bash
-python3 -c "
-import json, pathlib
-d = json.loads(pathlib.Path.home().joinpath('.softspark/ai-toolkit/plugins.json').read_text())
-print('plugins.json:', d['targets']['claude'])
-p = pathlib.Path.home() / '.claude/settings.json'
-print('pack hook leaked into real settings:', '<pack>' in json.dumps(json.loads(p.read_text()).get('hooks', {})) if p.exists() else False)
-print('pack paths in real ~/.softspark:', len(list(pathlib.Path.home().joinpath('.softspark').rglob('*<pack>*'))))
-"
+fingerprint_host > "$EVIDENCE/host-after.json"
+cmp -s "$EVIDENCE/host-before.json" "$EVIDENCE/host-after.json" || {
+  diff -u "$EVIDENCE/host-before.json" "$EVIDENCE/host-after.json"
+  echo "Host configuration changed: investigate before accepting the release."
+  exit 1
+}
+docker inspect "$SMOKE_CONTAINER" > "$EVIDENCE/container-after.json"
 ```
 
-All three must show the pre-test state.
+The fingerprints must match. This proves the enumerated managed settings stayed
+unchanged; the recorded container configuration separately proves there were no
+host mounts or shared host namespaces. Do not claim to have hashed the whole
+home directory, or print settings contents to demonstrate isolation.
 
-## Phase 8: Clean up
+## Phase 8: Preserve evidence and remove only the owned container
 
-`guard-destructive.sh` blocks `rm -rf` on a `PreToolUse` hook, so removal goes
-through an enumerated delete that reports what it removed:
+Run on the host, after leaving the container shell. Confirm ownership before any
+cleanup, then copy the recorded session, npm provenance metadata, and CLI version.
+Keep the host evidence directory for the release record.
 
 ```bash
-python3 -c "
-import pathlib, shutil
-sb = pathlib.Path('$SB')
-assert sb.is_dir() and str(sb).startswith(('/tmp', '/var/folders')), sb
-n = sum(1 for _ in sb.rglob('*') if _.is_file())
-shutil.rmtree(sb)
-print(f'removed {sb} ({n} files)')
-"
+test "$(docker inspect --format '{{index .Config.Labels "org.softspark.release-smoke"}}' "$SMOKE_CONTAINER")" = "$SMOKE_CONTAINER" || {
+  echo "Container ownership does not match; refusing cleanup."
+  exit 1
+}
+docker logs "$SMOKE_CONTAINER" > "$EVIDENCE/container.log" 2>&1
+mkdir -p "$EVIDENCE/container"
+docker cp "$SMOKE_CONTAINER:/tmp/ai-toolkit-smoke/evidence/." "$EVIDENCE/container/" || {
+  echo "Evidence transfer failed; keep the container and investigate."
+  exit 1
+}
+test -f "$EVIDENCE/container/session.log" || {
+  echo "Session evidence is missing; refusing cleanup."
+  exit 1
+}
+docker stop "$SMOKE_CONTAINER"
+docker rm "$SMOKE_CONTAINER"
+printf 'Evidence retained: %s\n' "$EVIDENCE"
 ```
 
+There are no host bind mounts or named volumes to delete. Never bypass a
+destructive-command guard with Python, shutil.rmtree, another interpreter, or a
+different deletion tool. If a guard rejects cleanup, leave the owned container
+and evidence in place and report the rejection through the normal approval
+mechanism. Do not prune Docker resources or delete unrelated temporary files.
+
 ## Success criteria
 
 | Area | Criterion |
@@ -8024,12 +8125,12 @@ print(f'removed {sb} ({n} files)')
 | Pack update | Current version silent; stale version updates and re-records |
 | Pack removal | Zero residue in `~/.softspark` and `settings.json`; re-install works |
 | Degraded path | Fetch failure is inert, loud in status, and recoverable |
-| Isolation | Real `~/.claude` and `~/.softspark` byte-identical to pre-test |
+| Isolation | Host-side managed-settings fingerprints match; container has no host mounts or shared host namespaces |
 
 ## Related
 
 - [Release Preparation](sop-release.md) — run before tagging
-- [Release Verification](sop-release-verification.md) — the maintainer-install checks
+- [Release Verification](sop-release-verification.md) — cross-editor checks of the isolated npm artifact
 - [rtk-pack Retirement](../history/completed/rtk-pack-retirement-20260727.md) — what happened the one time this SOP was written and not run
 
 ---
@@ -8142,9 +8243,9 @@ title: "SOP: Release Verification"
 category: procedures
 service: ai-toolkit
 tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif, dsh]
-version: "1.8.0"
+version: "1.8.2"
 created: "2026-04-08"
-last_updated: "2026-09-01"
+last_updated: "2026-09-06"
 description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit. Verifies CLI, native Codex and GitHub Copilot surfaces, explicit DSH lifecycle, Claude app export, doctor, validation, tests, eject, provenance, SARIF, and per-skill permissions."
 ---
 
@@ -8162,12 +8263,30 @@ Verifies all critical paths from the user's perspective.
 
 **Prerequisites:**
 - Node.js >= 18, Python 3, `bats`, git
-- `@softspark/ai-toolkit` installed globally
+- The target version of `@softspark/ai-toolkit` installed in a disposable test environment
 
 **Time:** 10-15 minutes (full), 2 minutes (quick checklist)
 
 ---
 
+## Verification environment
+
+Run installation, update, eject and editor smoke checks in a disposable
+container or VM with its own OS user and default home directory. Do not
+reassign `HOME` or `CODEX_HOME`, mount the operator's home/authentication
+directories, or alter the global installation used by an active session.
+Use the packed release candidate before publication and the exact npm version
+after publication; the installed package must be the source of runtime checks.
+Source validation and test commands still run from the matching release checkout.
+
+A scratch project alone does not isolate home-scoped writes. In particular,
+the live Augment checks in Phase 9 write user settings. Execute them inside
+the disposable environment, retain logs outside it, and remove only resources
+created for this verification run. Do not treat a dry-run as proof that emitted
+files parse or that a second install is idempotent.
+
+---
+
 ## Quick Checklist (TL;DR)
 
 The 14 core commands below must pass. Releases that change DSH must also complete Phase 10.
@@ -8262,9 +8381,11 @@ ai-toolkit status
 ```
 
 **Verify `--dry-run`:**
-- [ ] Agents: 44
-- [ ] Skills: 108
-- [ ] Hooks merged into settings.json
+- [ ] Agent and skill totals match the target package's `app/agents/` and
+      `app/skills/*/SKILL.md` inventory; compare with that release's validator
+      output and README badges, not a number copied from an older release
+- [ ] Dry-run describes the planned hook merge; the isolated installed copy
+      contains the expected hooks in settings.json
 - [ ] "Other AI Tools" lists documented global targets (with `--editors`): aider, antigravity, augment, cline, codex, copilot, cursor, gemini, opencode, roo, windsurf. Scope varies: Codex uses `$CODEX_HOME` (default `~/.codex`) plus `$HOME/.agents/skills`; Copilot uses `$COPILOT_HOME` (default `~/.copilot`); cursor has only `~/.cursor/hooks.json`; antigravity has the `~/.gemini/*/skills` pointer. Cursor and Antigravity rules remain project-only.
 
 **Verify `status`:**
@@ -8334,9 +8455,12 @@ python3 scripts/audit_skills.py --ci
 ```
 
 **Verify validate.py:**
-- [ ] Agents: 44, Skills: 108, Tests: exactly the current README badge count
-- [ ] Hook events: 14, Hook scripts: >= 30
-- [ ] Plugin packs >= 10, KB documents >= 20
+- [ ] Agent, skill and Bats test totals match the current release inventory
+      and README badges, as checked by the validator's metadata contracts
+- [ ] Hook events/scripts match `app/hooks.json` and the shipped hook files
+- [ ] Every shipped plugin pack and KB document passes its validator; compare
+      inventory with the release checkout rather than requiring an obsolete
+      fixed minimum number of packs or documents
 - [ ] `Errors: 0 | Warnings: 0` → `VALIDATION PASSED`
 
 **Verify audit_skills.py:**
@@ -8349,7 +8473,7 @@ python3 scripts/audit_skills.py --ci
 ## Phase 6: Tests (3-5 min)
 
 ```bash
-# Run ONCE, capture to file, then parse. Full suite is 669+ bats cases —
+# Run ONCE, capture to file, then parse. Use the current release's Bats count;
 # re-running it per check (tail / grep ok / grep not ok piped separately)
 # wastes minutes every release. Always cache the output.
 npm test > /tmp/npm-test.log 2>&1
@@ -8362,7 +8486,7 @@ echo "exit:   $exit"
 
 **Verify:**
 - [ ] `exit == 0`
-- [ ] `ok == expected test count` (e.g., 945 on v3.0.0)
+- [ ] `ok == expected test count` from the current release's metadata contracts
 - [ ] `not ok == 0`
 - [ ] Bats runs tests in parallel (4 jobs)
 - [ ] Groups: agents, autodetect, cli, generators, guards, hooks, inject,
@@ -8473,7 +8597,7 @@ AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run
 
 These verify the native-surface generators shipped in v3.0.0 actually emit the right files for the right profiles, and that the tool registry stays in sync with shipped generators.
 
-> **Safety warning — HOME-scoped writes:** Running `--profile full` with `augment` in the editor list writes to `$HOME/.augment/settings.json` (Augment stores hooks under HOME, not per-project). Use `--dry-run` for verification unless you intend to carry ai-toolkit hook entries on this machine. The generator is marker-safe (only rewrites its own `_source: ai-toolkit` entries) but is still a side-effect.
+> Run this phase inside the disposable verification environment. `--profile full` with `augment` writes to `$HOME/.augment/settings.json`, so a temporary project on the operator's machine is insufficient. Dry-run checks cover the planned paths; Phases 9.4 and 9.5 must also exercise actual writes in isolation.
 
 ### 9.1 `--profile full` emits every native surface
 
@@ -8550,7 +8674,9 @@ The bats suite validates JSON shape at generation time. This re-checks that what
 D=/tmp/aitk-json-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
 ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex,copilot --profile full >/dev/null 2>&1
 for f in .cursor/hooks.json .devin/hooks.v1.json .gemini/settings.json .codex/hooks.json .github/hooks/ai-toolkit.json "$HOME/.augment/settings.json"; do
-  [ -f "$f" ] && python3 -c "import json; json.load(open('$f'))" && echo "OK: $f"
+  [ -f "$f" ] || { echo "MISSING: $f"; exit 1; }
+  python3 -c 'import json, sys; json.load(open(sys.argv[1]))' "$f" || exit 1
+  echo "OK: $f"
 done
 ```
 
@@ -8587,15 +8713,17 @@ app-native rules skill, bundled agents/skills, and plugin-relative Cowork hooks.
 
 Run this phase whenever the release changes the `dsh` target, package pins, preset lifecycle, or DSH compatibility documentation. Use a new task-specific `DSH_HOME`; never replace `HOME` or reuse a regular profile.
 
-Prerequisites: DSH `0.1.1-rc.2`, pnpm `>=11.7.0,<12.0.0`, Codex logged in through ChatGPT, Claude Code logged in natively, and GitHub Copilot CLI logged in natively. Do not supply provider API keys.
+Prerequisites: DSH `0.1.2-rc.1`, pnpm `>=11.7.0,<12.0.0`, Codex logged in through ChatGPT, Claude Code logged in natively, and GitHub Copilot CLI logged in natively. Do not supply provider API keys. The lifecycle automatically installs the scoped Claude Agent SDK `0.3.263` override and checks the actual provider and SDK metadata; no manual vendor configuration is needed.
 
 ```bash
 DSH_SMOKE_ROOT="$(mktemp -d)"
 export DSH_HOME="$DSH_SMOKE_ROOT/dsh-home"
+export AI_TOOLKIT_HOME="$DSH_SMOKE_ROOT/toolkit-state"
+mkdir -p "$DSH_HOME"
 
 ai-toolkit dsh install --profile web
 ai-toolkit dsh doctor --profile web
-dsh --profile web --host 127.0.0.1 --port 0 --no-open
+DSH_TELEMETRY_DISABLED=1 dsh --profile web --host 127.0.0.1 --port 0 --no-open
 ```
 
 In a new `softspark-orchestrator` session, select the `codex` provider and run two standalone marker prompts:
@@ -8609,7 +8737,7 @@ Stop DSH, then remove only the managed profile artifacts:
 ai-toolkit dsh uninstall --profile web --yes
 ```
 
-**Verify:** both tool results have `isError=false`, both turns end as `completed`, `doctor` reports no recovery requirement before uninstall, and an unrelated preset fixture remains unchanged. Preserve only redacted event sequence evidence; never attach credentials, auth files, or full private prompts.
+**Verify:** both tool results have `isError=false`, both turns end as `completed`, `doctor` reports `Claude SDK: compatible (0.3.263)` and no recovery requirement before uninstall, and an unrelated preset fixture remains unchanged. The task-specific `AI_TOOLKIT_HOME` keeps lifecycle state separate from the operator's installation; `HOME` remains unchanged. Preserve only redacted event sequence evidence; never attach credentials, auth files, or full private prompts.
 
 ---
 
@@ -8682,9 +8810,9 @@ title: "SOP: Release Preparation"
 category: procedures
 service: ai-toolkit
 tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem, shellcheck]
-version: "1.15.0"
+version: "1.15.1"
 created: "2026-04-10"
-last_updated: "2026-09-02"
+last_updated: "2026-09-06"
 description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, version sync, changelog, artifact regeneration, validation, branch CI, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, checksum-pin, ShellCheck, licensing, exact-tag assertions, and a green Ubuntu/macOS branch-CI gate before any release tag is created."
 ---
 
@@ -8694,6 +8822,13 @@ Complete checklist for preparing a new `@softspark/ai-toolkit` release.
 Run this **before** tagging. After tagging and publishing, run the
 [Release Verification SOP](sop-release-verification.md) to smoke-test.
 
+Installation smoke uses a disposable container or VM with its own default
+home directory, as described in the verification SOP. Test the packed release
+candidate before publishing and the exact npm version afterward. Keep the
+operator's installed toolkit, editor settings and authentication directories
+outside that environment. Compare component counts with the current release
+inventory and validator output instead of historical constants in a checklist.
+
 **Pipeline:**
 ```
 Ecosystem Sync SOP (drift check + generator updates)
@@ -9686,9 +9821,9 @@ title: "AI Toolkit - Architecture Overview"
 category: reference
 service: ai-toolkit
 tags: [architecture, overview, design, structure]
-version: "1.10.0"
+version: "1.10.1"
 created: "2026-03-23"
-last_updated: "2026-09-01"
+last_updated: "2026-09-06"
 description: "Architecture of ai-toolkit: install ownership, runtime adapters, the explicit DSH target, skill tiers, and project integration."
 ---
 
@@ -9998,7 +10133,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 
 ## Quality Hooks
 
-29 entries across 14 lifecycle events. See [hooks-catalog.md](hooks-catalog.md) for full details.
+28 entries across 14 lifecycle events. See [hooks-catalog.md](hooks-catalog.md) for full details.
 
 | Hook | Trigger | Script | Action |
 |------|---------|--------|--------|
@@ -11939,9 +12074,9 @@ title: "AI Toolkit - DSH Compatibility"
 category: reference
 service: ai-toolkit
 tags: [dsh, deepseek-harness, subscriptions, lifecycle, compatibility]
-version: "1.7.0"
+version: "1.8.0"
 created: "2026-08-31"
-last_updated: "2026-09-01"
+last_updated: "2026-09-06"
 description: "Compatibility contract for project skills and the explicit SoftSpark package lifecycle in DeepSeek Harness."
 ---
 
@@ -11951,14 +12086,14 @@ description: "Compatibility contract for project skills and the explicit SoftSpa
 
 ai-toolkit supports DeepSeek Harness as an explicit developer-preview target. The integration is maintained by SoftSpark as a community compatibility layer. DeepSeek AI has not endorsed it.
 
-The reviewed runtime is DSH `0.1.1-rc.2`. Newer upstream prereleases are not covered until they pass the same qualification. Isolated pre-tag and exact-registry post-release profiles completed the Claude Code and Copilot Gemini marker roundtrips through a Codex parent on 2026-09-01.
+The 4.33.0 lifecycle targets DSH `0.1.2-rc.1`, with the exact package pair below. Other upstream prereleases require their own qualification. Historical marker roundtrips from 2026-09-01 used DSH `0.1.1-rc.2`; version-specific evidence is recorded under Qualification below.
 
 ## Project vs Profile Outputs
 
 | Surface | Command | Managed output | Explicit non-output |
 |---|---|---|---|
 | Project install | `ai-toolkit install --local --editors dsh` | `CLAUDE.md`, `.claude/settings.local.json`, `.claude/constitution.md`, detected language rules, other generic local outputs, and the DSH-specific one-level `.agents/skills/<name>/SKILL.md` catalog with bundled resources | No `$DSH_HOME` writes, npm package changes, profile changes, preset changes, or credential reads |
-| DSH profile | `ai-toolkit dsh install --profile web` | Two exact npm dependencies in the named profile, the released `softspark-orchestrator` preset, and ai-toolkit ownership state | No project files, provider login, API keys, unrelated plugins, or user presets |
+| DSH profile | `ai-toolkit dsh install --profile web` | Two exact npm dependencies, the scoped Claude SDK override and missing profile initialization files, the released `softspark-orchestrator` preset, and ai-toolkit ownership state | No project files, provider login, API keys, unrelated plugins, or user presets |
 
 DSH is excluded from `--editors all`, auto-detection, default profiles, and default editor selection. Naming `dsh` without `--local` is not a supported project install route.
 
@@ -11986,13 +12121,31 @@ The DSH profile defaults to `web` when `--profile` is omitted. `DSH_HOME` select
 
 | Component | Reviewed version | Role |
 |---|---:|---|
-| DeepSeek Harness | `0.1.1-rc.2` | Profile host and plugin manager |
+| DeepSeek Harness | `0.1.2-rc.1` | Profile host and plugin manager |
 | pnpm | `>=11.7.0,<12.0.0` | Package manager used by the DSH plugin command |
-| `@softspark/dsh-codex` | `1.0.0` | Codex parent provider through local `codex app-server` |
-| `@softspark/dsh-orchestrator` | `1.0.1` | Claude Code and GitHub Copilot Gemini delegation bundle plus released preset |
+| `@softspark/dsh-codex` | `1.5.0` | Codex parent provider through local `codex app-server` |
+| `@softspark/dsh-orchestrator` | `2.0.0` | Claude Code and GitHub Copilot Gemini delegation bundle plus released preset |
+| Claude Agent SDK | `0.3.263` | Exact profile override for the DSH Claude provider's bundled CLI |
 
 Install and update use exact package arguments with `--save-exact`. Arbitrary DSH prereleases and unpinned SoftSpark packages are outside this contract.
 
+Install and update also configure the exact profile selector
+`@deepseek-ai/dsh-subagent-claude-code@0.1.2-rc.1>@anthropic-ai/claude-agent-sdk`
+to `0.3.263`. DSH's original SDK `0.3.241` embeds Claude Code `2.1.241`, which
+current models reject even when the standalone Claude command is up to date.
+The override is applied through pnpm's JSON configuration API. Unrelated
+settings and overrides are preserved; an incompatible SDK override or an
+explicit non-hoisted package layout fails with guidance before modification.
+The installed SDK's actual package metadata is checked before state is committed.
+
+Upgrade the DSH runtime to `0.1.2-rc.1` before running this release's profile
+update. Ownership records for the earlier exact package pair remain valid and
+are migrated by `ai-toolkit dsh update`. On failure, rollback uses the versions
+recorded before the operation. The optional `dsh-file-preview` and
+`dsh-process-console` UI bundles are separate profile additions; their `2.0.0`
+line targets the new DSH client APIs, and the toolkit preserves them as unrelated
+dependencies.
+
 The reviewed DSH tag declares `pnpm@11.7.0`. The isolated cold-install environment used Corepack pnpm `11.24.0`, so the lifecycle accepts stable pnpm releases from `11.7.0` through the end of major 11. Before it creates the lifecycle lock or changes a profile, it resolves exact DSH and pnpm command paths from the minimal child `PATH`, records their command and resolved-file identities, and runs their version probes with a five-second bound. Missing, nonzero, timed-out, malformed, or unsupported pnpm probes fail with no package, preset, state, or lifecycle artifact.
 
 ## Subscription and Authentication Boundaries
@@ -12047,6 +12200,17 @@ The DSH record stores the canonical DSH home, profile, exact package versions, p
 
 The published npm packages own their installed code. The canonical preset source is `@softspark/dsh-orchestrator/agent-presets/softspark-orchestrator` inside the exact installed package. ai-toolkit copies and verifies that tree. It does not reconstruct the preset.
 
+Missing profile initialization files are created exclusively under pinned
+directories using the qualified DSH profile schema before invoking the external
+configuration command. A file appearing concurrently is never adopted as owned,
+even when its bytes match. The transaction snapshots `pnpm-workspace.yaml` bytes, mode and file identity in
+addition to package state. Ordinary failures restore that prestate through the
+same guarded file restoration used for the profile manifest. Default profile
+files created during initialization are removed only while their recorded
+identities still match. Unexpected settings changes or ambiguous failed
+external writes remain preserved behind a recovery marker. Configuration
+contents are never copied into lifecycle state, receipts, or error messages.
+
 Mutations first take a nonblocking exclusive POSIX `flock` on the already pinned `DSH_HOME` directory descriptor, then claim the bounded canonical lifecycle lock and use the shared state lock with compare-and-swap publication. Directory locking is independent of the replaceable lock filename. It remains held across sentinel scans, package and preset mutation, normal canonical-lock release, or recovery-sentinel creation plus file and directory `fsync`. A competing lifecycle must acquire the same directory lock before it can scan recovery state or claim the canonical name. The immutable prerequisite record is revalidated after lock acquisition and before every package mutation or package rollback. A replaced or removed executable, or a new earlier `pnpm` PATH shadow, blocks the command. The verified pnpm command directory is placed first in the child PATH so DSH's literal `pnpm` lookup resolves to the probed command. Install, update, and uninstall verify the profile manifest, package trees, preset identity, and unrelated dependencies before and after each external package-manager command. Rollback restores the immutable pre-operation target. It does not reinterpret concurrent bytes as owned data.
 
 Each DSH plugin add, update, remove, or rollback command has a 300-second process bound, separate from the short prerequisite probe. This bound accommodates cold package resolution without promising registry or network latency. Every mutation starts DSH in a dedicated POSIX session and process group. A timeout or interruption signals the complete group, escalates from `SIGTERM` to `SIGKILL` when needed, and waits for confirmed group exit before rollback. If exit cannot be confirmed, package rollback is blocked and deterministic inspection steps are reported. Child stdout and stderr remain suppressed from user-facing errors.
@@ -12080,8 +12244,17 @@ The first native target also excludes DSH hook bridging, MCP bridging, arbitrary
 
 `ai-toolkit dsh doctor` is read-only. It reports the DSH runtime version, pnpm availability and version, package pins, package-tree and preset ownership, state consistency, lifecycle lock recovery artifacts, staging paths, and recovery markers. A recovery marker keeps `Recovery needed: yes` visible until the operator resolves the named paths.
 
+Doctor also checks the required SDK override and installed SDK version. It
+queries pnpm directly only when the profile directory exists. It never uses
+`dsh plugin` for inspection, because that command initializes missing profiles.
+
 `ai-toolkit dsh uninstall --yes` removes only the recorded SoftSpark packages, preset, and profile state. Drift or ownership ambiguity stops removal. Unrelated profile dependencies, patch files, presets, and state keys remain unchanged.
 
+Successful uninstall retains the scoped SDK compatibility setting and the
+profile's pnpm layout. They are runtime prerequisites for a later reinstall,
+not ownership of the user's entire profile. Failed operations restore their
+pre-operation configuration unless concurrent edits make that unsafe.
+
 ## Verification
 
 Run the static and isolated checks without modifying a regular DSH profile:
@@ -12099,11 +12272,45 @@ ai-toolkit dsh doctor --profile web
 ai-toolkit dsh uninstall --profile web --dry-run --yes
 ```
 
-Phase 3 real-profile qualification completed with a task-specific `DSH_HOME`, exact published package artifacts, and native vendor logins. The pre-tag candidate and exact npm registry package both produced successful child and parent markers through `subagent_claude_code` and `subagent_gemini_copilot`; no provider API key was supplied or handled. The isolated DSH processes stopped cleanly and the unrelated profile fixture remained intact.
+### Historical qualification, 2026-09-01
+
+The earlier DSH `0.1.1-rc.2` package pair completed real-profile qualification
+with a task-specific `DSH_HOME`, exact published package artifacts, and native
+vendor logins. The pre-tag candidate and registry package produced successful
+child and parent markers through `subagent_claude_code` and
+`subagent_gemini_copilot`. No provider API key was supplied or handled; the
+isolated processes stopped and the unrelated profile fixture remained intact.
+
+### DSH 0.1.2-rc.1 qualification
+
+On 2026-09-06, the installed 4.33.0 candidate completed install, doctor,
+update, doctor, a controlled second-package failure with real pnpm rollback,
+doctor and uninstall against the published Codex 1.5.0/orchestrator 2.0.0
+pair. Rollback preserved the manifest, pnpm settings, ownership state and
+unrelated preset byte for byte. Doctor reported the exact package versions,
+Claude SDK 0.3.263 and no recovery requirement. Uninstall removed the managed
+packages, preset and profile ownership while retaining the unrelated preset
+and runtime SDK prerequisite. Both state roots were disposable; HOME stayed
+unchanged.
+
+The composed web host returned the Claude and Gemini child markers through
+the Codex parent. Browser checks covered cancellation, restart, the native
+child transcript and preservation of the parent session. The DSH package
+verification records retain those runtime results and their separate exact
+registry signature/provenance checks.
+
+The toolkit candidate also passed 1,989 Bats and 354 Python tests. An
+unmounted disposable container passed global install, status, doctor, local
+installation for all editors, repeated installation, eject and the official
+Claude 2.1.263 plugin validator. Exact published toolkit artifact results are
+recorded on the 4.33.0 release page after publication.
 
 ## Preview and Upstream Drift
 
-DeepSeek Harness describes itself as a developer preview with compatibility-breaking changes. The upstream release feed published `0.1.2-alpha.2` after the reviewed `0.1.1-rc.2` line. ai-toolkit does not adopt that prerelease by inference.
+DeepSeek Harness is a developer preview with compatibility-breaking changes.
+On 2026-09-06, npm `latest` pointed to `0.1.2-rc.1`. GitHub also listed
+`0.1.3-alpha.1`, but that exact CLI version was absent from npm. It is outside
+this lifecycle contract.
 
 Use the registry doctor to detect documentation, capability-marker, and local version changes. A new upstream version requires source review, focused fixture updates, isolated real-profile qualification, and explicit pin changes before support moves.
 
@@ -12111,10 +12318,10 @@ Use the registry doctor to detect documentation, capability-marker, and local ve
 
 - [DeepSeek Harness documentation](https://deepseek-harness.github.io/deepseek-harness/)
 - [DeepSeek Harness releases](https://github.com/deepseek-ai/deepseek-harness/releases)
-- [Reviewed DSH 0.1.1-rc.2 release](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.1-rc.2)
-- [Reviewed DSH package-manager declaration](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.1-rc.2/package.json)
-- [Reviewed DSH CLI profile and plugin contract](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.1-rc.2/apps/cli/reference/README.md)
-- [Reviewed DSH skill discovery contract](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.1-rc.2/docs/subsystems/skills.md)
+- [Reviewed DSH 0.1.2-rc.1 release](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.2-rc.1)
+- [Reviewed DSH package-manager declaration](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.2-rc.1/package.json)
+- [Reviewed DSH CLI profile and plugin contract](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.2-rc.1/apps/cli/reference/README.md)
+- [Reviewed DSH skill discovery contract](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.2-rc.1/docs/subsystems/skills.md)
 - [PATH: kb/reference/manifest-install.md]
 - [PATH: kb/history/completed/dsh-native-install-target-plan.md]
 
@@ -14066,7 +14273,7 @@ service: ai-toolkit
 tags: [rules, languages, coding-style, testing, patterns, security]
 version: "2.2.0"
 created: "2026-04-07"
-last_updated: "2026-09-04"
+last_updated: "2026-09-06"
 description: "Reference for the language-specific rules system: 13 per-language rule sets shipped as knowledge skills, plus common rules installed as Claude Code path-scoped project rules."
 ---
 
@@ -14139,6 +14346,12 @@ app/rules/
 
 ## Rule Categories
 
+The common security rules distinguish safe, actionable failure messages from
+private diagnostics. Common testing rules cover API error contracts and prohibit
+overlapping runners that reset a shared database. The `api-patterns` skill carries
+the focused error-contract guidance; the `review` checklist checks the same
+failure boundaries. These are content rules, not new hooks or runtime permissions.
+
 | Category | Filename | Content |
 |----------|----------|---------|
 | `coding-style` | `coding-style.md` | Naming, formatting, idiomatic constructs, linter config |
@@ -16265,7 +16478,7 @@ service: ai-toolkit
 tags: [skills, domain-knowledge, catalog, task-skills, hybrid-skills]
 version: "1.5.0"
 created: "2026-03-23"
-last_updated: "2026-08-06"
+last_updated: "2026-09-06"
 description: "Complete skills catalog with task, hybrid, and knowledge skills. Includes Codex adaptation notes, effort levels, skill-scoped hooks, executable scripts, security auditor, and persona presets."
 ---
 
@@ -16383,7 +16596,7 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | Skill | Directory | Domain |
 |-------|-----------|--------|
 | **app-builder** | `skills/app-builder/` | Full-stack application architecture |
-| **api-patterns** | `skills/api-patterns/` | REST/GraphQL design, versioning, error handling |
+| **api-patterns** | `skills/api-patterns/` | API design, versioning, actionable error contracts and safe retries; focused `reference/error-contracts.md` |
 | **database-patterns** | `skills/database-patterns/` | Schema design, indexing, query optimization |
 | **flutter-patterns** | `skills/flutter-patterns/` | Flutter/Dart architecture, state management |
 | **ecommerce-patterns** | `skills/ecommerce-patterns/` | E-commerce: catalog, cart, checkout, payments |