@softspark/ai-toolkit 4.29.1 → 4.30.2

package/kb/history/completed/dsh-integration-plan-superseded.md

@@ -0,0 +1,322 @@
+---
+title: "Plan: DeepSeek Harness (dsh) Integration"
+category: planning
+service: ai-toolkit
+tags:
+  - dsh
+  - deepseek-harness
+  - cordis
+  - integration
+  - skills
+  - subagents
+  - multi-model
+  - acp
+  - emission-target
+doc_type: plan
+status: superseded
+created: "2026-08-25"
+last_updated: "2026-08-27"
+closed: "2026-08-27"
+completion: "Functional objective delivered through standalone 1.0.0 modules; native ai-toolkit install target moved to a replacement plan"
+superseded_by: "kb/history/completed/dsh-native-install-target-plan.md"
+description: "Superseded DSH integration plan retained as the historical record of the subscription-backed runtime validation and the architecture split into dsh-codex and dsh-orchestrator."
+---
+
+# Plan: DeepSeek Harness (dsh) Integration (Superseded)
+
+**Status:** Superseded on 2026-08-27
+**Completion:** Functional objective delivered; native ai-toolkit install target moved to a replacement plan
+**Created:** 2026-08-25
+**Origin:** Requirement for a single window driving three already-owned subscriptions (Claude Max, ChatGPT Plus, Gemini) without buying API credits
+**Upstream reviewed:** `deepseek-ai/deepseek-harness` @ `b150a55` (2026-08-21), package version `0.1.1-rc.2`, MIT, developer preview
+**Replacement:** [`dsh-native-install-target-plan.md`](dsh-native-install-target-plan.md)
+
+## Closure Record
+
+This plan mixed two outcomes that now have different ownership:
+
+1. The user-facing runtime objective is complete. `@softspark/dsh-codex@1.0.0` provides the ChatGPT-backed Codex parent, and `@softspark/dsh-orchestrator@1.0.0` delegates bounded tasks to Claude Code and GitHub Copilot Gemini. Both are public Apache-2.0 modules with CI, provenance, security gates, KB, release SOPs, and post-release verification.
+2. Direct Gemini delegation through a personal Google AI Pro/Ultra login is not supported. The delivered route uses GitHub Copilot CLI ACP, GitHub authentication, and GitHub plan credits. No Google credential proxy or Antigravity workaround is part of the system.
+3. The native ai-toolkit emission target was not implemented. `ai-toolkit install --local --editors dsh`, managed preset installation, DSH-specific uninstall, registry metadata, and focused bats coverage move to the replacement plan.
+
+The historical phases below remain useful as the research and validation record. Their status table is updated to show what shipped, what was cut, and what moved.
+
+## 1. Objective
+
+Add dsh as the twelfth emission target so a single harness can delegate to Claude Code, Codex,
+and Gemini CLI while each child authenticates natively against its own vendor subscription.
+
+**Non-goal:** rewriting ai-toolkit on top of dsh. The toolkit stays the control plane and source
+of truth. dsh is a runtime it emits to, exactly like Codex CLI and opencode.
+
+**Hard constraint that shaped this plan:** Anthropic prohibits third-party tools from routing
+Free/Pro/Max OAuth credentials, and enforces it server-side without notice. Any harness that
+speaks the Anthropic API itself therefore requires a separate API key. dsh avoids this by
+spawning the real Claude Code binary instead of routing credentials.
+
+## 2. Why dsh satisfies the subscription constraint
+
+`packages/subagent/subagent-claude-code/README.md` states the provider deliberately omits the SDK
+`settingSources` option, so the official Agent SDK reads the host's normal user, project, and local
+Claude settings relative to the parent session cwd, including native account state. It neither
+copies nor filters those files and does not create or modify login state. Authentication and
+account state remain native; the bundle supplies the CLI but does not create an account, log in,
+or probe an account. Credential-shaped ambient variables are scrubbed before the explicit `env`
+overlay, so `ANTHROPIC_API_KEY` reaches the child only when supplied deliberately. The runtime is
+pinned to `@anthropic-ai/claude-agent-sdk@0.3.220` (Claude Code 2.1.220) and the executable comes
+from the SDK platform package, not from `PATH`.
+
+Consequence: the subscription is exercised by Claude Code authenticating itself, not by dsh
+presenting the user's credentials to Anthropic.
+
+### Subagent providers present in the tree
+
+| Package | Spawns | Subscription exercised |
+|---|---|---|
+| `subagent-claude-code` | Agent SDK to native `claude` | Claude Max |
+| `subagent-codex` | Codex | ChatGPT Plus |
+| `subagent-acp` | any Agent Client Protocol agent (Gemini CLI ships native ACP) | Gemini |
+| `subagent-dsh-sdk` | dsh SDK loop | model provider config |
+| `subagent-fork-in-process` | forked in-process session | inherited |
+| `subagent-spawn-in-process` | fresh in-process session | inherited |
+| `subagent-in-process-driver` | shared driver for the in-process providers | inherited |
+
+## 3. Verified compatibility surface
+
+### 3.1 Skill discovery is already satisfied
+
+`packages/skill/skill-filesystem` resolves roots in rank order:
+
+| Rank | Source | Path |
+|---|---|---|
+| 100 | `project-dsh` | `<projectRoot>/.dsh/skills` |
+| 200 | `project-agents` | `<projectRoot>/.agents/skills` |
+| 300 | `custom` | `Config.customSkillDirs` |
+| 400 | `user-dsh` | `<dshHome>/skills` (`$DSH_HOME`, default `~/.dsh`) |
+| 500 | `user-agents` | `<agentsHome>/skills` (`$DSH_AGENTS_HOME`, default `~/.agents`) |
+
+Skill format: single-level directory bundles `<name>/SKILL.md` or flat `<name>.md`. Frontmatter is
+an open YAML object; the provider interprets required `name` and `description` plus optional
+`whenToUse`, `metadata`, `disable-model-invocation`, and `user-invocable`. Names must be kebab-case.
+
+This is the ai-toolkit skill convention field for field. `scripts/generate_codex_skills.py` already
+mirrors every skill in `app/skills/` into `<target>/.agents/skills/<name>/`, native skills as
+symlinks to canonical `app/skills` and delegation-heavy skills as adapted wrappers through
+`codex_skill_adapter.sync_codex_skill`.
+
+**No new skill generator is required.** Rank 200 is the same directory Codex CLI consumes.
+
+A bare checkout shows only `ai-toolkit-skill-catalogue` under `.agents/skills/` because
+`enable_codex_skills` defaults to `False` for the standalone generator; the installer sets it when
+Codex is selected.
+
+### 3.2 Presets are compositions, not personas
+
+`packages/preset/agent-presets` treats a preset as a plugin composition: the composition file is a
+top-level list of plugin rows, with an optional sibling `preset.yml` carrying display `name` and
+`description` only. The `id` is the directory name and must match `[a-z0-9][a-z0-9-]*`; `trust`
+derives from the discovery root. Authoring is copy-only: `copy()` rejects a non-conforming id, an
+id already supplied by any root, and an unknown source, then re-tightens the copied tree to
+owner-only permissions and dereferences symlinks. A copied `preset.yml` keeps the description but
+drops `name` and roster `order`.
+
+Package-name rows resolve against the host composition rather than the preset directory, because a
+user-home preset cannot reach the harness through Node's upward `node_modules` walk. Relative
+paths resolve from the preset's own directory, so a preset's own plugin files and skill directories
+travel with it.
+
+**Implication:** mapping 44 agents onto 44 presets is architecturally wrong. Presets are session
+compositions (expect 2-3 of them). The 44 agents belong on the subagent surface.
+
+## 4. Gotchas that must become gates
+
+1. **Invocation frontmatter fails closed.** A camel-case spelling (`userInvocable`,
+   `disableModelInvocation`) or a non-boolean invocation value **drops the entire skill from
+   discovery** with a warning rather than falling back to a permissive default. Accepted boolean
+   spellings are YAML booleans plus case-insensitive `true`/`false`, `yes`/`no`, `on`/`off`,
+   `1`/`0`. Current emitters are clean; this must be enforced by `validate.py`, not left to chance.
+2. **Discovery is one level deep.** Only `<root>/<name>/SKILL.md` and `<root>/<name>.md` are
+   recognized. Nested skill trees and package manifests are ignored. Resources under `references`,
+   `scripts`, and `assets` inside a bundle are fine and do not invalidate the catalog.
+3. **Project root is the nearest `.git` ancestor.** Without that marker the provider falls back to
+   the supplied cwd. No alternate project-root marker, no monorepo subproject selection.
+4. **Symlinked skills.** `generate_codex_skills.py` emits symlinks into `app/skills`.
+   `watchFollowSymlinks` defaults to `true`, so this should hold, but it needs empirical
+   confirmation before being relied on.
+5. **Malformed entries disappear silently.** The model catalog receives no per-skill diagnostic and
+   cannot distinguish an absent skill from an invalid one.
+
+## 5. Open questions
+
+| # | Question | How to close |
+|---|---|---|
+| Q1 | Subagent definition format: how a delegatable agent such as `security-auditor` is declared | Moved to the replacement plan; the released orchestrator deliberately exposes two bounded static tools instead of mapping 44 toolkit agents |
+| Q2 | Whether `packages/hooks` ("Claude Code/Codex hook bridges + wire-protocol library") accepts the toolkit's `app/hooks/*.sh` directly | Moved to the replacement plan as an optional compatibility slice, not a prerequisite for the install target |
+| Q3 | Whether `subagent-acp` can drive Gemini CLI end to end on a Google login | Closed negative: individual Gemini CLI access ended; Antigravity has no ACP and prohibits third-party login use |
+| Q4 | Plugin row schema for a composition file | Closed by the released `softspark-orchestrator` preset and `cordis.patch.yml` |
+| Q5 | Whether Claude Max actually authenticates through the spawned CLI in practice | Closed positive by isolated Codex-to-Claude Max verification without an Anthropic API key |
+
+## 6. Progress Tracking
+
+| Phase | Deliverable | Depends on | Status |
+|---|---|---|---|
+| 0 | Empirical validation: dsh sees all 109 skills; subscription-backed providers run | none | completed through standalone modules; direct Google route replaced by Copilot Gemini |
+| 1 | `validate.py` gates for kebab-case invocation fields and one-level `.agents/skills` depth | 0 | moved to replacement Phase 1 |
+| 2 | `scripts/generate_dsh_preset.py` emitting 1-2 compositions | 0, Q4 | replaced by the released `softspark-orchestrator` preset; managed installation moved to the replacement plan |
+| 3 | 44 agents mapped onto the subagent surface | Q1 | cut; the released boundary exposes only Claude Code and Copilot Gemini delegation tools |
+| 4 | MCP servers and hook bridge | Q2 | cut from the runtime deliverable; optional compatibility work moved to the replacement plan |
+| 5 | `ecosystem_tools.json` entry, docs across the nine mandated files, bats coverage | 1-4 | native ai-toolkit registry, docs, tests, and uninstall moved to the replacement plan |
+
+### Phase 0 checkpoint: Codex primary provider verified (2026-08-26)
+
+- The checkpoint began at `@softspark/dsh-codex@0.1.0`; the public `1.0.0` release now bridges DSH to the official local `codex app-server`
+  over JSONL stdio. Codex retains sole ownership of ChatGPT authentication and tokens.
+- The isolated DSH profile loaded provider `codex`, exposed seven models, booted the Web UI
+  on `127.0.0.1:3080`, and completed end-to-end session prompts on Codex models.
+- The live app-server reported authentication kind `chatgpt`; no OpenAI API key was configured.
+- The final local tarball passed 92 tests, typecheck, lint, build, coverage, dependency,
+  signature, SARIF, package, and composition gates. Its SHA-256 is
+  `87db7be9f959de507d708bfa74feb4b5890b9b8a7a33d3520e31d91fcbe673c0`.
+- A persistent DSH session resumed the identical Codex thread after a host restart, and a live
+  cancellation ended with reason `aborted`.
+- The public `1.0.0` release keeps stable mode unchanged and exposes a bounded, opt-in
+  `experimentalDynamicTools` bridge. Dynamic-tool threads remain non-replayable after restart.
+
+Evidence and release gates live in the standalone repository:
+the public [softspark/dsh-codex](https://github.com/softspark/dsh-codex) repository.
+
+### Phase 0 checkpoint: SoftSpark orchestrator composition (2026-08-26)
+
+- `@softspark/dsh-codex@1.0.0` exposes an explicit bounded dynamic-tool bridge while stable mode remains unchanged.
+- `@softspark/dsh-orchestrator@1.0.0` is a separate Apache-2.0 public module with exact DSH dependencies, multi-OS CI, provenance, security gates, tests, KB, and release SOPs.
+- The isolated DSH profile loads `softspark-orchestrator` as its default preset and registers one-shot `subagent_claude_code` plus `subagent_gemini_copilot` tools.
+- A real Codex-to-DSH `todo_write` tool roundtrip completed on the final composition with no provider API keys.
+- Claude Max native login is verified. Google AI Pro/Ultra cannot be delegated through DSH: Gemini CLI ended individual access, Antigravity has no ACP, and its terms prohibit third-party use of account login. No proxy or token workaround will be implemented.
+- The final isolated profile completed both a neutral Codex-to-DSH tool call and a Codex-to-Claude Max delegation with exact markers and no provider API keys.
+
+## 7. Detailed Implementation
+
+### Phase 0 - Empirical validation (no code)
+
+```bash
+ai-toolkit install --local --editors codex     # populates .agents/skills/ with all 109
+npx @deepseek-ai/dsh web                        # UI on 127.0.0.1:3080
+```
+
+Verify, in order:
+
+1. The skill catalog lists 109 entries, not the single `ai-toolkit-skill-catalogue` pointer.
+2. Symlinked skill bodies load (gotcha 4).
+3. A `subagent-claude-code` delegation runs without an `ANTHROPIC_API_KEY` present (Q5).
+4. A `subagent-codex` delegation runs on the ChatGPT login.
+5. A `subagent-acp` delegation reaches Gemini CLI on the Google login (Q3).
+
+If step 3 fails, the entire premise collapses and the plan reverts to the ACP-in-JetBrains
+alternative recorded in section 10.
+
+### Phase 1 - Gates
+
+Extend `scripts/validate.py`:
+
+- Reject any emitted `SKILL.md` whose frontmatter carries `userInvocable` or
+  `disableModelInvocation`, or a non-boolean value for the kebab-case forms.
+- Reject any `SKILL.md` deeper than `<root>/<name>/SKILL.md` under `.agents/skills/`.
+- Reject skill directory names failing `[a-z0-9]+(-[a-z0-9]+)*`.
+
+These protect Codex CLI and opencode as well; the fail-closed behavior is what makes them
+non-optional rather than cosmetic.
+
+### Phase 2 - Presets
+
+`scripts/generate_dsh_preset.py` emits composition directories plus `preset.yml` display metadata.
+Start with `ai-toolkit-standard`; add `ai-toolkit-strict` only if the profile split earns it. Ids
+must satisfy `[a-z0-9][a-z0-9-]*`. Do not attempt to author presets by writing into a shipped
+preset directory. Upstream authoring is copy-only and `remove()` refuses shipped presets.
+
+### Phase 3 - Agents
+
+Blocked on Q1. Expected shape: one subagent declaration per `app/agents/*.md`, carrying
+`description`, tool allowances, and delegation targets, with the model left unset so host settings
+stay authoritative. The `model` alias problem is the same one documented for opencode in
+`kb/reference/opencode-compatibility.md`: the toolkit stores `opus`/`sonnet`/`haiku`, which cannot
+be mapped without assuming a provider.
+
+### Phase 4 - MCP and hooks
+
+`packages/mcp` for server config, `packages/hooks` for the bridge. If the hook bridge speaks the
+Claude Code hook wire protocol, `app/hooks/*.sh` may attach with a thin adapter rather than a
+rewrite. Preserve `exit 2` blocking semantics for `guard-destructive.sh`. This matters most under
+unattended delegation, where nobody is watching the permission prompt.
+
+### Phase 5 - Registry, docs, tests
+
+Follow the opencode precedent exactly:
+
+- `scripts/ecosystem_tools.json` entry with docs and release-notes URLs for drift detection.
+- `kb/reference/dsh-compatibility.md` mirroring the section layout of
+  `kb/reference/opencode-compatibility.md` (Summary, Local/Global Install Outputs, Editor Surface
+  Comparison, translation models, Behavioral Limits, Verification, CLI Commands).
+- Entry in `kb/reference/supported-tools-registry.md`.
+- The nine files mandated by `CLAUDE.md`: README.md, CLAUDE.md, ARCHITECTURE.md, package.json,
+  plugin.json, skills-catalog.md, architecture-overview.md, llms.txt, AGENTS.md.
+- bats generator contract tests, auto-detection tests, idempotency tests.
+- `python3 scripts/validate.py --strict`, `python3 scripts/audit_skills.py --ci`, and
+  `shellcheck --severity=warning app/hooks/*.sh` if any hook is touched.
+
+## 8. Original Success Criteria and Outcome
+
+| Criterion | Outcome |
+|---|---|
+| `ai-toolkit install --local --editors dsh` creates the workspace without manual editing | Not delivered; moved to the replacement plan |
+| One session runs Claude Max, ChatGPT-backed Codex, and Gemini without provider API keys | Delivered with Gemini hosted through GitHub Copilot rather than a Google login |
+| `validate.py --strict` and `audit_skills.py --ci` pass | Delivered for the standalone repositories; native target coverage remains in the replacement plan |
+| Uninstall preserves user-authored files | Not applicable until ai-toolkit owns DSH artifacts; moved to the replacement plan |
+| DSH remains opt-in | Delivered by separate packages and retained as a requirement of the replacement plan |
+
+## 9. Risks and Mitigation
+
+| Risk | Impact | Mitigation |
+|---|---|---|
+| Upstream breaking changes (declared developer preview) | Generators break for users mid-release | Keep dsh strictly opt-in; never in `--editors all` defaults until it leaves preview |
+| Anthropic changes its stance on spawned-CLI orchestration | Phase 0 premise invalidated | Fall back to ACP in JetBrains/Zed, where each agent owns its own auth by design |
+| Preset schema churn | Phase 2 rework | Emit the minimum viable composition; keep display metadata in `preset.yml` where the contract is narrow and stable |
+| Documentation drift across the nine mandated files | Broken user trust, per CLAUDE.md | Phase 5 is one atomic change with `validate.py --strict` as the gate |
+| Silent skill loss from fail-closed frontmatter | Skills vanish with only a warning | Phase 1 gates land before phase 2 |
+
+## 10. Pre-Mortem
+
+*It is six months out and this failed. What happened?*
+
+1. **We shipped dsh in the default editor set.** An upstream breaking change broke `install` for
+   every toolkit user, not just dsh users. Prevented by success criterion 5.
+2. **Phase 0 was skipped.** Phases 1-5 were built on the assumption that Max authenticates through
+   the spawned CLI, and it turned out to require an API key in practice. Prevented by making Q5 a
+   hard gate.
+3. **We mapped 44 agents onto 44 presets.** The preset surface is a session composition, not a
+   persona, so the emission produced 44 near-identical compositions nobody could maintain.
+   Prevented by section 3.2.
+4. **We became Cordis contributors.** Time went into upstream plugin work instead of the toolkit.
+   Prevented by treating dsh as an emission target with a fixed contract surface, never a fork.
+5. **A frontmatter regression silently dropped skills.** Nobody noticed because discovery only
+   warns. Prevented by phase 1.
+
+## 11. Archived Next Actions
+
+No work should continue from this archived document. The scoped native install target is complete in [`dsh-native-install-target-plan.md`](dsh-native-install-target-plan.md). Reopen this record only if evidence about the 2026-08-26 validation needs correction.
+
+## Sources
+
+- `deepseek-ai/deepseek-harness` @ `b150a55`, `0.1.1-rc.2`, MIT: `packages/skill/skill-filesystem`,
+  `packages/preset/agent-presets`, `packages/subagent/*`, `docs/`
+- https://github.com/deepseek-ai/deepseek-harness
+- https://deepseek.com/harness/en/
+- `kb/reference/opencode-compatibility.md`: precedent for the emission-target contract
+- `kb/reference/codex-cli-compatibility.md`: `.agents/skills` precedent
+- `kb/reference/supported-tools-registry.md`
+
+## Related
+
+- `kb/reference/opencode-compatibility.md`
+- `kb/reference/codex-cli-compatibility.md`
+- `kb/reference/architecture-overview.md`
+- `kb/reference/supported-tools-registry.md`

package/kb/history/completed/dsh-native-install-target-plan.md

@@ -0,0 +1,331 @@
+---
+title: "Plan: Native DSH Install Target"
+category: planning
+service: ai-toolkit
+tags:
+  - dsh
+  - deepseek-harness
+  - installer
+  - editor-target
+  - subscriptions
+  - lifecycle
+  - security
+doc_type: plan
+status: completed
+created: "2026-08-27"
+last_updated: "2026-09-01"
+approved: "2026-08-28"
+started: "2026-08-28"
+completion: "Phase 3 of 3 complete"
+completed: "2026-09-01"
+predecessor: "kb/history/completed/dsh-integration-plan-superseded.md"
+description: "Implementation plan for an explicit ai-toolkit DSH target that emits project skills and safely manages the published dsh-codex and dsh-orchestrator packages without handling vendor credentials."
+---
+
+# Plan: Native DSH Install Target
+
+## Status
+
+Approved on 2026-08-28 and completed on 2026-09-01.
+
+Estimated size: **L (3 to 5 days)**. The runtime integrations already exist. The remaining work is installer ownership, lifecycle safety, validation, tests, and documentation.
+
+Predecessor: [`dsh-integration-plan-superseded.md`](dsh-integration-plan-superseded.md).
+
+## Context
+
+The subscription-backed runtime is already delivered in two standalone Apache-2.0 packages:
+
+- `@softspark/dsh-codex@1.0.0` registers the DSH `codex` provider and delegates authentication, tools, thread state, and model execution to the locally installed Codex app server. See <https://github.com/softspark/dsh-codex>.
+- `@softspark/dsh-orchestrator@1.0.1` registers bounded Claude Code and GitHub Copilot Gemini delegation through native vendor logins. It accepts no provider API keys. See <https://github.com/softspark/dsh-orchestrator>.
+
+ai-toolkit does not expose `dsh` in its editor list, does not track DSH profile artifacts, and has no DSH-specific install, doctor, update, or uninstall contract. [PATH: bin/ai-toolkit.js:309]
+
+The published packages currently require two explicit operations: install exact plugins into a named DSH profile, then copy `softspark-orchestrator` from the installed package into `$DSH_HOME/.agent-presets`. See the orchestrator setup guide at <https://github.com/softspark/dsh-orchestrator>.
+
+## Decision
+
+The native target has two separate ownership surfaces:
+
+1. `ai-toolkit install --local --editors dsh` emits project-owned `.agents/skills` and validates DSH compatibility. It must not mutate `$DSH_HOME`, install npm packages, or inspect vendor credentials.
+2. `ai-toolkit dsh install --profile web` is the explicit profile mutation command. It installs exact reviewed package versions, copies the released preset, and records ownership in the existing ai-toolkit state model.
+
+This split preserves the meaning of `--local`. It also makes global DSH changes impossible without a command that names DSH and the target profile.
+
+`dsh` stays out of `--editors all`, auto-detection, default profiles, and global editor defaults while DSH remains a developer preview. Selecting `dsh` must be explicit.
+
+## Scope
+
+### Included
+
+- Explicit project target under `--editors dsh`.
+- Reuse of the existing `.agents/skills/<name>/SKILL.md` emission path.
+- DSH-specific validation for fail-closed skill metadata and one-level discovery depth.
+- Explicit `ai-toolkit dsh install`, `update`, `doctor`, and `uninstall` lifecycle commands.
+- Exact installation of `@softspark/dsh-codex@1.0.0` and `@softspark/dsh-orchestrator@1.0.1` into a named DSH profile.
+- Ownership-safe copy and update of `$DSH_HOME/.agent-presets/softspark-orchestrator`.
+- State tracking through `~/.softspark/ai-toolkit/state.json`.
+- Dry-run output, collision refusal, rollback, tests, registry metadata, and public documentation.
+
+### Excluded
+
+- Direct Google AI Pro/Ultra, Gemini CLI OAuth, Antigravity, or Gemini API integration.
+- Provider API keys, custom OAuth, token copying, credential-file reads, or login automation.
+- Mapping all 44 ai-toolkit agents into DSH subagents.
+- A new DSH skill generator. DSH already consumes `.agents/skills`.
+- Automatic DSH installation from `--editors all`, auto-detection, or default install profiles.
+- Rewriting the released dsh-codex or dsh-orchestrator packages inside ai-toolkit.
+- MCP and hook bridging in the first native-target release.
+- Support for arbitrary DSH prereleases or unpinned community package versions.
+
+## Global Success Criteria
+
+- [x] `ai-toolkit install --local --editors dsh` emits the complete managed skill catalog and makes no write under `$DSH_HOME`.
+- [x] `ai-toolkit dsh install --profile web` installs exact `@softspark/dsh-codex@1.0.0` and `@softspark/dsh-orchestrator@1.0.1` packages plus the released preset without manual file editing.
+- [x] Install, update, doctor, and uninstall preserve user-authored presets and unrelated DSH plugins.
+- [x] No command accepts, reads, copies, logs, or forwards provider credentials.
+- [x] `dsh` remains excluded from `--editors all`, auto-detection, default profiles, and default global editors.
+- [x] Offline, missing-runtime, collision, partial-install, and interrupted-update paths fail without leaving untracked artifacts.
+- [x] The full repository test, validation, skill-audit, and documentation gates pass.
+
+## Phase 1: Project Target and Fail-Closed Gates
+
+Dependency: none.
+
+Size: **M (1 to 2 days)**.
+
+### Phase 1 Success Criteria
+
+- [x] CLI help and validation accept `dsh` only when named explicitly.
+- [x] `--editors all` resolves to the existing stable editor set and excludes `dsh`.
+- [x] Dry-run lists `.agents/skills` changes but writes nothing.
+- [x] Project installation emits every managed skill at one discovery level.
+- [x] Validation rejects camel-case invocation fields, non-boolean invocation values, invalid skill directory names, and nested `SKILL.md` locations.
+- [x] A read-only doctor check reports DSH, Codex, Claude Code, and Copilot executable availability without opening credential stores.
+
+### Phase 1 Completion Evidence
+
+Completed on 2026-08-28 after sequential TDD, three spec review passes, and four quality-review repair cycles.
+
+- Full repository suite: 1726/1726 tests.
+- Final spec review: 10/10 requirements approved.
+- Final quality review: 0 Critical, 0 Important.
+- Strict validator: 0 errors, 0 warnings.
+- Skill audit: 0 HIGH, 0 WARN.
+- DSH remains explicit-only, project-local, credential-blind, transactionally owned, and outside Phase 2 profile lifecycle behavior.
+
+### Phase 1 Tasks
+
+| ID | Outcome | Affected files | Owner | Depends on |
+|---|---|---|---|---|
+| P1.1 | Add an explicit-only DSH editor capability separate from the stable `ALL_EDITORS` expansion | `bin/ai-toolkit.js`, `scripts/install.py`, `scripts/install_steps/ai_tools.py` | `backend-specialist` | none |
+| P1.2 | Reuse the managed Codex skill emitter for the DSH project surface without emitting unrelated Codex configuration | `scripts/generate_codex_skills.py`, `scripts/install_steps/ai_tools.py` | `backend-specialist` | P1.1 |
+| P1.3 | Enforce the DSH fail-closed metadata, name, and depth contract | `scripts/validate.py`, `tests/test_metadata_contracts.bats`, `tests/test_skills_native.bats` | `backend-specialist` | none |
+| P1.4 | Add read-only runtime and version diagnostics with no login automation | `scripts/doctor.py`, `tests/test_doctor_fix.bats`, `tests/test_dsh.bats` | `infrastructure-validator` | P1.1 |
+| P1.5 | Cover explicit selection, `all` exclusion, dry-run, idempotency, and project-only writes | `tests/test_dsh.bats`, `tests/test_install.bats`, `tests/test_install_profiles.bats` | `test-engineer` | P1.1, P1.2, P1.3, P1.4 |
+
+### Phase 1 Rollback and Scope Cut
+
+Remove the explicit `dsh` selector and its focused tests. Existing Codex skill emission and both standalone DSH packages remain unchanged. If the fail-closed metadata gates reveal unrelated invalid skills, fix those skills before shipping rather than weakening the gate.
+
+## Phase 2: Explicit DSH Profile Lifecycle
+
+Dependency: Phase 1 → Phase 2.
+
+Size: **M (1 to 2 days)**.
+
+### Phase 2 Success Criteria
+
+- [x] `ai-toolkit dsh install --profile web` performs preflight before the first mutation.
+- [x] The command installs exact reviewed package versions through the DSH plugin manager.
+- [x] The preset is copied from the installed orchestrator package, not reconstructed by ai-toolkit.
+- [x] Existing user-owned preset or plugin collisions stop the command with an actionable error.
+- [x] State records the DSH home, profile, package versions, preset path, and managed content hash without recording credentials.
+- [x] Update replaces only artifacts whose ownership and previous hash match state.
+- [x] Uninstall removes only ai-toolkit-managed DSH artifacts and leaves unrelated profile content unchanged.
+- [x] Interrupted or failed installation restores the pre-operation state or reports a deterministic recovery command.
+
+### Phase 2 Completion Evidence
+
+Completed on 2026-08-31 after adversarial transaction, concurrency, rollback, path-swap, state-CAS, and credential-boundary testing.
+
+- Full repository suite on the final isolated DSH scope: 1846/1846 tests.
+- Phase 2 spec review: approved with zero must-fix gaps.
+- Defensive security review: approved with zero findings.
+- Code quality review: 0 Critical, 0 Important, 0 Suggestions.
+- Strict validator: 0 errors, 0 warnings on the verified DSH tree.
+- Skill audit: 0 HIGH, 0 WARN.
+- Exact reviewed pins are DSH `0.1.1-rc.2`, dsh-codex `1.0.0`, and dsh-orchestrator `1.0.1`.
+- Lifecycle state stores canonical package and preset ownership metadata without credentials or package contents.
+
+### Phase 2 Tasks
+
+| ID | Outcome | Affected files | Owner | Depends on |
+|---|---|---|---|---|
+| P2.1 | Freeze the pinned DSH plugin add, update, and removal contract against DSH `0.1.1-rc.2` in bounded fixtures | `scripts/install_steps/dsh.py`, `tests/fixtures/dsh/`, `tests/test_dsh.bats` | `backend-specialist` | Phase 1 |
+| P2.2 | Implement explicit profile install, update, doctor, and uninstall dispatch with `web` as the documented default profile | `bin/ai-toolkit.js`, `scripts/install.py`, `scripts/install_steps/dsh.py`, `scripts/uninstall.py` | `command-expert` | P2.1 |
+| P2.3 | Extend state tracking with DSH profile and managed-preset ownership | `scripts/install_steps/install_state.py`, `kb/reference/manifest-install.md`, `tests/test_install_state.bats` | `backend-specialist` | P2.1 |
+| P2.4 | Add atomic preset copy, collision refusal, hash verification, and recovery behavior | `scripts/install_steps/dsh.py`, `tests/test_dsh.bats`, `tests/test_uninstall_recovery.bats` | `backend-specialist` | P2.2, P2.3 |
+| P2.5 | Audit command construction, environment filtering, logs, and state for credential exposure | `scripts/install_steps/dsh.py`, `scripts/uninstall.py`, `tests/test_dsh.bats` | `security-auditor` | P2.2, P2.4 |
+| P2.6 | Exercise clean install, repeat install, update, collision, offline, interruption, and uninstall with fake DSH binaries and isolated roots | `tests/test_dsh.bats`, `tests/test_uninstall_ai_tools.bats`, `tests/fixtures/dsh/` | `test-engineer` | P2.2, P2.3, P2.4, P2.5 |
+
+### Phase 2 Rollback and Scope Cut
+
+Disable the lifecycle subcommand while retaining the Phase 1 project target and read-only doctor output. Users can continue following the standalone package installation guides. Never recover from a lifecycle bug by deleting an unowned preset or profile.
+
+## Phase 3: Registry, Documentation, and Release Qualification
+
+Dependency: Phase 2 → Phase 3.
+
+Size: **S to M (1 day)**.
+
+### Phase 3 Success Criteria
+
+- [x] DSH has one opt-in registry entry with pinned docs and release-note sources.
+- [x] Compatibility documentation distinguishes project emission, explicit profile mutation, vendor authentication, and unsupported Google routes.
+- [x] README, CLI help, architecture, supported-tools registry, manifest install reference, and `llms.txt` describe the same commands and boundaries.
+- [x] An isolated real-profile qualification installs the two published packages, selects the released preset, and completes Codex-to-Claude plus Codex-to-Copilot-Gemini delegation.
+- [x] No release is tagged while focused tests, full tests, validation, skill audit, ShellCheck, or generated-document checks are red.
+
+### Phase 3 Completion Evidence
+
+Completed on 2026-09-01 after exact-package pre-tag and post-release qualification.
+
+- Full repository suite: 1920/1920 tests.
+- Strict validator: 0 errors and 0 warnings; skill audit: 0 HIGH and 0 WARN.
+- ShellCheck, Apache-2.0 licensing, SARIF, public-surface, ecosystem, npm audit, and package dry-run gates passed.
+- `@softspark/dsh-orchestrator@1.0.1` published with SLSA provenance after both native-login marker tools completed through a Codex parent.
+- The exact npm registry package repeated both Claude Code and Copilot Gemini child/parent marker roundtrips, with no provider API key handling.
+- The isolated DSH process stopped cleanly and the unrelated profile fixture remained intact.
+
+### Phase 3 Tasks
+
+| ID | Outcome | Affected files | Owner | Depends on |
+|---|---|---|---|---|
+| P3.1 | Add the opt-in DSH registry and drift-monitoring contract | `scripts/ecosystem_tools.json`, `tests/test_ecosystem_doctor.bats` | `technical-researcher` | Phase 2 |
+| P3.2 | Publish one compatibility contract and synchronize all user-facing command surfaces | `kb/reference/dsh-compatibility.md`, `kb/reference/supported-tools-registry.md`, `kb/reference/architecture-overview.md`, `kb/reference/manifest-install.md`, `README.md`, `CLAUDE.md`, `llms.txt`, `bin/ai-toolkit.js` | `documenter` | P3.1 |
+| P3.3 | Run isolated end-to-end qualification with real DSH and published packages, then record evidence | `kb/reference/dsh-compatibility.md`, `kb/procedures/release-verification-sop.md` | `infrastructure-validator` | P3.2 |
+| P3.4 | Run focused and full repository gates and assess regression blast radius | `tests/test_dsh.bats`, `tests/test_cli.bats`, `tests/test_install.bats`, `tests/test_uninstall_ai_tools.bats`, `scripts/validate.py`, `scripts/audit_skills.py` | `qa-automation-engineer` | P3.2, P3.3 |
+| P3.5 | Review final security boundaries and veto release on credential or ownership regressions | `scripts/install_steps/dsh.py`, `scripts/install_steps/install_state.py`, `scripts/uninstall.py`, `kb/reference/dsh-compatibility.md`, `tests/test_dsh.bats` | `security-architect` | P3.3, P3.4 |
+
+### Phase 3 Rollback and Scope Cut
+
+Do not tag or publish the ai-toolkit release. Keep the published standalone `@softspark/dsh-codex@1.0.0` and `@softspark/dsh-orchestrator@1.0.1` packages as the supported installation route. If upstream DSH drifts during qualification, retain the registry entry as unsupported-preview metadata and remove the user-facing install command until compatibility is restored.
+
+## Dependencies
+
+```text
+Phase 1 → Phase 2 → Phase 3
+```
+
+Within phases:
+
+```text
+P1.1 → P1.2 → P1.5
+P1.3 ─────────→ P1.5
+P1.4 ─────────→ P1.5
+
+P2.1 → P2.2 → P2.4 → P2.5 → P2.6
+             ↘ P2.3 ↗
+
+P3.1 → P3.2 → P3.3 → P3.4 → P3.5
+```
+
+No phase begins until the previous phase meets its success criteria. Phase 1 can ship as project-only compatibility without Phase 2. Phase 2 can remain unreleased if real-profile qualification fails.
+
+## Requirement Traceability
+
+| Requirement | Tasks |
+|---|---|
+| Explicit DSH project target | P1.1, P1.2, P1.5 |
+| DSH excluded from defaults and `all` | P1.1, P1.5 |
+| Fail-closed skill discovery | P1.3, P1.5 |
+| No credential handling | P1.4, P2.5, P3.5 |
+| Exact package installation | P2.1, P2.2, P2.6 |
+| Managed preset lifecycle | P2.3, P2.4, P2.6 |
+| Ownership-safe uninstall | P2.3, P2.4, P2.6 |
+| Registry and documentation parity | P3.1, P3.2 |
+| Real subscription-backed smoke test | P3.3, P3.4 |
+| Release blocked on red gates | P3.4, P3.5 |
+
+## Verification
+
+### Focused gates
+
+```bash
+bats tests/test_dsh.bats
+bats tests/test_install.bats
+bats tests/test_install_profiles.bats
+bats tests/test_install_state.bats
+bats tests/test_uninstall_ai_tools.bats
+bats tests/test_uninstall_recovery.bats
+```
+
+### Repository gates
+
+```bash
+python3 scripts/validate.py --strict
+python3 scripts/audit_skills.py --ci
+python3 scripts/ecosystem_doctor.py
+npm test
+```
+
+Run ShellCheck when a shell fixture, hook, or command wrapper changes. Run the existing generated-document drift checks before commit.
+
+### Isolated runtime qualification
+
+Use a new task-specific `DSH_HOME` and DSH profile. Do not replace `HOME` and do not reuse the maintainer's regular DSH profile.
+
+Verify these observations:
+
+1. Project installation emits the full managed skill catalog and no nested skill entry.
+2. Profile installation records exact package versions and one managed preset.
+3. Codex reports ChatGPT-owned authentication through its own status command.
+4. Claude Code and Copilot own their login state; ai-toolkit state and logs contain no credential values.
+5. A Codex parent delegates one bounded marker task to Claude Code and one to Copilot Gemini.
+6. Uninstall returns the isolated profile to its pre-install inventory while preserving an injected user-owned preset fixture.
+
+## Pre-Mortem
+
+| Failure mode | Probability | Impact | Mitigation |
+|---|---|---|---|
+| Generic `install --local` mutates a global DSH profile | Medium | High | Separate project emission from the explicit `ai-toolkit dsh install` command and test zero `$DSH_HOME` writes in Phase 1 |
+| `--editors all` silently gains a developer-preview runtime | Medium | High | Keep explicit-only editors in a separate registry and assert expansion output in tests |
+| Preset update overwrites user edits or a same-name user preset | Medium | High | Require ownership state plus matching previous hash; refuse every ambiguous collision |
+| Partial DSH plugin installation leaves one provider without the matching preset | Medium | High | Preflight all inputs, snapshot managed state, order mutations, and implement deterministic recovery |
+| Installer logs or state capture vendor credentials | Low | Critical | Never invoke login flows, never read credential files, redact command output, and audit fixtures for secret-shaped data |
+| DSH prerelease changes plugin or preset discovery semantics | High | High | Pin the reviewed DSH version, run ecosystem drift checks, and block release on real-profile qualification failure |
+| Reusing Codex-adapted skills produces incorrect DSH delegation instructions | Medium | Medium | Validate representative delegation-heavy skills in the Codex parent and add a DSH-specific adapter only if evidence requires it |
+| Copilot changes Gemini model availability or credit policy | Medium | Medium | Treat model and credit policy as doctor-visible compatibility data, not a promise hardcoded into ai-toolkit behavior |
+
+## Agent Assignments
+
+| Workstream | Primary agent | Review agent | Reason |
+|---|---|---|---|
+| CLI and installer plumbing | `backend-specialist` | `tech-lead` | Python and Node entry-point integration with existing installer layers |
+| Command UX | `command-expert` | `product-manager` | Explicit mutation semantics, dry-run output, and actionable errors |
+| Runtime preflight and qualification | `infrastructure-validator` | `technical-researcher` | DSH profile behavior, pinned compatibility, and observable smoke evidence |
+| Security and ownership | `security-auditor` | `security-architect` | Credential boundary, collision refusal, state minimization, and release veto |
+| Test automation | `test-engineer` | `qa-automation-engineer` | Fake-runtime fixtures, lifecycle integration tests, and full regression gates |
+| Documentation | `documenter` | `fact-checker` | Cross-file parity and evidence-backed compatibility claims |
+
+## Approval Checkpoint
+
+Implementation starts only after the user approves:
+
+1. The two-command split between project emission and explicit DSH profile mutation.
+2. Excluding DSH from `--editors all` and auto-detection while upstream remains a developer preview.
+3. Pinning the native target to DSH `0.1.1-rc.2`, dsh-codex `1.0.0`, and dsh-orchestrator `1.0.1`.
+4. Deferring 44-agent mapping, MCP bridging, and hook bridging outside this plan.
+
+## Sources
+
+- `kb/history/completed/dsh-integration-plan-superseded.md`
+- `bin/ai-toolkit.js`
+- `scripts/install.py`
+- `scripts/install_steps/ai_tools.py`
+- `scripts/install_steps/install_state.py`
+- `scripts/ecosystem_tools.json`
+- <https://github.com/softspark/dsh-codex>
+- <https://github.com/softspark/dsh-orchestrator>
+- <https://github.com/deepseek-ai/deepseek-harness>