@6reduk/workspace-pipeline 0.1.0

package/docs/lifecycle-cli.md

@@ -0,0 +1,141 @@
+# Lifecycle CLI routing — development scope
+
+The generic dispatcher routes `setup`, `update`, `repair`, `remove`, `switch` and `continue` through
+the native operation APIs and their coordinators. The packaged entrypoint supplies
+compiled Codex, Claude, Kimi and Grok adapters. S11 review and native Kimi/Grok
+verification remain open; use disposable workspaces for these additions.
+For Grok Claude-import suppression use the [scoped launcher](launch.md), not a
+direct harness invocation. File readiness does not certify runtime isolation.
+
+Tests supply a trusted registry directly to `runCli`. There is no argv flag,
+environment-selected module, or pipeline-supplied executable adapter loader.
+Direct library calls without a registry still fail with `cli.providers-unavailable`.
+CLI assembly supplies built-in adapters, never package code.
+
+## Preview and apply contract
+
+Once a trusted registry is provided by the CLI assembly:
+
+```text
+workspace-pipeline setup --workspace <absolute-wrapper> [--manifest <absolute-file>] [--network]
+workspace-pipeline update --workspace <absolute-wrapper> [--manifest <absolute-file>] [--network]
+workspace-pipeline setup --workspace <absolute-wrapper> --apply --preview <absolute-json-file>
+workspace-pipeline update --workspace <absolute-wrapper> --apply --preview <absolute-json-file>
+```
+
+Preview returns the complete prepared JSON on stdout. It may acquire a Git
+source into temporary storage outside the wrapper, but does not write provider
+configuration. Network acquisition requires explicit `--network`. When manifest
+is omitted, setup uses the standard workspace manifest; update uses the recorded
+manifest origin. Relocation does not silently rebind it. The separate source
+rebind workflow is not exposed by these commands yet.
+
+Save prepared JSON privately, inspect its operations and then explicitly invoke
+`--apply --preview`. It may contain configuration secrets and absolute local
+paths; do not commit it or send it to shared logs. Apply does not accept
+`--manifest` or `--network`, acquire a fresh source, or substitute a new preview.
+Missing/stale staged data is an error, not permission to download replacements.
+
+Apply binds the verb and exact wrapper before lock acquisition, then invokes
+existing locked approval, registry, ownership, history, snapshot and drift checks.
+`--apply` authorizes only that saved prepared subject; no approval is inferred
+from preview generation. Existing local opt-in retention is handled by the
+internal lifecycle coordinator, not a second cleanup pass in the dispatcher.
+
+## Output and failures
+
+- stdout: one prepared JSON or operation result.
+- stderr during apply: structured journal/recovery locations and operation events.
+- exit 0: preview created, or observed configuration ready with successful lock
+  release and reporting. It never certifies harness/MCP runtime.
+- exit 1: lifecycle failure/incomplete result, including a wrong verb or wrapper
+  in the prepared package. Read the operation result, not just the exit code.
+- exit 2: invalid invocation, unavailable adapters, input/transport failure.
+
+If stdout fails after a successful apply, exit 2 does not undo that apply.
+Operation events and `doctor` distinguish actual configuration state from output
+delivery. Errors expose stable codes, not raw exception messages or argv secrets.
+No force unlock, rollback, retry or global configuration mutation is performed.
+
+## Offline repair and removal
+
+These routes have the same trusted-registry restriction as setup/update:
+
+```text
+workspace-pipeline repair --workspace <absolute-wrapper>
+workspace-pipeline remove --workspace <absolute-wrapper> [--providers codex] [--bundles claude-grok]
+workspace-pipeline repair --workspace <absolute-wrapper> --apply --preview <absolute-json-file>
+workspace-pipeline remove --workspace <absolute-wrapper> --apply --preview <absolute-json-file>
+```
+
+Repair reconstructs only the approved installed snapshot, not the newest source.
+Removal preserves other installed providers and shared files while needed; full
+removal restores taken-over content and removes only owned scope. Missing/corrupt
+snapshots, backups, unresolved history or conflicting user edits fail closed.
+Neither route reads the original manifest or downloads from Git. `--manifest`
+and `--network` are rejected. `--providers` and `--bundles` are remove-preview-only;
+omitting both previews all installed providers and bundles. Use actual installed
+bundle IDs; selecting a bundle member via `--providers` fails with
+`remove.bundle-required`. The saved subject fixes the actual selection, so apply
+cannot override it. See [removal](remove.md) and [bundle delivery](provider-bundles.md).
+
+The maintenance coordinator validates exact command/workspace and record before
+locking, checks history under lock and calls native approval/replay. It reports
+journal/recovery locations early and preserves partial evidence on failure.
+Successful full removal returns `not-installed` with exit 0, not `ready`; runtime
+is still unverified. A failed output delivery cannot roll back successful work.
+
+Automatic retention remains setup/update-only at this stage; maintenance does
+not silently clean history or use removal approval as cleanup permission.
+Interrupted-operation continuation has a separate exact approval boundary below.
+
+## Switching pipeline
+
+With the same trusted built-in registry restriction:
+
+```text
+workspace-pipeline switch --workspace <absolute-wrapper> --manifest <absolute-incoming-manifest> [--network]
+workspace-pipeline switch --workspace <absolute-wrapper> --apply --preview <absolute-json-file>
+```
+
+The incoming manifest is mandatory for preview. Preparation stages and validates
+the incoming Git package before removal; it does not change workspace files.
+Apply accepts only the saved prepared subject, not manifest/network overrides.
+Under the workspace lock it persists recovery, marks the operation pending,
+executes `remove-old` then `install-new`, and activates only after both phases
+and final targets are checked. Completed phases alone do not mean activation.
+
+Events identify journal/recovery locations and phase progress. An interruption
+between phases leaves the actual state `needs-reconciliation` and the old active
+identity; an operation result of `failed` does not imply unchanged files.
+Re-running switch is not an implicit retry or recovery command. There is no
+automatic rollback, source reacquisition, or retention cleanup in this route.
+Use read-only doctor/history to inspect retained state. Continuation eligibility
+is narrower than arbitrary failure recovery, as described below.
+
+## Continuing an interrupted operation
+
+```text
+workspace-pipeline continue --workspace <absolute-wrapper> --recovery .pipeline/transactions/<run-id>/recovery.json
+workspace-pipeline continue --workspace <absolute-wrapper> --apply --preview <absolute-json-file>
+```
+
+The registry restriction still applies. Select an exact workspace-relative recovery
+record, never the newest filename or timestamp. Preview is read-only and private;
+it may contain desired configuration bytes. Apply accepts no recovery/source/network
+override and reconstructs the saved proposal under lock before any target writes.
+
+This creates a new journal and recovery record. Old records are preserved; desired
+bytes are read back, not written again, and before bytes require the new approval.
+Conflicting bytes, stale pending state, corrupt ancestry or changed evidence reject
+continuation. Removal may end in not-installed; success is not runtime certification.
+Reporter failures retain evidence and never trigger rollback or automatic retry.
+
+The native eligibility rules remain authoritative: general operations require a
+valid pending record without conflicts. Switch accepts an uncertain target or a
+verified open/completed journal still selected by pending state. At a clean
+boundary, `uncertain: null` means no ambiguous write: only unrecorded operations
+and phase checks remain. Completed outcomes are not replayed. After both recorded
+phase checks, an empty remainder permits separately checked activation, not an
+inferred phase success. Failed/corrupt journals and changed targets fail closed.
+No source download, global setting change, force unlock or retention cleanup occurs.

