@6reduk/workspace-pipeline 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 6reduk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# Workspace Pipeline CLI
+
+`@6reduk/workspace-pipeline` — workspace-local pipeline delivery. Licensed under MIT.
+
+**`--help`, read-only `doctor`, and `logs list/clean/policy` are implemented.**
+Setup/update/repair/remove/switch/continue use compiled workspace-local adapters
+for Codex, Claude, Kimi and Grok. No native plugin installation
+or global activation is performed. Claude/Grok shared-entry and skill routing were
+observed in disposable sessions. Kimi native verification is deferred; its
+configuration renderer remains experimental. Real-project migration requires an
+explicit preview and approval; installation is not blanket runtime certification.
+
+Grok's Claude-import suppression requires the [scoped launch command](docs/launch.md).
+File installation does not establish native session discovery or runtime isolation;
+Kimi/Grok checks and known generic-skill discovery limits are documented in
+[native component formats](docs/native-provider-format.md).
+Claude/Grok can be supplied as a single [provider bundle](docs/provider-bundles.md):
+separate native configurations, one full CLAUDE.md, and joint lifecycle. A source
+may supply either member or both; the CLI never invents missing configurations.
+
+## Purpose
+
+Configure a workspace using a standalone pipeline from a local or remote Git
+repository's committed tree. Pipeline packages contain shared rules and provider
+skills, agents, MCP declarations and entry instructions; no native plugin lifecycle
+is required.
+
+The CLI supports single-repository and multi-repository layouts with an
+explicit documentation location. Each workspace owns its installed resources.
+Package versions describe installation state, not the validity of project documents.
+
+Provider discovery, isolation, model behavior and live MCP remain distinct checks;
+successful file installation does not certify runtime behavior or task approval.
+
+## Development
+
+Requires Node.js 22 or newer and npm. The contract layer uses locked Ajv and YAML
+dependencies. See [contracts](docs/contracts.md) and [collaboration](docs/collaboration.md).
+
+```sh
+npm ci --ignore-scripts
+npm run check
+npm test
+node src/cli.js --help
+node src/cli.js doctor --workspace /absolute/path/to/workspace --json
+npm run pack:check
+npm run test:packed:providers
+```
+
+The executable name is `workspace-pipeline`. Doctor prints JSON: exit 0 means
+observed configuration ready, 1 means not ready/incomplete, 2 means invocation or
+transport error. Unsupported commands exit with code 2. On Windows use an absolute
+path such as `C:\Projects\my-workspace`. See [doctor](docs/doctor.md) for limits.
+
+For journal listing and explicit cleanup, see [retention](docs/retention.md).
+Cleanup requires a saved, reviewed preview and a separate `--apply --preview`
+invocation. It never deletes snapshots, backups, project files or provider configs.
+Startup cleanup is disabled unless the user enables a local policy via
+`logs policy set`; no numeric defaults are assumed. Internal setup/update honors
+that policy; public setup/update uses the same coordinator. Policy commands only
+write `.pipeline/retention.json`, never harness settings or project documents.
+Repository init/adopt previews acquire the explicitly selected Git pipeline source;
+remote access additionally requires `--network`. No command launches MCP or changes
+credentials. Repository setup and provider activation are separate steps.
+See [repository commands](docs/repositories.md), [recovery](docs/repository-recovery.md)
+and [manual recovery boundaries](docs/repository-manual-recovery.md).
+See [lifecycle CLI](docs/lifecycle-cli.md) for preview/apply and continuation
+contracts, including current restrictions and private-preview handling.
+
+## Distribution boundary
+
+The npm allowlist contains `src/`, `schemas/` and `docs/`, plus npm's standard package metadata,
+README and license. Customer manifests, private pipeline definitions and credentials
+do not belong in this repository or the published package.
+
+Verification CI does not publish. The separately dispatched release workflow
+builds a tested tarball; npm publication remains gated until bootstrap and trusted
+publishing are configured. See [release procedure](docs/release.md).

package/docs/collaboration.md

