ultra-builder-pro-cli 0.25.1 → 0.26.1

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -1,158 +1,143 @@
 # Runtime compatibility matrix
 
-Claude Code, OpenCode, Codex, Kimi Code, and Grok Build are supported plugin
-hosts. The canonical asset boundary lives in
-`adapters/_shared/runtime-assets.cjs`.
-
-Legend: **FULL** means a native equivalent exists; **FUNCTIONAL** means the same
-outcome uses a different native primitive; **DEGRADED** means the missing host
-surface is stated and the Skill-entry Context read remains authoritative; **N/A**
-means intentionally absent.
-
-## Plugin and workflow surface
-
-| Capability | Claude Code | OpenCode | Codex | Kimi Code | Grok Build |
-|---|---|---|---|---|---|
-| Package form | `.claude-plugin` | config bundle + JS plugin | personal `.codex-plugin` | managed `kimi.plugin.json` | native Grok plugin |
-| Public entry | `/ultra-builder-pro:ultra-*` | `/ultra-*` | `$ultra-builder-pro:ultra-*` | `/ultra-builder-pro:ultra-*` | native Ultra commands/Skills |
-| Public workflow Skills | 11 explicit-only | 11 command-backed private assets | 11 implicit-disabled | 11 model-disabled | 11 explicit-only |
-| Internal rule Skills | 4 worker-only | 4 worker-only | 4 implicit-disabled | 4 worker templates | 4 worker templates |
-| MCP tools | exactly 7 | exactly 7 | exactly 7 | exactly 7 | exactly 7 |
-| Automatic semantic chaining | N/A | N/A | N/A | N/A | N/A |
-
-Commands are thin launchers. The Skill contains adaptable semantic workflow prose;
-the adapter contains only host metadata, translation, and wiring.
-
-## Agents and collaboration
-
-| Capability | Claude Code | OpenCode | Codex | Kimi Code | Grok Build |
-|---|---|---|---|---|---|
-| Bundled review/debug workers | FULL, 10 native Markdown agents | FULL, 10 native agents | FULL, 10 managed TOML agents | FUNCTIONAL, 10 prompt templates | FUNCTIONAL, 10 prompt templates |
-| Immutable Worker Packet | FULL | FULL | FULL | FULL | FULL |
-| Native bounded delegation | native agent surface | native agent surface | native subagents | Agent/AgentSwarm | plugin agent surface |
-| Cross-host advisor | explicit read-only | explicit read-only | explicit read-only | explicit read-only | explicit read-only |
-| Final acceptance owner | primary host | primary host | primary host | primary host | primary host |
-
-Every Worker Packet binds Context, decisions, Git, Task, acceptance, evidence,
-output schema, and digest. A worker cannot write SQLite or accept its own result.
-
-## Hooks and Context
-
-| Lifecycle | Claude Code | OpenCode | Codex | Kimi Code | Grok Build |
-|---|---|---|---|---|---|
-| Session Context | FULL, SessionStart compact | FULL, system transform | FULL, session/prompt compact | FULL where native event consumes output | DEGRADED, ignored stdout is not claimed as injection |
-| Skill-entry Context | FULL | FULL | FULL | FULL | FULL and authoritative |
-| Managed-file protection | PreToolUse | tool.before | PreToolUse | PreToolUse | camelCase PreToolUse |
-| Compact recovery | PreCompact + SessionStart | compacting transform | pre/post compact | native pre/post where available | records lifecycle; Skill rereads Context |
-| Stop | non-blocking advisory | session.idle annotation | non-blocking advisory | non-blocking advisory | advisory only for `reason=end_turn` |
-| Subagent event | minimal ids | DEGRADED when host lacks event | minimal ids | native start/stop | minimal ids where exposed |
-
-All Hook context comes from the canonical Context Envelope generator. Hooks never
-capture prompts, transcripts, general memory, observations, or code-graph payloads.
-They do not create semantic records or block ordinary work for incomplete evidence.
-
-## MCP and native runtime
-
-| Capability | Claude Code | OpenCode | Codex | Kimi Code | Grok Build |
-|---|---|---|---|---|---|
-| stdio registration | `.mcp.json` | local MCP entry | `.mcp.json` | `mcpServers` | native plugin MCP entry |
-| Public discovered tools | 7 | 7 | 7 | 7 | 7 |
-| Public write/read smoke | FULL | FULL | FULL | FULL | FULL |
-| Doctor backup/reopen | FULL | FULL | FULL | FULL | FULL |
-| Bundled `better-sqlite3` native | FULL | FULL | FULL | FULL | FULL |
-| ABI/provenance validation | FULL | FULL | FULL | FULL | FULL |
-| Git team checkpoint | `.ultra/tasks/tasks.json` | same | same | same | same |
-| Local authority | `.ultra/.runtime/state.db` | same | same | same | same |
-
-The installed runtime includes the externalized `better-sqlite3` package and its
-native `.node`. Provenance records native digest, platform, architecture, Node ABI,
-and runtime command. A mismatched ABI fails before authority is opened; Doctor
-repairs through staging and atomic swap.
-
-Archive finalization uses a packaged Python 3 worker with identity-checked
-descriptor-relative filesystem operations on POSIX. If this prerequisite is absent,
-archive fails closed with `ARCHIVE_RUNTIME_UNAVAILABLE`; other MCP tools remain usable.
-
-## Structured user interaction
-
-| Host | Native question surface | Fallback |
+Ultra Builder Pro adapts one fourteen-Skill, five-hook contract to five native hosts.
+This document records the differences that belong in adapters rather than shared
+Skills.
+
+## Installed surface
+
+| Host | Managed plugin or bundle | Skills | Hook bridge |
+|---|---|---:|---|
+| Claude Code | `<config>/skills/ultra-builder-pro` | nested `skills/<name>` | direct Python commands in `hooks/hooks.json` |
+| Codex | `<home>/plugins/ultra-builder-pro` plus personal marketplace entry | nested `skills/<name>` with `agents/openai.yaml` | `hooks/adapters/codex.py` |
+| OpenCode | `<config>/.ultra-builder-pro` plus `<config>/plugins/ultra-builder-pro.js` | managed `<config>/skills/<name>` | native JS events call shared Python scripts |
+| Kimi Code | `<config>/plugins/managed/ultra-builder-pro` plus `installed.json` | nested `skills/<name>` | `hooks/adapters/kimi.py` |
+| Grok Build | `<GROK_HOME>/.ubp/plugin-sources/ultra-builder-pro` | nested `skills/<name>` | `hooks/adapters/grok.py` |
+
+Every host receives the same eight owner workflows, five model disciplines, and one
+router. Codex alone needs generated `agents/openai.yaml` files to express display data
+and implicit-invocation policy; those are host metadata, not custom agents.
+
+## Scope resolution
+
+| Host | Global default | Local default | Environment override |
+|---|---|---|---|
+| Claude Code | `~/.claude` | `<cwd>/.claude` | `CLAUDE_CONFIG_DIR` |
+| Codex | `~/.codex` for config; `~/plugins` and `~/.agents` for sidecars | `<cwd>/.codex` plus home-scoped plugin surface | `CODEX_HOME` |
+| OpenCode | `${XDG_CONFIG_HOME:-~/.config}/opencode` | `<cwd>/.opencode` | `OPENCODE_CONFIG_DIR` or `OPENCODE_CONFIG` |
+| Kimi Code | `~/.kimi-code` | no project plugin scope | `KIMI_CODE_HOME` |
+| Grok Build | `~/.grok` | no project plugin scope | `GROK_HOME` |
+
+An explicit `--config-dir` wins over all defaults and becomes the home for any
+host-owned sidecar as well. This rule makes isolated installation tests trustworthy.
+With multiple selected runtimes, the CLI passes `<config-dir>/<runtime>` to each adapter
+instead of merging incompatible host layouts.
+Kimi and Grok currently expose user-scoped plugin installation only. `--local` rejects
+them before mutating another host; an explicit `--config-dir` remains available for an
+isolated user-scope installation test.
+
+## Invocation policy
+
+| Role | Owner can route directly | Model can select implicitly |
+|---|---:|---:|
+| eight user-invoked Skills | yes | no |
+| five model-invoked Skills | no | yes |
+| `ultra-status` router | yes | no |
+
+Claude and Grok receive `user-invocable` / `disable-model-invocation` frontmatter.
+Kimi receives its native equivalent. Codex receives
+`policy.allow_implicit_invocation` in `agents/openai.yaml`. OpenCode uses portable
+source frontmatter and native discovery, but its current Skill schema has no equivalent
+owner/model routing bit: all fourteen Skills remain discoverable and their descriptions
+guide model selection. Ultra does not add a semantic interception hook to imitate a
+host feature OpenCode does not expose.
+
+## Hook compatibility
+
+| Hook | Claude | Codex | OpenCode | Kimi | Grok |
+|---|---:|---:|---:|---:|---:|
+| session context | yes | normalized | native bridge | normalized to message | executed; host stdout limits apply |
+| mid-workflow recall | yes | handles `apply_patch` | native bridge | normalized | executed |
+| compact context | pre/start | pre/post | native compact event | pre/post | pre-compact |
+| post-edit observation | Write/Edit | Write/Edit/`apply_patch` | write/edit/patch | Write/Edit | Write/Edit/patch |
+| dangerous command guard | Bash advisory/deny | Bash advisory/deny | bash advisory/deny | Bash advisory/deny | Bash allow/deny mapping |
+
+All hooks share the same `.ultra/` idle guard. Wire adapters normalize payload and
+output fields only; they do not change semantic policy. Codex installation health and
+hook activation are distinct: Codex skips newly installed non-managed plugin hooks
+until the user reviews and trusts the current definition, so Doctor reports
+`hook_activation: user_review_required` without pretending the hook already ran.
+
+## Delegation argv
+
+`adapters/_shared/host-profile.cjs` records current non-interactive invocation for:
+
+- Claude print mode with structured output and an explicit file-tool allowlist; read-only
+  uses `plan`, while bounded write uses `acceptEdits` without Bash or web tools;
+- Codex ephemeral `exec` with user config ignored, project rules preserved, native
+  `read-only` or `workspace-write`, network disabled, and an output schema;
+- OpenCode `run --auto` only after an inline config explicitly denies Bash, web,
+  subagents, external directories, Skills and undeclared edit roots;
+- Kimi prompt mode with a launch-only read or write agent profile that exposes only
+  file tools and no Bash, web, MCP, Skills or subagents;
+- Grok single-turn mode with `read-only` or `workspace` OS sandbox, structured output,
+  no memory, web search or subagents.
+
+The launcher accepts no external-effect authority. It binds instruction, permission and
+output-schema digests, a clean Git worktree, allowed write roots, actual changed paths,
+strict result schema, timeout and cancellation. Empty roots select read-only mode. The
+model returns structured output and never authors the receipt. Host-native permissions
+are the execution boundary; the primary host still inspects and integrates the isolated
+diff.
+
+## Lifecycle verification
+
+Each adapter must pass isolated install, doctor, reinstall, and uninstall tests. Real
+global doctor additionally asks the native host where supported, but never repairs or
+installs. Codex still performs native registration under `--config-dir`; its host process
+inherits the same isolated `HOME` and `CODEX_HOME`. Grok native registration is skipped
+only in explicit isolated test mode. Lifecycle tests also require the isolated config
+and fake HOME to contain zero children after uninstall, while separate ownership tests
+prove that pre-existing empty Codex and Kimi registries survive.
+
+## Authenticated cross-host continuation evidence
+
+On 2026-08-03, one deliberately narrow task was run in an isolated Git repository to
+test the product's central recovery claim with real authenticated models. This was a
+continuation drill, not a full project workflow or a delegation receipt test.
+
+Both hosts used globally installed artifacts from the same clean source candidate:
+
+- source commit: `c473a248bde2afce77591f2ba382246d420b5c72`;
+- worktree digest: `e83bdcbe2905cf02cb06cb0219127f6ce0400484331a6e9fc95622bbe24b44bd`;
+- Doctor: Claude healthy with 83 assets and zero issues; Codex healthy with 99 assets
+  and zero issues, with optional hooks still `user_review_required`.
+
+The seed repository had one passing smoke test, one pending task, one mapped Change
+acceptance ID, and seed HEAD `cf27d62aeeae353e0650413de6d9a118b89a0406`.
+
+| Phase | Execution boundary | Observed result |
 |---|---|---|