package/docs/lifecycle.md

@@ -0,0 +1,42 @@
+# Setup/update coordination (S6 development)
+
+Internal APIs only; public CLI routing and real provider adapters remain pending.
+
+`prepareLifecycle(input, registry)` prepares an explicit setup or update command.
+It can acquire a Git source into temporary storage outside the workspace, but
+does not edit provider configuration or approve its own output. A wrong verb for
+the current installation is rejected. Incomplete history blocks preparation.
+
+`applyLifecycle(input, registry, {report, retention})` takes the exact prepared plan and a
+separate approval, acquires the workspace lock, rechecks state/history and invokes
+native apply. Callers must coordinate stopped configuration consumers; neither an
+approval nor this lock proves that outside harness sessions have stopped.
+
+The registry and reporter are trusted caller code, never loaded from the pipeline
+source. Reporter events contain paths and status, not credential-bearing contents.
+CLI wiring must provide a reporter to actually print early events.
+
+Journal location events: `planned` (no creation claim), `created` (directory exists),
+`initialized` (start record checked). They include absolute path and run ID.
+Recovery location events: `created-unverified`, then `verified` after readback;
+before creation its intended path is labelled `not-created`.
+
+The final result preserves the last observed location statuses, including failure
+after journal creation but before recovery. A failure before journal allocation
+reports null journal/recovery. A forced kill cannot guarantee a final message.
+Reporter failure during execution stops it; partially written evidence is retained.
+Failure to emit the final result does not rewrite an already successful operation:
+`outputError` is separate. Lock release failure is likewise separately reported.
+No rollback, cleanup, force-unlock or retry is implied by a failure report.
+
+The optional `retention` argument is a separately approved exact cleanup preview,
+not an implicit setup permission. It runs under the same lock after read-only
+main preflight and before the new journal is created. A failed cleanup/report
+prevents setup/update from starting; its own result stays in `result.cleanup`.
+Main preflight is repeated afterwards. See [retention](retention.md) for limits;
+an explicitly enabled local automatic policy is also supported. Manual startup
+cleanup plus automatic policy is rejected. Public setup/update routing remains pending.
+
+Repeated update with unchanged desired deployment remains valid: doctor verifies
+every matching recovery record, and recovery distinguishes completed no-op state
+from before-state using the completed journal, not equality of state bytes alone.