@@ -0,0 +1,59 @@
+# Collaboration contract
+
+Scope: multiple harnesses may be configured in one workspace. This does not make
+concurrent edits safe or create a distributed lock.
+
+## Task owner and handoff (CON-03)
+
+One owner controls each active task/artifact scope. Record task ID, owner, files,
+source revision/before hashes, current step, unresolved questions and handoff target
+in the project's task artifacts, not in machine-local installer state.
+
+Before an overlapping edit, the next agent reads that handoff, checks the before
+revision/hashes and explicitly takes ownership. Conflicts stop the edit; old approvals
+are not silently reused for changed subjects. Review independence must be disclosed.
+Independent agents can work on disjoint scopes only with explicit ownership.
+
+The CLI does not orchestrate agents or certify their compliance with these rules.
+A task claim is advisory, not a lock preventing all harness writes.
+
+## Installer exclusion (CON-01/02)
+
+The internal S5 coordinator acquires its lock through the caller: one exclusive
+lock per canonical workspace. It rechecks before bytes and stops the remaining
+operation plan on drift/failure. A second workspace remains independent. Abandoned
+locks are preserved; neither age nor a recorded PID authorizes deletion.
+
+Before update/remove/switch/repair, coordinate and stop sessions using the affected
+configuration. The CLI cannot reliably discover every outside agent/editor or revoke
+already loaded instructions. Synthetic Windows tests cover separate-process
+exclusion, interrupted writes and read-only recovery. CLI lifecycle commands and
+real harness behavior are not implemented/certified by those tests.
+
+Recovery requires the exact transaction record and never resumes execution,
+rolls back, clears a lock or guesses the latest transaction. A stop before recovery
+publication may leave an orphan start journal; preserve it as inert evidence.
+Interrupted replacement staging files are also preserved, not safe to delete by
+glob. Pending-state resolution needs an explicit scoped lifecycle operation;
+until that command exists, the workspace cannot be automatically repaired.
+
+The prepared preview checks the inline recovery budget (2 MiB and 50k parser nodes)
+and refuses oversized plans with `plan.recovery-budget` before returning a preview
+for approval. Split work into smaller plans; source blob limits are not deployment
+envelope limits. Apply still validates the actual serialized records before writes.
+
+Journal appends check the current head and new record. Full history is checked at
+terminal result, activation and recovery: older-prefix damage may be detected at
+those later gates, never treated as a valid completed transaction. This bounded
+detection latency and cooperative locking are not hostile-OS protection. Power
+loss/directory durability, ACL behavior and non-Windows execution remain unverified.
+
+## Across developers and machines (CON-04)
+
+Use branches/worktrees plus review and a shared task authority in Git or the selected
+board. Each developer owns their local wrapper; shared documentation belongs in the
+declared repository. Do not commit credentials, machine-local state or secret-bearing
+backups.
+
+A local workspace lock is not a distributed lock. Installer readiness, live harness
+discovery, safe parallel operation and producer acceptance are separate claims.

package/docs/config-fields.md