-| Claude Code | `AskUserQuestion` | one concise direct question |
-| OpenCode | `question` | one concise direct question |
-| Codex | `request_user_input` when exposed by current mode | one concise direct question |
-| Kimi Code | `AskUserQuestion` outside auto mode | one concise direct question |
-| Grok Build | native structured question when exposed | one concise direct question |
-
-An interaction-disabled mode leaves the choice unresolved. The adapter never infers
-consent or stores an interaction receipt.
-
-## User instruction isolation
-
-| Host | Durable user instruction | Installer writes it? |
-|---|---|---|
-| Claude Code | `~/.claude/CLAUDE.md` | no |
-| OpenCode | `~/.config/opencode/AGENTS.md` | no |
-| Codex | `~/.codex/AGENTS.md` | no |
-| Kimi Code | `~/.kimi-code/AGENTS.md` | no |
-| Grok Build | host-owned instruction file | no |
-
-Install, update, Doctor, and uninstall preserve user instructions, repository
-instructions, project `.ultra`, unrelated plugins, and unrelated host configuration.
-
-## Install lifecycle
-
-| Capability | Claude Code | OpenCode | Codex | Kimi Code | Grok Build |
-|---|---|---|---|---|---|
-| Global flag | `--claude` | `--opencode` | `--codex` | `--kimi` | `--grok` |
-| Staging + atomic swap | FULL | FULL | FULL | FULL | FULL |
-| Exact-host preflight | FULL | FULL | FULL | FULL | FULL |
-| Native registration truth | host manifest | host config | plugin manifest/cache | installed registry | `grok plugin list/details` |
-| Active MCP truth | host MCP config | host MCP config | plugin cache | managed plugin config | `grok inspect` + `grok mcp doctor` |
-| Managed uninstall guard | FULL | FULL | FULL | FULL | FULL |
-| Preserve unrelated config | FULL | FULL | FULL | FULL | FULL |
-| Read-only Doctor | FULL | FULL | FULL | FULL | FULL |
-
-Preflight uses the final manifest command and verifies initialize, `tools/list == 7`,
-public write/read, Doctor backup, close/reopen consistency, native provenance, and
-lazy project initialization.
-
-The Grok adapter probes the installed CLI's command and flag capabilities rather
-than branching on a Grok version number. Global installation uses Grok's native
-plugin registry, keeps a durable managed local source for native refresh, and
-resolves the MCP launcher through `${GROK_PLUGIN_ROOT}` after Grok copies the plugin
-under its dynamic `installed-plugins/<repo-key>` path. An older raw
-`$GROK_HOME/plugins/ultra-builder-pro` installation is backed up and migrated; a
-failed native install restores the prior source and registration.
-
-`grok mcp list` is not the plugin-MCP inventory surface in current Grok releases;
-it reports explicit user/project MCP configuration. Ultra therefore does not add a
-second `[mcp_servers]` entry merely to make that command display the plugin. The
-authoritative plugin consumer checks are the native plugin registry, merged
-`grok inspect` MCP source, and the live `grok mcp doctor` handshake.
-
-## Durable compatibility
-
-| Capability | Contract |
-|---|---|
-| Current authority schema | `22.0` |
-| Runtime values | `claude`, `opencode`, `codex`, `kimi`, `grok` |
-| Legacy inputs | v4.4/v4.5 task projections, the legacy root-level state database, Task Contexts, v0.22/v0.23 DB and team ledger |
-| Preservation | exact-byte backup, row/ID/event/migration-history preservation, verified semantic promotion |
-| Failure | transactional rollback; no partial DB, ledger, native runtime, or host installation |
-
-Old workflow/dialogue rows are retained as non-authoritative history. Current
-Decisions, Stage Checkpoints, Context Envelopes, Worker Packets, and team checkpoint
-are reconstructed only from verified authority.
-
-## Verification sources
-
-- `adapters/tests/*.test.cjs` validates every native builder and manifest.
-- `tests/conformance/<runtime>/*.test.cjs` validates all five hosts.
-- `adapters/_shared/tests/runtime-assets.test.cjs` keeps docs and asset allowlists
-  synchronized.
-- `tests/install.test.cjs` verifies atomic install, rollback, Doctor, and instruction
-  preservation.
-- `tests/package-smoke.test.cjs` installs the npm tarball and performs five real
-  launcher write/read/backup/reopen round trips.
-- Grok acceptance runs capability probing, native install/list/details/enable,
-  merged inspect, MCP Doctor, migration rollback, and camelCase Hook fixtures.
+| Claude | One print-mode call, `acceptEdits`, no persistent session, empty MCP config, explicit file and local-test tools, USD 1.00 cap | Exit 0 at USD 0.741367 with zero web requests. It changed only the task ledger/context, added `test/slug.test.cjs`, and allowed the hook to write disposable progress. `src/slug.cjs` and completion evidence remained untouched. The task test exited 1 with actual `hello,-world!` versus expected `hello-world`; both task surfaces read `in_progress`, and the Resume Note named the exact next action. |
+| Codex | One ephemeral `workspace-write` call with sandbox network disabled and no conversation from Claude | Exit 0. It found and read the installed `ultra-dev` Skill, recovered the single task from Git and `.ultra/`, reproduced the same red, changed only the intended implementation, then passed the task test 1/1 and `npm test` 2/2. It wrote the three-command canonical evidence record and logs, completed both task status surfaces, and filled Completion and the final Resume Note. |
+| Independent check | Local commands after both model calls | `node --test test/slug.test.cjs` passed 1/1, `npm test` passed 2/2, `git diff --check` passed, and a structural check confirmed one completed task, six evidence dimensions, three existing command-log references, and matching ledger/context state. |
+
+The Codex process emitted non-blocking diagnostics for an older local model-cache
+schema and an unauthenticated user-config MCP startup. No MCP result was consumed and
+no external effect occurred; all task actions used local file and shell tools. This
+means the drill proves file-backed Claude-to-Codex continuation even while Codex hooks
+remain untrusted, but it does not claim that arbitrary user configuration starts
+without unrelated host diagnostics.
+
+The result establishes one real end-to-end example of cross-host resume without a
+shared conversation, database, MCP authority, daemon, or generated prompt projection.
+It does not establish output quality for every model, host, repository, or task shape.
+Task-level `ultra-review` and commits were intentionally excluded from the drill so the
+two host calls tested only the handoff boundary.
+
+Two older `.ultra` evidence snapshots originally named the completed WIP by its former
+path. The current-path artifact contract requires every reference to resolve in the
+checkout, so those two references now point here while their 2026-08-01 status and
+limitations remain explicitly historical. The original WIP is still recoverable from
+their pinned source commit `3f99189bc68697262cd90444685ac2d4857139c4` with
+`git show`; the live `docs/wip/` directory contains no unfinished document.