package/docs/migrations/unity.md

@@ -0,0 +1,288 @@
+# Legacy Unity migration — internal synthetic implementation
+
+S10 is in progress. CLI preview, inspection and explicit apply are available for
+synthetic testing; independent review and real deployment approval remain pending.
+
+## CLI preparation and inspection
+
+`workspace-pipeline migration unity preview --workspace <absolute-wrapper> --manifest <absolute-manifest>`
+prepares the complete proposal, staging committed Git source outside the wrapper.
+Add `--network` only to permit remote acquisition. Keep the JSON private: it can
+contain full config bytes. The command does not disable plugins or install files.
+
+`workspace-pipeline migration unity inspect --workspace <absolute-wrapper> --recovery <relative-record> --phase <phase>`
+inspects one explicit saved migration without writes or source acquisition.
+Phases: `deactivation`, `installation`, `recovery`, `closeout`, `compensation`.
+Each selects the corresponding narrow internal planner described below. Unknown
+phases, path escapes, duplicate flags and `--apply` are rejected. Exit 0 means a
+proposal was prepared, NOT installation readiness or approval. Blocked proposals
+return nonzero. To authorize exactly a saved proposal, use the separate command:
+
+`workspace-pipeline migration unity apply --workspace <absolute-wrapper> --preview <absolute-preview-file>`
+
+This verb is explicit authorization of the saved installer-bound envelope. It
+accepts no source/network/phase overrides. Initial migration runs deactivation,
+installation and validated closeout under its lock. Recovery/compensation previews
+execute only their selected bounded operation; a phase result may still require a
+fresh closeout preview and approval. Exit 0 means completed or legacy-restored;
+exit 1 means needs-reconciliation, exit 2 means rejected/error (writes may have
+occurred before an I/O failure). Inspect the reported recovery/log paths; never
+infer rollback from nonzero exit. Stop harness sessions/config editors before apply.
+Private records remain under .pipeline/migrations; do not delete active recovery
+evidence. No automatic cleanup or publication occurs.
+
+CLI output now wraps the inner proposal in `installer-bound-migration-preview`.
+Its installer identity hashes `package.json`, `src/` and `schemas/`, independently
+of installation directory. Verify this envelope before future apply; changed
+installer payload requires a new preview. This does not version-pin project docs,
+the harness or model. Docs/tests are excluded from this executable-payload identity.
+It is not a publisher signature, a hash of tar compression bytes, or verification
+of installed dependency contents. `npm run test:packed:identity` tests identity
+through an offline tarball install and rejects a changed installed payload.
+prepareLegacyUnityOptOut is a pure byte transformer, not a writer or approval.
+It disables only unity-sdd-pipeline@unity-sdd in the supplied local Codex/Claude
+configuration. Other bytes are preserved. Missing/ambiguous activation and active
+inline TOML ancestors fail closed. No global settings are accepted implicitly.
+
+The coordinator binds the wrapper, exact before/after bytes and approved source;
+the public CLI additionally binds the installer payload. Prefetch and conflict
+checks precede legacy deactivation.
+Existing AGENTS.md/CLAUDE.md require explicit takeover and private backups.
+Global caches, game and docs remain outside scope. Old .unity-sdd markers are not
+ownership. The transformer alone is neither a migration nor recovery mechanism.
+Interrupted operations need observed-state reconciliation under the CLI lock and
+fresh continuation/compensation approval, never blind rollback. Users must stop
+active harness sessions. Do not deploy until the complete route is reviewed.
+
+The configuration-only deactivation record includes both complete before/after
+payloads and hashes. Treat it as private: foreign settings may contain credentials.
+Validation rebuilds the narrow transformations instead of trusting caller hashes.
+Inspection classifies each current target as before, after, unchanged-disabled or
+conflict. It never establishes ownership, authorizes restoration, or writes files.
+An independently edited file equal to after bytes is not proof of our execution.
+This record has no wrapper/source/approval binding; it is an internal component,
+not a complete apply preview. The outer coordinator must supply those bindings.
+
+Read-only preflight now acquires a committed Git source into external preparation
+storage, verifies its inventory and Unity identity, and binds the wrapper plus six
+legacy entry/config/marker file hashes. Rechecking uses staged bytes without Git
+or network. Existing .pipeline metadata, missing legacy files, changed wrapper
+bytes and changed package bytes block this preparation route. No target writes,
+entry takeovers, journal or approval are implemented by this preflight. Its digest
+is integrity evidence, not authority; native registry/layout validation and a full
+apply transaction are supplied by the internal routes below. This inner preflight
+does not bind the installer; the public CLI envelope binds its executable payload,
+not the tarball bytes, as described above.
+
+prepareLegacyUnityPreview now renders the compiled Codex/Claude adapters and
+shared entry against the verified source and workspace manifest. Only AGENTS.md
+and CLAUDE.md receive proposed exact-byte takeovers; other foreign collisions
+still fail closed. Original entry bytes are retained in the private proposal and
+the setup plan declares their native backup paths. No backup file is written yet.
+
+The embedded setup preview uses virtual post-deactivation observations. It is
+NOT independently applicable to the current wrapper and must never be submitted
+directly to generic apply. The outer migration requires both ordered phases under
+one approval and appropriate recovery semantics. It also binds original target
+observations and checks the manifest again after rendering. The internal coordinator
+below handles deactivation, native installation and same-process finalization.
+
+verifyLegacyUnityPreview binds explicit caller approval to the whole proposal,
+checks the selected wrapper and current manifest, verifies staged package bytes
+and reconstructs every proposed edit with compiled adapters. Changed instructions,
+paths or phase order are rejected even if a caller recomputes the outer digest.
+This verification performs no acquisition, writes or locking, and must be repeated
+under the eventual transaction guard before writes. It is not an execution capability.
+
+Integration constraint: ordinary setup recovery represents one installation and
+cannot truthfully cover a preceding legacy deactivation. Do not manufacture an
+old active deployment or record deactivation as init/repair. The final coordinator
+must persist both phases and gate all normal lifecycle writers while migration is
+incomplete; native doctor/history/continuation must understand the resulting record
+before any ready activation is allowed. CLI apply delegates to these checked routes.
+
+Pending guard implemented: presence of `.pipeline/migration-operation.json`
+blocks ordinary workspace locks and existing repository/lifecycle entry guards.
+It is checked again when a held lock is used, including repository-operation locks.
+Empty, malformed, directory and link markers are not parsed as permission to proceed.
+History reports incomplete; doctor reports needs-reconciliation, ready=false.
+No marker is deleted or auto-repaired. Migration-specific recovery/execution
+capabilities were initially unavailable; the internal begin/deactivate route below
+now supplies one. Do not create the marker manually in real workspaces. This guard
+alone does not perform migration.
+
+## Internal begin and first-phase execution
+
+beginLegacyUnityMigration validates the full approved preview before locking and
+again under a process-local migration lock. It first writes a pending marker,
+then the private recovery record containing original bytes and approval binding.
+Only after both readbacks does it seal the capability. JSON cannot recreate the
+capability. Changed/missing marker or changed recovery invalidates it. Ordinary
+and repository-operation locks cannot bypass it. The caller must release the
+returned lock; failure does not delete recovery evidence or restore targets.
+
+The returned internal deactivate method writes exact Codex and Claude opt-outs
+with per-target intent/outcome records under the migration's deactivation directory.
+An error stops the remainder. A write followed by an error is uncertain, not
+silently successful. A repeated call is not an automatic retry. Final history
+readback audits the fixed phase journal. Instructions, skills and game files are
+not written in this phase. Result remains needs-reconciliation after success:
+the second phase must run separately through the same authenticated capability.
+
+## Internal second-phase installation
+
+The returned install method requires the complete, hash-linked deactivation journal
+and exact disabled configuration bytes. Disabled settings alone are not execution
+evidence. It delegates installation to native apply, including re-rendering, checked
+writes, instruction takeover backups, native transaction recovery and activation.
+The full preview approval supplies the subordinate installation authorization;
+it is not a new inferred human decision. Source snapshot and Git object preparation
+must remain outside the wrapper and present for verification.
+
+An installation locator binds the native journal/recovery to the outer migration
+and deactivation result. A second call is not an implicit retry. An interruption
+preserves recovery and leaves ordinary lifecycle operations blocked. Even when
+native apply returns ready, the outer result is needs-reconciliation: the pending
+marker stays in place and doctor must not report readiness until finalization.
+
+## Internal same-process finalization
+
+The returned finalize method requires a completed first-phase journal, exact native
+prepared-plan/approval bindings and a successful native recovery inspection of the
+current installation. Legacy binding files must remain unchanged. It writes an
+exclusive completion record, repeats the checks and removes only the exact pending
+marker. Recovery, original backups and journals are retained. Removing the marker
+invalidates the migration write capability; the caller must release the lock before
+ordinary doctor can report readiness. Readiness covers configuration, not runtime.
+
+Interruption before marker removal leaves the workspace blocked. An existing
+completion record is not permission to retry or delete the marker manually.
+Supported restart and compensation routes are described below; they require fresh
+approval and do not themselves authorize a real-workspace deployment.
+
+## Read-only restart closeout preview
+
+prepareLegacyUnityCloseoutResume accepts an exact persisted migration recovery
+path, verifies marker/recovery/preview bindings and both installed phases, and
+returns a digest-bound proposal. If a matching completion record already exists,
+only marker removal is proposed; otherwise completion creation precedes removal.
+Conflicting completion evidence or incomplete installation is rejected. No lock,
+write, network acquisition, lease or implicit approval is issued (executable=false).
+This preview covers only the installed-phase restart case. For partial deactivation,
+see "Partial deactivation inspection"; for interrupted installation, see "Interrupted
+installation preview"; for bounded restoration, see "Explicit pre-install
+compensation". Approved closeout execution is described next.
+
+## Approved restart closeout execution
+
+applyLegacyUnityCloseoutResume requires fresh approval of the exact closeout
+preview digest. It reconstructs the proposal before acquiring a new process-local
+migration lease, checks again under the workspace lock, and saves a separate
+authorization record. It creates completion only when proposed, verifies the
+result and authorization, and removes the exact marker. Old completion records
+are preserved. The lock is released on success or error; no error triggers rollback.
+If interruption creates completion, the previous preview is stale: inspect again
+and approve the new remaining-operation preview. Tests currently exercise fresh
+leases after releasing the former lock, not termination of a live harness process.
+CLI apply can invoke this writer only with its saved installer-bound proposal.
+
+## Partial deactivation inspection
+
+prepareLegacyUnityDeactivationResume reads the persisted migration and validates
+the bounded first-phase journal prefix (start, intents, outcomes, phase check).
+It compares current files with exact before/after bytes and preserves failed or
+uncertain history. A desired hash without an intent is not attributed to this
+migration; completed evidence followed by before bytes is a conflict, not retry.
+Foreign config bytes block the proposal, while unrelated target drift is rejected.
+The result proposes write-disabled or confirm-observed actions without executing
+them. It rejects the native installation locator/state: partial installation needs
+its own recovery route. This is not an executable continuation or compensation.
+
+applyLegacyUnityDeactivationResume is the internal approved writer for that
+proposal. It reconstructs the preview, acquires a fresh migration lease/lock and
+writes a separate digest-selected attempt journal. It checks surrounding targets
+and original evidence before each operation. Observed disabled bytes are confirmed;
+remaining exact before bytes can be changed to disabled. Errors preserve uncertainty
+and stop execution; original failed/uncertain records remain untouched. Replaying
+the same attempt cannot overwrite its journal. Both success and failure keep the
+migration blocker. phase-observed alone is not permission to advance to installation
+or remove the marker: the evidence verification below is mandatory.
+
+## Resumed-phase evidence at the installation gate
+
+The installation/finalization phase verifier now recognizes exactly one completed
+deactivation-resume attempt. It reconstructs the two narrow operations from the
+original before/after contract and observed hashes; checks approval, original
+journal prefix, unchanged observations, classifications and the six new records;
+and verifies record membership/hashes again. Incomplete, tampered or multiple
+attempts block the gate. No latest-by-time selection or historical PASS rewrite.
+This only supplies phase evidence to existing installation validation; passing
+this verifier does not create a write capability. The restart route below requires
+a separate fresh approval.
+
+## Fresh installation after recovered deactivation
+
+prepareLegacyUnityInstallResume binds the persisted migration, completed phase
+evidence, current target hashes, prepared snapshot and original native setup plan.
+It rejects an existing installation locator or state rather than retrying a started
+installation. applyLegacyUnityInstallResume reconstructs that preview, requires
+its exact approval, acquires a new process-local lease and rechecks under lock.
+It saves a separate authorization record and delegates to native installation.
+Result remains needs-reconciliation until separately approved closeout. Recovery
+of an interrupted native installation is not implemented by this route.
+
+## Interrupted installation preview
+
+An initial setup interrupted after its native recovery record is persisted but
+before pending state is published can be continued with a new approved recovery
+preview. This requires absent state, validated snapshot/backups, an intact original
+journal with no target intents/outcomes and all targets/dependencies still at their
+original bytes. It creates a separate transaction; it never fabricates the missing
+pending state or rewrites historical evidence. Existing-state updates do not gain
+this pre-pending route.
+
+Earlier interruptions with an installation locator but missing/incomplete native
+journal or recovery record remain blocked: there is insufficient validated native
+evidence for this continuation. Do not remove the marker manually. Repeated failed
+continuations remain unsupported as described below.
+
+prepareLegacyUnityInstallRecovery wraps the existing native prepareContinuation,
+without a separate target-writing algorithm. It binds migration/marker, completed
+first-phase evidence, installation locator and exact original prepared setup to
+the selected native recovery. Legacy binding files are checked separately from
+native-owned targets. The native planner proposes verify-readback for observed
+desired bytes and write-desired for remaining before bytes; conflicts fail closed.
+The result requires new approval, stays executable=false and never clears the
+migration blocker or rewrites an old outcome.
+
+applyLegacyUnityInstallRecovery reconstructs a newly approved preview, acquires a
+fresh migration lease and uses native applyContinuation. A separate authorization
+and exclusive continuation locator bind the new native recovery to this migration.
+Closeout checks the exact authorized continuation and its native lineage to the
+original interrupted setup before accepting the new activation. It does not use
+an unrelated ready state or overwrite original recovery. The migration blocker
+remains until separately approved closeout. An interrupted continuation remains
+blocked; repeating it is rejected. Multi-continuation selection/recovery is pending.
+
+## Explicit pre-install compensation
+
+prepareLegacyUnityCompensation and applyLegacyUnityCompensation cover only the
+original deactivation attempt before native installation or resumed deactivation.
+Existing native preparation/state or resumed-attempt records block this narrow
+route. A new digest-bound approval authorizes restoration of the two exact original
+local configuration files and marker removal after complete verification. It never
+changes shared caches, global settings, instructions, game files or documentation.
+
+Separate compensation intent/outcome records preserve the original history. An
+error stops writes and retains the marker; no implicit retry/rollback follows.
+Success returns legacy-restored, not ready for the new pipeline. Migration evidence
+and .pipeline metadata remain; this is not metadata cleanup or authorization for
+another setup. Compensation after installation/resumed attempts and recovery of
+an interrupted compensation remain unsupported.
+
+These writers and CLI apply remain development-preview functionality.
+Real application requires a separately approved real-wrapper preview. Only the
+bounded resume and pre-install compensation routes described above are supported.
+Repeated interrupted recovery attempts, multiple installation continuations and
+post-install compensation remain unsupported; do not clear the marker to bypass
+these limitations.