@@ -0,0 +1,65 @@
+# Owned configuration fields
+
+S11 development: setup includes Codex, Claude, Kimi and Grok adapters.
+
+Trusted adapters propose changes; this layer does not grant approval, install a
+plugin, start a harness/MCP server or edit any global configuration.
+
+## JSON and TOML
+
+JSON field requests retain their existing JSON-pointer ownership semantics.
+Claude's root `.mcp.json` is restricted to individual named `/mcpServers/<name>`
+entries. Whole-file replacement and taking over the entire server map are refused.
+Kimi's `.kimi-code/mcp.json` has the same named-entry restriction. JSON output is
+reserialized with two-space indentation and a final newline: foreign values are
+preserved, but the original JSON whitespace is not promised.
+
+Codex `.codex/config.toml` uses `toml-fields` requests. Only named `/agents/<name>`
+and `/mcp_servers/<name>` entries are addressable. Reserved scalar agent settings,
+model, auth, permissions and project trust are outside this editor's scope.
+Format is selected by this exact destination, never by executable source code or
+a heuristic based on the file's contents. Existing state kind `field` and hashes
+remain format-independent; no document/pipeline semantic version gate is added.
+Grok's exact `.grok/config.toml` destination also uses TOML, restricted to named
+`/mcp_servers/<name>` entries. Its agents are separate Markdown files. Compatibility
+flags are child-environment launch settings, not owned TOML edits.
+
+An entry is owned as a whole object. Concurrent changes inside that object cause
+a conflict, including extra fields; foreign sibling entries remain foreign.
+Equal foreign values do not silently become owned. Exact explicit takeover still
+requires the ordinary preview/apply approval and backup.
+
+## Preservation and limits
+
+TOML is parsed as TOML 1.0 using pinned `toml-eslint-parser` 0.10.1. AST source
+ranges select changed entries; unrelated text, comments and newline spelling are
+not reserialized. Changed entries are rendered deterministically and reparsed;
+full semantic comparison checks that foreign values stayed unchanged. Comments
+outside the replaced key/value spans stay in place, even if the former section
+was removed. Empty lines/implicit parent tables may remain after removal.
+
+- 2 MiB input/output and bounded AST traversal (50000 nodes, depth 64).
+- Owned values must be JSON-domain TOML values; null/dates/nonfinite/unsafe numbers
+  are refused. Foreign TOML values are preserved without conversion to JSON.
+- Named entries may use dotted keys, quoted keys and ordinary nested sections.
+- An inline ancestor such as `agents = { ... }` cannot be split while preserving
+  foreign source spans: a changing request returns `toml.inline-ancestor`.
+- Array-of-table entries and scalar parents are not supported owned entries.
+- Parser diagnostics expose stable codes, not excerpts that may contain secrets.
+
+Planner, doctor, repair, removal, backup checking and field-only historical
+projections use the same destination codec. Repair uses installed snapshot data,
+not latest upstream. The transaction engine still binds the exact complete
+before/after file bytes and stops on drift; field projections do not authorize
+continuation of uncertain operations.
+
+## Evidence boundary
+
+Unit tests cover text preservation and conflicts. Synthetic lifecycle tests cover
+setup/update/doctor/repair/remove and original-value backup restoration. This does
+not certify native runtime behavior, MCP startup or model-visible instruction
+loading. All four compiled adapters are implemented; bounded native discovery
+evidence and its limitations are recorded separately.
+
+Parser source/API: [toml-eslint-parser](https://github.com/ota-meshi/toml-eslint-parser)
+and [AST range specification](https://github.com/ota-meshi/toml-eslint-parser/blob/main/docs/AST.md).

package/docs/contracts.md

@@ -0,0 +1,149 @@
+# Contract layer (S1)
+
+This is a library layer, not an operational installer. The executable still exposes
+only help. No provider is ready. Source acquisition, physical containment and apply
+are later stages.
+
+## Reading route
+
+- Portable package: [pipeline schema](../schemas/pipeline.schema.json).
+- Portable workspace: [workspace schema](../schemas/workspace.schema.json).
+- Shared types: [common schema](../schemas/common.schema.json).
+- Package file list: [inventory schema](../schemas/inventory.schema.json).
+- Local deployment: [state schema](../schemas/state.schema.json).
+- File-operation preview/receipt: [operation schema](../schemas/operation.schema.json).
+- Agent coordination: [collaboration](collaboration.md).
+
+The four portable schemas are the reviewed v1 definitions. They do not invoke remote
+schema resolution. New local state/operation schemas are implementation subjects for
+review; they are not project governance versions.
+
+## Parsing and validation
+
+`parse(text, format)` accepts JSON or YAML 1.2 core representing JSON-domain data.
+It rejects duplicate keys (including escaped JSON keys), multiple documents, explicit
+tags, anchors/aliases, merge keys, non-string mapping keys, prototype-sensitive keys,
+non-finite/unsafe integer numbers, input over 2 MiB, depth over 64 and over 50,000 nodes.
+Explicit tags/aliases are deliberately unsupported on both keys and values, not
+partially expanded. Node/depth limits count mapping keys as well as values.
+Multiple documents produce parse.documents; parser syntax failures produce parse.syntax.
+A leading BOM and CRLF are allowed. Callers loading bytes must decode UTF-8 strictly;
+this API accepts text, not arbitrary byte buffers.
+
+JSON syntax is first checked with JSON.parse; the YAML AST then checks keys before
+conversion. Returned mappings have null prototypes. Errors expose stable codes,
+not parser excerpts or source values. These are domain inputs, not a general-purpose
+editor for existing harness settings: preserving foreign comments/format is S8/S11.
+
+`validateStructure(kind, value)` uses local Ajv 2020-12 schemas without coercion,
+default insertion or field removal. It does not mutate inputs. Strict type-placement
+and required-placement lint checks are disabled for the reviewed conditional schemas;
+schema validation itself is not disabled.
+The common schema is registered for references only: common is not a public
+document kind and validateStructure('common', ...) fails with schema.kind.
+
+Implementation references: [YAML document API](https://eemeli.org/yaml/#documents),
+[YAML parser options](https://eemeli.org/yaml/#parse-options),
+[Ajv JSON Schema](https://ajv.js.org/json-schema.html).
+Dependencies are exact-versioned with a lockfile; no package scripts run to parse data.
+
+## Semantic entry points
+
+- `validateBundle(pipeline, workspace, adapters?)`: provider subset/capabilities,
+  required-null rejection, explicit layout versus named profile, reference IDs, clone
+  subdirectory, custom/default common entry selection and lexical package paths.
+  Pipeline-source subdirectory is checked both in bundles and stored snapshots;
+  dot means package root, other values follow portable-path rules.
+  Omitting adapters checks declarations only, never certifies a harness.
+- `validateInventory(inventory, {inventoryPath, manifestPath})`: lowercase SHA-256,
+  self-entry, mandatory manifest, path/case collisions, trailing dot/space and cap.
+  9,999 entries plus the inventory equals the 10,000-file cap.
+- `renderEntry(text, layout)`: only repository.<id> and documentation substitutions;
+  unknown or malformed tokens fail, including extra braces adjacent to a token.
+  Ordinary single braces (for example JSON around a quoted token) remain literal.
+  No expressions are evaluated.
+- `resolveEntryChange(...)`: pure ownership decision; foreign content conflicts
+  unless explicitly preserved/replaced. A merge must be prepared as a separately
+  reviewed desired result. S4/S8 must compute the supplied hashes from actual bytes.
+
+Physical inventory equality, blob hashes and size totals are S2. Repository overlap,
+canonical roots, reserved roots, symlink/reparse containment and resolved path budgets
+are S3. These checks cannot be replaced by a structural PASS.
+
+## Adapter boundary
+
+`src/providers/interface.js` declares five capabilities, including behavioural
+compatibility-isolation (no artificial corresponding file). Non-null components imply
+capabilities even if requires omits them. Required null components and empty providers
+fail. An adapter has id/version/capabilities plus pure validate/plan methods.
+
+Adapters are trusted CLI modules, never executable modules loaded from the pipeline.
+The test double is only a contract fixture and produces no operations. S8/S11 must
+verify native provider roots and actual discovery before enabling a real adapter.
+Adapters validate their data before proposing operations; they do not perform writes.
+Generic planning and ownership checks must inspect proposed operations in S4.
+
+## Local state
+
+State contains canonical workspace, configuration status, independent runtime status,
+active deployment or null, and pending plan digest or null. An active deployment
+contains pipeline/version, frozen Git identity, snapshot/inventory digests, explicit
+layout/providers, adapter versions and ownership records.
+
+Manifest origin retains original absolute path/base/digest and resolved source.
+A copied manifest is not a new resolution base. Local snapshot and backup paths live
+under .pipeline/snapshots and .pipeline/backups. Rebind detection is S4.
+
+Ownership is per file or JSON Pointer field; file/field and ancestor-field overlap
+are rejected. Original existing values require a local backup reference. Hashes and
+references are stored instead of secret-bearing before/after values. Backup protection,
+actual existence and field serialization are later I/O checks.
+
+Ready requires an active deployment and no pending operation. Not-installed requires
+neither. Needs-reconciliation requires a pending plan digest; drift requires an
+active deployment. Conflict and unsupported can describe a pre-installation
+diagnostic and do not require an active deployment. Pending work never implies a
+successful new deployment.
+
+## File plans, receipts and transitions
+
+A plan binds workspace, command, before-state digest, frozen source, desired deployment
+and ordered target operations. One target path appears once; field edits are combined
+into a containing-file replacement with whole-file before/desired guards.
+Create/replace/delete/edit-fields have explicit hash/null rules.
+
+validateOperation(plan, previous?) and validateReceiptForPlan(receipt, plan, previous?)
+require previous when beforeStateHash is non-null. The previous state must validate
+and match the plan workspace and digest. With a null beforeStateHash, previous must
+be omitted or null. validateTransition forwards its previous state to these guards.
+Target owners must be shared or belong to the union of previous.active.providers
+and desired.providers. This allows removal/restoration of a former provider while
+rejecting unrelated owners, without weakening source-state binding.
+Provider membership alone is not file-level write authority: S4/S5 still check exact
+ownership, permitted targets and observed bytes before any write.
+
+The current operation schema describes file operations only. Clone/move transaction
+records needed by init/adopt must be added and tested in S7 before those commands can
+be exposed; listing their names does not implement them.
+
+A receipt binds the canonical digest of that exact plan and every ordered target's
+ID and before/desired hashes. Status is completed, failed, uncertain or skipped.
+Completed requires desired readback; failed requires unchanged before-state. After
+the first non-completed operation, all following operations must be skipped.
+
+`contractDigest` sorts object keys, retains array order and hashes UTF-8 JSON with
+SHA-256. Use it only on validated JSON-domain data; it is not a general serializer.
+Source file digests use exact bytes instead.
+Numbers follow JSON serialization: -0 and 0 have the same canonical representation.
+This is intentional normalization, not distinct domain identities; current validated
+plan/state numeric fields do not depend on signed zero. String values remain distinct.
+
+`validateTransition` checks previous-state digest, workspace identity and full
+receipt coverage. Completion selects exactly the planned deployment; failure keeps
+the previous active deployment and records needs-reconciliation + pending digest.
+All installer transitions reset runtime to not-run. No document approval is touched.
+
+These are consistency guards, not proof of execution or user authorization. S4/S5
+must compute hashes from actual state, enforce approved preview and lock, execute
+guarded writes, verify readback and persist the journal. A fabricated consistent
+receipt is not runtime evidence.

package/docs/doctor.md

@@ -0,0 +1,165 @@
+# Read-only installation inspection (S6 development)
+
+The internal `inspectInstallation(workspace, {recoveryPath}?)` API is implemented.
+The public CLI exposes it read-only:
+
+`workspace-pipeline doctor --workspace <absolute-path> [--recovery <relative-record>] [--json]`
+
+Output is JSON even without --json. Exit 0 means configuration ready, 1 not ready
+or incomplete, 2 invalid invocation or output failure. This is not an install command.
+
+`ready` means observed **configuration readiness**, never a running harness,
+Unity/MCP connectivity, task approval, permission to update, or deletion authority.
+It does not write state: the on-disk historical status remains untouched.
+
+Checks use local state and the installed snapshot; the original Git source,
+workspace manifest and preparation directory need not still exist. No network
+lookup or new package execution occurs. Managed file hashes and JSON field values
+are checked; foreign siblings are not owned. Output does not include config values.
+
+The history inventory pairs journal/recovery directories by exact UUID, validates
+record chains and reports unfinished, malformed and orphan entries. A completed
+journal alone does not establish activation or valid backups. Doctor selects a
+completed transaction through the state's activation binding, then runs recovery
+validation. Legacy unanchored states use conservative desired-deployment matching;
+all such matches must pass. Selection is never by timestamp. Historical validation
+errors or incomplete history force transactionEvidence=fail even if the selected
+current transaction itself validates. An explicit path cannot hide invalid history.
+
+For completed transactions bound to the exact current deployment, doctor compares
+field-owned JSON by owned values rather than claiming ownership of foreign
+siblings or formatting. Both the historical desired bytes and current bytes must
+contain every owned value with its recorded hash. File-owned targets, malformed
+JSON and changed/missing owned values do not qualify. Projected paths are explicit
+in `fieldProjections`, bound to the exact recovery record. Historical receipts,
+hashes and current observed byte hashes are not rewritten.
+
+Ordinary `inspectRecovery` remains exact-byte validation. Doctor explicitly opts
+into `fieldOwnershipOnly`; its result declares `comparisonScope` and may report
+`desired-owned-fields` instead of byte equality. This exception is never available
+to pending/incomplete journals and does not grant continuation or cleanup authority.
+
+Completed continuation evidence may resolve an exact older unfinished entry.
+History retains the original status and hashes and adds `resolution: continued`
+plus exact `resolvedBy` recovery paths. A missing/corrupt approval, journal, source
+snapshot, backup or lineage prevents this resolution. Only the corresponding
+`history.unfinished` diagnostic is removed; unrelated problems stay visible.
+
+The `evidenceOnly` recovery inspection used here reports `completed-evidence`,
+not `applied`: activation and current targets remain `not-verified`. This makes
+historical linkage survive a later legitimate update without pretending old
+bytes are still current. Doctor separately validates the active transaction and
+current owned configuration. Resolved history remains protected from cleanup;
+an old unfinished journal is never rewritten as completed.
+
+For repeated interruptions, `resolvesChain` lists the exact validated ancestors;
+each ancestor keeps its own original status and hash. Validation is iterative,
+cycle-checked and capped at 32 continuation links. Invalid/missing earlier evidence
+prevents descendant resolution. All chain members remain cleanup-protected.
+
+State, targets and history are observed again to detect drift. A present lock,
+unknown or unfinished history, corrupt snapshot, mismatched workspace, invalid
+recovery or target drift prevents readiness. Runtime is always `not-run`.
+Historical transactions are not compared against today's target bytes as though
+each were the current installation.
+
+## Limits
+
+S7 repository operations have separate pending markers and bootstrap/recovery
+locks. Doctor reports their presence as `repository.pending`,
+`repository.bootstrap-pending`, `repository.recovery-pending`, or
+`repository.recovery-resume-pending`, with readiness
+false, without clearing or interpreting malformed records as success. This is a
+blocking observation, not full repository recovery verification.
+
+Ordinary mutating commands cannot acquire/use a workspace lock while these markers
+exist. Only the internal repository executor holding the real same-workspace
+bootstrap capability may proceed with its own operation. Lifecycle CLI previews
+also stop before source access. Read-only history listing remains available;
+this does not imply that the new S7 namespaces are already covered by retention.
+
+A recorded `not-installed` state with history requires matching completed removal
+evidence. An activation binding selects the exact committed operation; all retained
+completed history is still validated as historical evidence. Current removal
+results, history, state and lock status are verified.
+Successful absence is `status: not-installed`, `configuration: not-installed`,
+`ready: false`; it does not claim an installed or runnable pipeline. Missing,
+corrupt or unfinished evidence remains a reconciliation blocker. Original history
+is not deleted or changed by this check.
+
+New final states contain `activation` with relative recovery path, recovery hash
+and completed journal sequence/hash. The reference is saved in the same checked
+state write. Pending retains the prior reference. Doctor verifies that binding and
+historical predecessor references; selecting a different recovery is an error.
+Historical target bytes are not compared to today's configuration, but corrupt or
+unfinished evidence remains a blocker. Predecessor cycles are rejected.
+
+Old states without activation remain readable and conservative: all content-matching
+records are checked against current results. No reference is synthesized on read.
+The optional schemaVersion=1 field is backward-readable by the new CLI; older
+strict readers reject extended states rather than ignoring an unknown field.
+This is installation metadata, not a pipeline/document version requirement.
+
+- Read-only observations are not an atomic filesystem snapshot; hostile same-user
+  races are outside the guarantee. Run with configuration writers stopped.
+- History enumeration is bounded to 1000 entries per journal/transaction parent.
+  Exceeding the bound produces `history.limit`, not a partial healthy result.
+- All inventory entries remain protected from cleanup. Retention/dependency
+  eligibility and cleanup commands are separate S6 work.
+- Errors remain visible; doctor never repairs config, deletes evidence, clears
+  locks, renews approvals or silently selects an updated pipeline version.
+- A missing state is `not-installed` only when metadata is absent; residual
+  metadata with no valid state remains incomplete, not a clean installation.
+- Provider-specific discovery/global compatibility checks are later adapter work;
+  synthetic provider-double readiness is not live-provider certification.
+
+### Repository completion is not lock recovery
+
+The internal S7 completion verifier can confirm the exact approved repository
+result after its pending marker has moved into history. That result does not mean
+the workspace is unlocked or a pipeline is installed. If the process exited
+abruptly, both its sibling bootstrap lock and `.pipeline/lock` may remain.
+Read-only confirmation preserves them; ordinary operations remain blocked.
+Do not delete those directories to bypass recovery. The public stale-lock recovery
+route is not implemented yet. Tests distinguish an exception (which runs cleanup)
+from a child process exiting without running `finally`.
+
+Internal `recoverRepositoryLocks` now supports the paired stopped-owner locks
+around finalization, with explicit approval of the exact lock-reconciliation digest.
+It preserves both original lock directories under
+`.pipeline/repository-lock-recoveries/<digest>/`, together with the request and
+completion receipt. It does not replay repository effects or install a pipeline.
+If finalization was pending, that separate operation remains necessary. Any failure
+after recovery starts retains its sibling recovery gate; supported continuation
+is described below. This is not a public CLI command.
+
+Internal `inspectRepositoryLockRecovery` reconstructs interruptions after the
+recovery request is persisted: before any rename, after the workspace-lock rename,
+after both renames, and after receipt creation with the gate retained. It requires
+the original lock digest plus repository preview/reconciliation bindings and
+rechecks the repository result. Duplicate/missing lock locations, corrupted
+records and changed results are refused. This read-only report never authorizes
+resume or gate removal, including when a receipt is present. Interruptions before
+the request is persisted remain outside this route.
+
+Internal `finishRepositoryLockRecovery` supports all four recorded interruption
+states listed above. The recovery owner must be a stopped local process and
+the exact fresh observation must be explicitly approved. A sibling
+`.recovery-resume` guard excludes competing resumptions and ordinary operations.
+Only still-original lock directories are moved, in workspace/bootstrap order.
+A missing receipt is created once; an existing receipt is preserved. Subjects,
+owners, expected locations and records are rechecked between steps. The old gate
+is moved into the recovery archive, then the resumption guard and approval are
+also retained there. No repository effect is repeated. If this
+resumption is interrupted, its guard remains blocking; recursive recovery of that
+new interruption and failures before request persistence are not implemented yet.
+
+Internal `inspectRepositoryLockResumption` can read an interrupted or completed
+resumption without changing it. Supply the original lock digest and the exact
+approved recovery observation digest, together with the repository subjects.
+It distinguishes an active resumption, an archived old gate with a resumption
+still pending, and a fully archived resumption. It checks the approval/owner
+bindings and current repository result; duplicate locations and corrupt records
+are refused. A completed record is not permission to replay the operation.
+This check is for the same original subject before subsequent lifecycle changes;
+it does not project stale evidence over later finalization or repository edits.

package/docs/launch.md

@@ -0,0 +1,50 @@
+# Scoped Grok launch (S11 development)
+
+This command starts Grok from an already configured workspace with five Claude
+compatibility switches set to false in the child environment: skills, rules, agents,
+MCP and hooks. It does not install a pipeline. Configure Grok using the ordinary
+manifest-driven setup preview/apply first; do not manually construct state.
+
+Preview first (replace both absolute paths):
+
+```powershell
+workspace-pipeline launch grok --workspace "C:\Work\example" --executable "C:\Tools\grok.exe"
+```
+
+The default is read-only: it checks installation state and reports the intended
+launch without starting Grok. Add `--execute` to start an interactive session.
+An interactive terminal is required. For native diagnostic output, use
+`--inspect --execute`; this passes only `inspect --json` to the executable.
+Diagnostic success does not establish model-visible skills or task readiness.
+
+## Boundaries
+
+- Supply a trusted, absolute native executable path. Windows requires `.exe`;
+  `.cmd`/`.bat` wrappers are not accepted. No shell or automatic PATH lookup is used.
+- Arbitrary harness arguments are rejected. In particular, the command does not
+  forward working-directory, worktree, model, prompt or approval overrides.
+- The existing account/profile environment is inherited. Only the five Claude
+  pipeline compatibility variables are replaced; parent variables and global
+  configuration files are unchanged. Environment secrets are not printed.
+- Installation must be ready, include Grok and have no pending operation.
+  State is checked around inspection and again immediately before execution.
+- Close pipeline configuration editors/updaters during launch. These checks do
+  not hold a lock for the session or prevent subsequent concurrent edits.
+- This is not a sandbox or executable authenticity check. The selected program
+  runs with the user's permissions and can start configured MCP servers. Normal
+  workspace trust and action approvals remain the harness/user's responsibility.
+- Native plugins and generic skill discovery are not disabled. Removing Grok's
+  owned files alone does not prove it cannot discover another provider's skills.
+- Native 1.0.40 inspection verified disabled markers for Claude skills, rules and
+  ordinary MCP declarations. Claude agents, hooks and plugin MCP remained listed
+  without disabled markers. This does not prove execution, but complete runtime
+  suppression of those components is NOT_VERIFIED; five environment values are
+  not by themselves an isolation guarantee.
+- Root CLAUDE.md remained visible in the tested scoped session. Bundled delivery
+  uses it intentionally as a full shared entry with conditional provider sections.
+  Standalone legacy delivery retains the neutral AGENTS.md route.
+  This does not certify other import surfaces or
+  the full interactive TUI launch path.
+
+The child exit code is propagated (signals map to a nonzero exit). No pipeline
+stage, human acceptance or runtime certification is inferred from that code.