package/docs/SKILL-AUTHORING.md

@@ -1,75 +1,96 @@
 # Skill authoring contract
 
-Ultra Builder Pro keeps one portable source workflow and adapts only runtime metadata
-or host invocation details. This contract follows OpenAI Skills guidance and the Agent
-Skills progressive-disclosure format:
-
-- <https://learn.chatgpt.com/docs/build-skills>
-- <https://learn.chatgpt.com/docs/customization/overview>
-- <https://agentskills.io/specification>
-- <https://agentskills.io/skill-creation/best-practices>
-
-## Surface ownership
-
-| Content | Owner |
-|---|---|
-| Repeatable task procedure and conditional references | `skills/<name>/SKILL.md` |
-| Codex display, invocation policy, and dependencies | `skills/<name>/agents/openai.yaml` after adaptation |
-| Host launcher | `commands/<name>.md` |
-| Durable repository or user engineering policy | `AGENTS.md` or the host equivalent |
-| Deterministic lifecycle enforcement | one hook implementation |
-| Live external data or actions | MCP server or connector |
-| Bounded delegated role | `agents/<name>.md` |
-
-Do not duplicate a rule across these surfaces.
-
-## Portable `SKILL.md`
-
-Source frontmatter contains only `name` and `description`. The description says what
-the Skill does and when it should activate. The body uses imperative, outcome-oriented
-steps and includes only information an agent cannot reliably infer from the task,
-repository, or host policy.
-
-Keep the main file compact. Move conditional domain detail to `references/`, reusable
-deterministic work to `scripts/`, and output material to `assets/`. Reference a file
-only from the main workflow or one directly relevant reference.
-
-## Language
-
-The standards do not prohibit Chinese. Ultra source prompts use English as a project
-policy because one source is transformed for Claude Code, Codex, OpenCode, Kimi Code,
-and Grok Build. The host or user instruction controls the response language; a workflow must not
-hard-code the user's output language unless language is itself part of the task.
-
-Maintainer documentation may use the language appropriate for its audience. English
-source prompts are a portability rule, not a claim that multilingual Skills are invalid.
-
-## Content that does not belong in a Skill prompt
-
-- release notes, migration history, old-version behavior, or implementation diary;
-- host tool inventories, model pins, package paths, and dependency metadata shared by
-  only one runtime;
-- generic engineering doctrine already owned by user or repository instructions;
-- one-off project facts, volatile external facts, or copied datasets;
-- duplicated command bodies, hook policy, MCP schemas, or private memory behavior;
-- arbitrary coverage, confidence, complexity, option-count, or severity thresholds;
-- pattern matching that turns TODOs, mocks, catch blocks, or line counts directly into
-  findings without a reachable impact;
-- tutorial-style old/new or good/bad comparisons that do not change the workflow;
-- menus of hypothetical alternatives when one repository default already satisfies the
-  contract.
-
-Comparison is appropriate only when the task requires a real decision or verification:
-compare credible alternatives against shared constraints, accepted specification
-against delivered behavior, or independent analyses against authoritative evidence.
-
-## Review checklist
-
-1. Does the description state a precise use condition?
-2. Is every instruction reusable for this Skill rather than copied global policy?
-3. Is host-specific metadata outside the portable prompt?
-4. Does each conditional reference earn its context cost?
-5. Are judgments evidence-based rather than threshold-based?
-6. Are commands thin and agents bounded?
-7. Do positive and negative trigger evals cover accidental activation?
-8. Do source, five generated runtimes, and package contents pass validation?
+Ultra Skills are portable model-facing methods. They describe outcomes, evidence, and
+owner boundaries; host-specific discovery and invocation policy belong in adapters.
+
+## Role selection
+
+Choose exactly one role before writing:
+
+- **user-invoked**: a complete owner-selected workflow with a durable outcome;
+- **model-invoked**: a reusable discipline used by at least two canonical workflows;
+- **router**: read-only diagnosis that recommends the smallest next public route.
+
+A user workflow may recommend but must not invoke another user workflow. A discipline
+with only one real caller should be inlined.
+
+## Portable frontmatter
+
+Source `SKILL.md` frontmatter contains only:
+
+```yaml
+---
+name: lower-case-hyphen-name
+description: What this produces and the concrete situations that trigger it.
+---
+```
+
+Adapters generate Claude/Grok/Kimi invocation flags and Codex `agents/openai.yaml`.
+Do not put host paths, dependency declarations, plugin policy, or release history in
+source frontmatter.
+
+## Required shape
+
+Every Skill has one outcome-led title and these semantic sections:
+
+```text
+## Before you start
+## Definition of done
+## <workflow-specific process>
+## When the owner decides
+## References
+```
+
+User workflows begin by reading `.ultra/tasks.json`, the unfinished task's
+`context_file` and Resume Note, `CONTEXT.md`, and relevant decisions. They name the
+files they write and read them back. Completion criteria must be observable without a
+semantic validator.
+
+Use positive leading words consistently: tracer bullet, seam, deep module, red,
+frontier, and fog of war. Explain a branch by its checkable result, not the model's
+reason for choosing it.
+
+## Progressive disclosure
+
+Keep resident `SKILL.md` short enough to load on every invocation. Move focused detail
+into `references/` and deterministic validation or waiting into `scripts/`.
+
+- Load one research step or review lens at a time.
+- Keep one canonical copy of grilling, TDD, review, domain language, and autonomy rules.
+- Cross-reference another model-invoked Skill by relative path.
+- Do not hide the primary workflow in a script.
+- A script may check paths, schemas, counts, hashes, process status, or other mechanical
+  facts; it may not decide semantic completeness.
+
+Rule-side executable examples live with the consuming Skill. They are never copied
+wholesale into project authority.
+
+## Language and host neutrality
+
+Model-facing Skills, references, scripts, comments, and identifiers are English.
+Shared Skills never mention `.claude`, `.codex`, `.opencode`, `.kimi`, `.grok`, or a
+host-only question surface. Use “host-native question surface” and put the translation
+in the adapter.
+
+## Safety boundary
+
+The owner decides intent, acceptance, reductions, material risk, irreversible actions,
+and external effects. The model owns investigation, design, decomposition, evidence
+interpretation, reversible implementation detail, and final expression.
+
+Semantic gaps are diagnostics. A Skill must not invent a hard gate based on counters,
+regexes, similarity, context estimates, or workflow position. Every real hard effect
+guard names its invariant, authoritative input, blocked effect, and reachable repair.
+
+## Validation
+
+For every changed Skill:
+
+1. run the Skill Creator validator;
+2. resolve every relative reference in the source and installed artifact;
+3. verify its role metadata on all five hosts;
+4. test the accepted workflow with representative valid and adversarial inputs;
+5. confirm no retired runtime vocabulary or host-specific path entered portable text.
+
+The repository's `tests/skill-authoring.test.cjs` and
+`tests/v026-contract.test.cjs` mechanize the portable parts of this contract.