package/docs/native-provider-format.md

@@ -0,0 +1,149 @@
+# Native source components (S8 / S11 implementation)
+
+These are trusted CLI adapters, not native harness plugins. They consume verified
+Git files through the existing manifest component paths; source code is never
+loaded as a CLI adapter. Development dispatch includes Codex, Claude, Kimi and Grok.
+Harness discovery, packaged lifecycle and pilot readiness remain
+separate checks.
+
+## Skills
+
+All four providers accept a directory of `<name>/SKILL.md` files. Each file has YAML
+frontmatter containing exactly `name` and `description`, and a nonempty body.
+Directory and declared name must match. Supporting files remain in the snapshot.
+Names are lowercase ASCII letters/digits/hyphens, beginning with a letter, up to
+63 characters; `constructor`, `prototype` and `default` are not accepted.
+
+The CLI generates a small native skill in `.agents/skills/` (Codex) or
+`.claude/skills/` (Claude). It retains the name/description and directs the agent
+to read the complete source skill in the installed snapshot. Relative links are
+resolved from that source file. This avoids rewriting the canonical procedure
+and its links. Package authors must ensure those source-relative links resolve.
+An existing foreign skill is an ownership conflict, not silently overwritten.
+Names are not automatically changed: references in the pipeline keep working.
+Authors should use a pipeline-specific prefix. User/global harness precedence
+is not certified by file installation or these adapters.
+
+## Agents
+
+Codex: a flat directory of `<name>.toml`, with exactly three string assignments:
+`name`, `description`, `developer_instructions`. The adapter registers named
+roles in `.codex/config.toml`, pointing to local `.codex/agents/<name>.toml`.
+Generated role files contain only `developer_instructions`, with source routing
+followed by the original instruction text. No model or permission is selected.
+The reserved scalar role name `enabled` is also rejected.
+
+Claude: a flat directory of `<name>.md`, with exactly `name` and `description` in
+YAML frontmatter and a nonempty instruction body. The generated
+`.claude/agents/<name>.md` routes to the source. Optional harness-specific models,
+tools, hooks and permission fields are currently unsupported and rejected, not
+dropped silently. A null agents component explicitly means no packaged agents.
+
+## MCP
+
+Each non-null MCP component points to JSON with exactly `mcpServers`, a nonempty
+map of named servers. Supported server shapes:
+
+- `type: stdio`, `command`, optional string-array `args` and string-map `env`.
+- `type: http`, `url` with HTTP(S), no userinfo or fragment.
+
+Unknown fields/transports fail closed. There is no secret resolution, OAuth,
+trust grant or server execution in rendering. Environment values are literal
+configuration data; do not place secrets in public sources. Automatic startup
+later remains harness behavior, and users must trust the pipeline supplier.
+
+Codex receives individual `/mcp_servers/<name>` TOML fields; Claude receives
+individual `/mcpServers/<name>` fields in wrapper `.mcp.json`. Other servers and
+user settings retain existing ownership rules. Runtime availability is not
+inferred from configuration presence.
+
+## Entry and shared ownership
+
+For a declared Claude/Grok bundle, [bundle rules](provider-bundles.md) take priority:
+one full source-authored CLAUDE.md and joint lifecycle. The following neutral-entry
+behavior is retained only for standalone sources without bundle declarations.
+
+Claude and Grok share a provider-neutral `CLAUDE.md`: it imports `@AGENTS.md` and
+explicitly instructs the reader to read AGENTS.md, without relying on import
+syntax support in Grok. It contains no direct Claude-specific route. Normal
+foreign-file conflict checks apply. Codex uses common `AGENTS.md`. Non-null provider
+entry components are conditional routes from AGENTS.md; follow only the route for
+the current harness. These links do not enable a provider.
+The common entry lists available source routes independently of the selected
+installation subset so removing one provider does not invalidate its remaining
+owner's reconstruction. AGENTS.md remains until the last provider is removed.
+CLAUDE.md has one shared owner but only two consumers: Claude and Grok. Removing
+either retains it while the other remains; removing its final consumer restores
+the original file or removes the created file, even if Codex remains installed.
+
+An update migrates the old managed Claude-owned entry only after checking its
+recorded bytes; original backup lineage is preserved. Edited or foreign files
+remain conflicts, not implicitly authorized replacements. Installed version-1
+adapter output can still be replayed for repair/removal before updating. Adapter
+versions describe CLI rendering, never the validity of project documents.
+
+Source contracts are intentionally bounded. `compatibility-isolation` is not a
+claimed capability here. Legacy plugins/global imports require separate migration
+and native checks; they are not disabled by these renderers.
+
+## Official format references
+
+- [Codex skills](https://learn.chatgpt.com/docs/build-skills)
+- [Codex named agent/config reference](https://learn.chatgpt.com/docs/config-file/config-reference)
+- [Claude subagents](https://code.claude.com/docs/en/sub-agents)
+- [Claude MCP scopes](https://code.claude.com/docs/en/mcp)
+
+Consulted 2026-09-20/21. Native-version observations and limitations are recorded
+in the S8 provider-discovery artifact; current docs alone do not certify installed
+harness behavior.
+
+## S11 development: Kimi and Grok components
+
+These renderers are registered in the development CLI for configuration delivery.
+Select providers in the workspace manifest, then use normal preview/apply setup.
+Native discovery, trust and runtime isolation are separate from file installation.
+
+Both use the same strict skill frontmatter and immutable routing described above:
+Kimi writes `.kimi-code/skills/<name>/SKILL.md`; Grok writes
+`.grok/skills/<name>/SKILL.md`. Agents accept the same restricted Markdown source
+shape as Claude and use their respective `agents/<name>.md` directories. Kimi
+rejects `agent`, `coder`, `explore`, `plan`; Grok rejects `general-purpose`,
+`explore`, `plan`, to prevent unintended built-in replacement. No roles are
+invented when the package declares `agents: null`.
+
+Canonical MCP JSON is translated to named fields in `.kimi-code/mcp.json`
+(`/mcpServers/<name>`) and `.grok/config.toml` (`/mcp_servers/<name>`). Canonical
+`type` is omitted from these native entries. Only those entries are owned:
+whole-file replacement and unrelated configuration fields are refused. Existing
+foreign entries are conflicts or preserved, never silently adopted.
+
+Both use the common AGENTS.md provider route. No Kimi SYSTEM.md, Grok system
+prompt override, authentication, trust or model settings are generated.
+
+### Discovery and launch limitations
+
+Kimi and Grok can discover generic `.agents` skills. Removing one provider's
+owned routes therefore does not prove that harness can no longer discover a
+pipeline still installed for another provider. Installer ownership isolation and
+native discovery are distinct checks.
+
+Grok's child-environment helper sets five Claude compatibility switches to false:
+skills, rules, agents, MCP and hooks. It changes only the child environment,
+including removal of conflicting Windows key spellings. It does not switch
+accounts, rewrite global configuration, grant trust or suppress native plugins.
+The development CLI exposes a guarded [launch command](launch.md). Ordinary direct `grok` launch is
+not certified by component rendering; local TOML presence is insufficient proof
+of effective compatibility settings. Diagnostic plugin inventory can retain a
+plugin even when its imported skill is disabled.
+
+In the tested Grok 1.0.40 session, root CLAUDE.md was still read with all five
+flags false. The common entry deliberately accommodates this behavior. It does
+not prove suppression of duplicate agents, hooks or plugin MCP. Those runtime
+checks remain separate; shared instructions do not imply full Claude compatibility.
+
+Source and native inspect probes support development decisions; session-visible
+discovery, trust behavior and execution remain separately tested requirements.
+References: [Kimi skills](https://www.kimi.com/code/docs/en/kimi-code-cli/customization/skills.html),
+[Kimi agents](https://www.kimi.com/code/docs/en/kimi-code-cli/customization/agents.html),
+[Grok agents](https://docs.x.ai/build/features/subagents),
+[Grok MCP](https://docs.x.ai/build/features/mcp-servers).