@6reduk/workspace-pipeline 0.1.0

package/docs/provider-bundles.md

@@ -0,0 +1,81 @@
+# Provider bundles (development)
+
+A bundle installs a declared set of native configurations together. It does not
+install the harnesses, log in, translate missing configurations or enable a
+native plugin. The initial bundle entry format supports Claude/Grok with a single
+full CLAUDE.md. The two harnesses keep separate skill, agent and MCP destinations.
+
+## Pipeline source
+
+Declare components under the existing `providers` map, then name the delivered
+set. Every listed member must have its own provider declaration:
+
+```yaml
+bundles:
+  claude-grok:
+    providers: [claude, grok]
+    entry:
+      source: instructions/CLAUDE.md
+      target: CLAUDE.md
+```
+
+Only Claude supplied? Use `[claude]`. Only Grok? Use `[grok]`. Both are valid.
+There is no full/partial flag: doctor shows the exact supplied/installed set.
+An absent provider is not configured merely because it can read CLAUDE.md.
+No second GROK.md is generated. The bundle entry is required in either case.
+
+The source entry is an inventory-bound UTF-8 workspace template. Existing
+`{{documentation}}` and `{{repository.name}}` substitutions refer to the wrapper
+layout. Its deployed Markdown links must be wrapper-relative, not source-folder
+relative. Unknown substitutions fail. Full rules and provider-specific sections
+are allowed; make those sections explicitly conditional on the current harness.
+Skills retain their existing canonical snapshot-relative routing.
+
+One bundle is supported initially because there is one allowed bundle entry
+destination. Nested bundles, arbitrary destinations and unknown native renderers
+are rejected. Source data cannot introduce executable CLI adapters. Composition
+changes among supported providers do not require new package-specific CLI code.
+
+## Workspace selection
+
+Select the bundle, not its individual members. For example, alongside Codex:
+
+```yaml
+providers: [codex]
+bundles: [claude-grok]
+```
+
+The ordinary Git source and layout/profile fields are still required. A workspace
+with only a bundle may omit `providers`. Setup/update use the usual saved preview
+and explicit apply; the preview includes all supplied members and the entry.
+It is not necessary to install both harness executables to configure the bundle.
+
+## Lifecycle
+
+- Update adds or retires members according to the new verified source, with exact
+  target changes visible before approval. User-modified owned files block writes.
+- Repair restores the installed snapshot and membership, not the latest source.
+- Remove the bundle together. Member-only removal is refused with
+  `remove.bundle-required`, rather than silently deleting the other harness.
+- Existing foreign files are not overwritten. Historical backups are retained
+  during a managed migration and restored when their owner is finally removed.
+- Old source manifests without bundles retain standalone behavior. To migrate,
+  explicitly select the source's bundle and approve the resulting update preview.
+
+Removal preview example (replace path/id):
+
+```powershell
+workspace-pipeline remove --workspace "C:\Work\example" --bundles claude-grok
+```
+
+Save the complete preview using the existing documented workflow, review it, then
+apply with `--apply --preview <absolute-file>`. Apply accepts no changed selectors.
+Preview files may contain private configuration bytes; keep them local.
+
+## Runtime is a separate check
+
+Grok's observed loading of root CLAUDE.md is intentionally accommodated. Use the
+[scoped launcher](launch.md) for the tested compatibility switches. Full native
+entry behavior and suppression of duplicate agents/hooks/plugin MCP are still
+not certified. Bundle installation is not a claim of full Claude compatibility,
+runtime readiness or approval of a pipeline stage.

package/docs/provider-resources.md

@@ -0,0 +1,37 @@
+# Shared entry and local resources (S8)
+
+The trusted shared adapter produces one wrapper `AGENTS.md` for all selected
+providers. It does not write into code/documentation repositories or global
+harness configuration. An existing foreign entry is still subject to normal
+ownership/conflict checks; choosing a template is not permission to overwrite it.
+
+`agentsDocument.mode: default` selects the small CLI entry. `mode: source` reads
+the specified file exclusively from the verified Git snapshot. The workspace
+selection overrides the pipeline default. The existing bounded substitutions
+`{{documentation}}` and `{{repository.ID}}` resolve to wrapper-relative paths;
+unknown substitutions fail. No expressions, includes or source code execute.
+
+Both modes append the resolved repository/documentation/project-root map and
+the installed resource location. Paths are relative to the wrapper. Pipeline
+resources stay at `.pipeline/snapshots/<digest>/<resources>` in the already
+verified local snapshot, not in a mutable global cache. A later source move or
+network outage does not change this location. The digest is installation metadata,
+not a workflow gate or a requirement to update project documentation versions.
+
+Trusted adapter contexts now carry `snapshot` alongside pipeline/workspace/layout
+and copied source bytes. Setup, locked preflight, switch and repair provide the
+same binding. Adapters must not treat an arbitrary source path as a filesystem
+grant. `sourceBytes`/`sourceText` have no filesystem fallback; resource routing
+checks the snapshot path against its digest.
+
+New deployments retain the resolved `agentsDocument` selection. Repair can thus
+reproduce a custom entry even if the workspace manifest is unavailable. The field
+is optional when reading earlier state; absent selection uses the package default,
+and repair's existing hash comparison still rejects mismatched reconstruction.
+Resources and old snapshots remain subject to the existing retention policy, not
+implicit deletion when an entry is removed.
+
+The public registry pairs this shared adapter with Codex/Claude renderers. Native
+discovery, packaged lifecycle and independent review are separate S8 checks.
+File/config checks do not certify model-visible instructions, trust,
+MCP execution or semantic approval.

package/docs/release.md

@@ -0,0 +1,25 @@
+# Release procedure
+
+This package is @6reduk/workspace-pipeline, separate from the legacy unity-sdd
+installer. Node.js 22+ is required. No native plugin installation is used.
+
+1. Review the exact public source, bump package.json and package-lock.json
+   together, run targeted tests and the packed provider lifecycle.
+2. Commit/push the approved source. Dispatch release.yml on main. It runs the
+   full test suite and packed provider lifecycle, then uploads a tarball.
+3. First publication requires the maintainer's normal npm authentication/2FA.
+   Download the successful workflow's artifact; publish that exact tarball:
+   `npm publish <tarball> --access public --provenance=false`.
+4. Once the package exists, configure npm trusted publishing for GitHub repository
+   6reduk/workspace-pipeline-cli, workflow release.yml, environment npm-release.
+   No npm token belongs in source. Set repository variable NPM_PUBLISH_ENABLED=true
+   only after trust is established. Subsequent explicit workflow dispatches can
+   publish through OIDC. Existing version bytes must match; never overwrite tags
+   or republish different bytes under the same version.
+5. Verify registry version/integrity against the uploaded tarball. A successful
+   build or uploaded artifact alone is not publication success.
+
+Release workflow does not move a workspace, grant trust or upgrade installed
+pipeline snapshots. Publish a pipeline's Git source separately, then use the
+ordinary reviewed setup/update preview for each workspace. Kimi native behavior
+remains deferred; scoped Grok launch and import-surface limits remain applicable.

package/docs/remove.md

@@ -0,0 +1,70 @@
+# Removal preview and apply
+
+The public CLI prepares removal without executing it:
+
+```text
+workspace-pipeline remove --workspace <absolute-wrapper> [--providers codex] [--bundles claude-grok]
+workspace-pipeline remove --workspace <absolute-wrapper> --apply --preview <absolute-json-file>
+```
+
+Use installed bundle IDs, not necessarily the example `claude-grok`. Save the
+preview privately, inspect it, then apply that exact preview without selectors.
+Omit both selectors to remove all installed providers and bundles. Explicit
+selection must be nonempty, unique and installed. A bundle member cannot be
+selected independently: `remove.bundle-required` requires selecting its bundle.
+The internal API is `prepareRemoval(workspace, registry, {providers, bundles})`.
+See [bundle delivery](provider-bundles.md) and [CLI lifecycle](lifecycle-cli.md).
+
+Shared AGENTS.md stays while any provider remains; shared CLAUDE.md stays while
+Claude or Grok remains. Full removal has desired=null;
+partial removal retains source/version/layout and the remaining ownership.
+
+The installed snapshot is replayed through trusted adapters. Every managed value
+must still match; missing or user-edited owned values block the whole preview.
+No original Git lookup or latest-version selection occurs.
+
+- Created owned files are proposed for deletion, never directories/repositories.
+- Taken-over files are restored to exact original backup bytes.
+- JSON fields are removed or restored individually; current foreign siblings stay.
+- JSON containers are kept, even if empty. No guessed directory/file cleanup.
+- Historical backup files and evidence are retained, not removal targets.
+
+State, managed observations, snapshot replay and used backups are rechecked.
+The envelope contains private before/output bytes and may contain secrets. Do not
+publish it as a diagnostic. applySupported=true refers only to the internal
+executor; fresh approval of the saved preview is required for public CLI apply.
+`verifyRemovalApproval(lock, prepared, approval, registry)` requires a fresh exact
+digest approval and a live lock, then reconstructs the whole preview from installed
+state. Changed targets, foreign siblings, retained-provider files, backups or
+prepared payload invalidate the preview. This is read-only preflight, not execution.
+
+## Internal execution
+
+`applyRemoval(lock, prepared, approval, registry)` repeats installed replay under
+the live lock. It preserves and verifies all original backup files, including
+those belonging to retained providers. Exact file unlink is allowed only for
+created managed files whose bytes still match immediately before deletion.
+Directories, repositories, history and backups are never deleted. Portable Node
+APIs cannot exclude hostile same-user races after the last filesystem check.
+
+A new journal and recovery record precede pending state and target writes. Full
+removal ends in `not-installed`, partial removal in `ready` with remaining/shared
+ownership. `inspectRecovery` checks either result and interrupted deletion without
+clearing pending state or inventing missing readbacks. Failures after unlink stay
+uncertain even when the file is absent. Original journal outcomes are retained.
+
+Internal continuation retains command remove and original backup/snapshot lineage.
+An already absent target becomes `verify-absent` (both hashes null, no payload or
+fields): a fresh readback, never a repeated unlink. Untouched files retain delete
+or restore work. A new exact approval and journal are required; original outcomes
+are preserved. Repeated interruptions use the bounded existing lineage mechanism.
+`verify-absent` is a validated continuation readback, not general target-deletion
+authority. It is also supported for the narrowly scoped retirement of an owned
+member file when updating a still-selected bundle; see [bundle delivery](provider-bundles.md).
+
+Doctor recognizes a
+completed removal with retained history only after validating matching removal
+evidence and current results; it reports not-installed, never ready. Public switch
+routing is described in [CLI lifecycle](lifecycle-cli.md). These operations do
+not certify live-provider behavior. An operational
+version tag never requires document reapproval.

package/docs/repair.md

@@ -0,0 +1,80 @@
+# Repair and reconciliation previews (S6 in progress)
+
+Internal APIs only. No public repair command yet.
+
+`inspectRepair(workspace, registry)` replays installed snapshot bytes through
+trusted adapters and checks that generated owned values match recorded hashes.
+Missing source Git/manifest does not trigger a fetch or latest-version lookup.
+Changed adapter output is rejected. Current user edits remain conflicts.
+
+`prepareRepairPreview(workspace, registry)` produces exact payloads for missing
+owned files/fields, preserving foreign JSON siblings. Any conflict blocks ALL
+targets in the preview. It does not silently take over changed files or approve
+itself. Outputs can contain configuration secrets from preserved siblings: keep
+this envelope local, never print it as diagnostic output or publish it.
+
+`previewReconciliation(workspace, exactRecoveryPath)` binds the current state and
+selected recovery/journal evidence. It preserves uncertain writes even where
+current bytes equal desired bytes. It does not replay, roll back, clear pending
+state or release an abandoned lock.
+
+Inspection/preview results have applySupported=false, automaticActions=false,
+runtime=not-run and require fresh approval. They are not executable envelopes.
+
+`prepareRepairPlan(workspace, registry)` binds a native operation with command
+`repair` to the exact current state, all owned dependencies and missing-target
+payloads. Its `prepared-repair` envelope preserves the entire active deployment,
+including version, identity, ownership and original backup lineage. It rejects
+conflicts; it does not select a new source/version or manufacture an approval.
+Absent JSON files use create with no field-edit operations; existing JSON files
+use edit-fields with exact absent-field preconditions and preserved siblings.
+
+`verifyRepairApproval(lock, prepared, approval, registry)` is read-only preflight:
+it requires the fresh exact digest approval, verifies a live workspace lock and
+rebuilds the complete plan from installed bytes. Changed state, payloads, foreign
+siblings, unchanged managed dependencies or adapter output invalidate the plan.
+
+`prepared-repair` now has applySupported=true for the internal `applyRepair`
+entrypoint only; setup/update apply still rejects it. `applyRepair` replays under
+lock, verifies existing backup lineage, and uses the shared journal/write/readback
+transaction engine. It rechecks the fresh plan after recovery metadata is staged
+and before pending state or provider targets are written. No Git source is needed.
+
+`inspectRecovery` understands repair records, requires an unchanged deployment
+and preserves uncertainty after interruption. This is inspection, not automatic
+retry/rollback. Internal continuation execution is described below; public CLI
+routing remains unimplemented. Doctor checks all matching records and explicitly distinguishes
+owned JSON fields from foreign siblings in completed historical transactions;
+exact-byte recovery inspection remains the default. Full regression still needs
+checking before S6 completion. All envelopes with bytes remain private and potentially
+secret-bearing.
+
+`prepareContinuation(workspace, recoveryPath)` creates a separate
+proposal for an exact pending transaction. It binds state, recovery bytes and the
+journal head (sequence/hash). Desired targets require new `verify-readback` actions;
+untouched targets get `write-desired` actions. Other bytes or invalid evidence
+block the whole proposal. Unchanged dependencies and exact stored output bytes
+are included. No old outcome is rewritten or presumed successful.
+
+`verifyContinuationApproval` reobserves the proposal under a live caller-owned
+lock and requires its fresh digest approval. Changes to journal head, state,
+targets or payload invalidate it.
+
+Internal `applyContinuation` executes that exact approval in a NEW transaction.
+Already-desired targets receive a new journaled readback without file writes;
+remaining writes use immediate before-hash checks. Existing backups are verified,
+not replaced. Before activation, original recovery bytes/journal head and the
+exact original target/payload/dependency relationship are rechecked. Historical
+uncertainty is never rewritten as a successful original outcome.
+
+Doctor/history validate completed continuation evidence and mark the exact old
+entry as resolved by that continuation, preserving its original status and bytes.
+Historical completion is distinct from activation/current configuration readiness.
+Nested continuation (continuing a failed continuation) verifies the complete
+ancestry iteratively, preserving every ancestor's bytes and approval. Repeated
+paths are rejected as cycles. The maximum is 32 continuation links; preparing
+another beyond that bound fails before execution and retains pending evidence.
+History resolves all verified ancestors only through completed descendant evidence.
+Public CLI routing,
+compensation and abandoned-lock removal are not implemented. This is an internal
+executor with applySupported=true, not a complete user-facing recovery workflow.

package/docs/repositories.md

@@ -0,0 +1,209 @@
+# Repository workspace commands
+
+These commands prepare repository layout only. They do not install a pipeline,
+start an LLM harness or MCP server, approve project trust, or modify Git remotes.
+Provider configuration requires a separate `setup` plan. `wrap` is an alias for
+`adopt`, not a destructive in-place conversion command.
+
+## Inputs and preview
+
+Use absolute paths for command-line paths. A workspace manifest selects the Git
+pipeline source, provider names, repository destinations and documentation owner.
+See [contracts](contracts.md) for the manifest contract and [source](source.md)
+for source acquisition. A separate JSON file makes each repository action explicit:
+
+```json
+{"game":{"action":"move","from":"C:\\Projects\\ExistingGame"}}
+```
+
+The key must match the manifest repository ID. Supported actions are `keep`,
+`directory`, `init`, `clone`, and `move`; their validity depends on the observed
+source/destination and manifest. `directory` creates an empty directory, not a
+Git repository. `move` preserves the existing repository, including dirty and
+untracked files, and does not change origin. Clone materializes the selected
+commit, not uncommitted files of its source.
+
+```powershell
+workspace-pipeline wrap --workspace "C:\Work\GameWorkspace" --manifest "C:\Work\workspace.json" --choices "C:\Work\choices.json"
+```
+
+Save the exact JSON stdout as UTF-8 `preview.json` outside the affected repository
+and wrapper. Read its operations and blockers. Preview may acquire a temporary
+Git snapshot, but does not perform repository effects. Remote access is explicit
+with `--network`; local Git does not need that flag. Do not put credentials into
+source URLs or retained preview files.
+
+```powershell
+workspace-pipeline wrap --workspace "C:\Work\GameWorkspace" --apply --preview "C:\Work\preview.json"
+```
+
+Apply accepts only the saved preview, not fresh choices or a different manifest.
+It rechecks exact inputs and observed filesystem state. A destination collision,
+source drift or missing required prepared snapshot causes refusal, not overwrite.
+Apply still resolves the manifest's source identity: an unavailable local Git
+pipeline source is refused, even when its acquired snapshot is retained. Restore
+that source before retrying. Recovery after recorded repository effects instead
+uses retained operation inputs, independently of that source and user preview.
+Repository clone inputs have their own retained bindings.
+
+`init` uses the same preview/apply shape for a new layout; `adopt` for an existing
+one. Inspect `--help` for the installed command surface. Do not treat successful
+repository setup as proof that a provider is configured or usable.
+
+## Interruptions and recovery
+
+Do not delete lock directories or replay the original apply blindly. Stdout and
+stderr identify operation/journal paths. Retained inputs under
+`.pipeline/repository-inputs/` let recovery work without the original user preview
+or pipeline source. Preserve these records until recovery and retention checks.
+
+```powershell
+workspace-pipeline repositories status --workspace "C:\Work\GameWorkspace"
+workspace-pipeline repositories finalize --workspace "C:\Work\GameWorkspace"
+workspace-pipeline repositories finalize --workspace "C:\Work\GameWorkspace" --apply --preview "C:\Work\finalize-preview.json"
+```
+
+Each mutation requires its own current preview. `status` is read-only;
+`no-pending-marker` means no pending marker, not comprehensive workspace health.
+Uncertain effects are not silently turned into completed ones. Follow the exact
+diagnostics and [recovery contract](repository-recovery.md).
+
+If a stopped process retained operation locks, use the explicit journal UUID from
+the operation record, never guess the newest directory:
+
+```powershell
+workspace-pipeline repositories recover-locks --workspace "C:\Work\GameWorkspace" --journal "<UUID>"
+workspace-pipeline repositories recover-locks --workspace "C:\Work\GameWorkspace" --journal "<UUID>" --apply --preview "C:\Work\locks-preview.json"
+```
+
+This can retire attributable locks only after verifying owners, effects and
+history. It does not authorize replaying uncertain operations. Bootstrap has
+separate `recover-bootstrap`, `continue-bootstrap` and `retire-bootstrap` routes; use only a supported,
+verified native preview. Live or unconfirmed owners, torn records and foreign
+files must not be removed to force progress.
+
+For the **first** recovery of wrapper creation, retain the original complete
+`init`/`adopt` preview (or the native repository preview). This route needs no
+pipeline-source access. It supports either a still-absent wrapper with its exact
+intent, or an existing wrapper with a matching creation receipt; the recorded
+local owner must have stopped. It archives the attributable bootstrap attempt,
+not a replay of repository operations.
+
+```powershell
+workspace-pipeline repositories recover-bootstrap --workspace "C:\Work\GameWorkspace" --bootstrap-preview "C:\Work\original-init-preview.json"
+workspace-pipeline repositories recover-bootstrap --workspace "C:\Work\GameWorkspace" --apply --preview "C:\Work\fresh-bootstrap-recovery.json"
+```
+
+Save the first command's full output as the fresh recovery preview for the second
+command. The original bootstrap preview and fresh recovery approval are different
+files. A stale preview is rejected. If this recovery itself is interrupted, use
+`continue-bootstrap` against its retained request instead. Missing/torn original
+records or a wrapper without a matching receipt remain blocked; do not fabricate
+the original preview or clear a lock to proceed.
+
+## Missing parents and abandoning an uncertain attempt
+
+Missing wrapper ancestors have a separate bounded plan. It creates approved
+parents only, not the wrapper or repositories. Afterward prepare a fresh
+`init`/`adopt` preview against the new filesystem state.
+
+```powershell
+workspace-pipeline repositories prepare-parent --workspace "C:\Work\New\GameWorkspace"
+workspace-pipeline repositories prepare-parent --workspace "C:\Work\New\GameWorkspace" --apply --preview "C:\Work\parent-preview.json"
+```
+
+After interruption, preserve the original parent preview. Continuation preview
+reads it with `--parent-preview`; apply takes the newly saved continuation envelope
+with `--preview`. These files are different approvals and cannot be interchanged.
+
+```powershell
+workspace-pipeline repositories continue-parent --workspace "C:\Work\New\GameWorkspace" --parent-preview "C:\Work\parent-preview.json"
+workspace-pipeline repositories continue-parent --workspace "C:\Work\New\GameWorkspace" --apply --preview "C:\Work\parent-continuation.json"
+```
+
+### Nested repository destinations
+
+Paths such as `repos/api` and `repos/documentation` remain valid manifest paths.
+One-shot `init` deliberately refuses missing destination parents; it does not
+silently widen repository approval into recursive directory creation. Use the
+existing bounded parent-preparation route, then obtain a **fresh** `init` preview.
+
+For a new `C:\Work\Services` wrapper, the following parent preview has
+`C:\Work\Services\repos\api` as its **sentinel**, not as the actual pipeline
+workspace. It proposes creating only the missing chain `Services`, `Services\repos`;
+neither `api` nor `documentation` is created by this command. Review the returned
+`targets`, `anchor`, and history location before saving and applying its JSON.
+
+```powershell
+workspace-pipeline repositories prepare-parent --workspace "C:\Work\Services\repos\api"
+workspace-pipeline repositories prepare-parent --workspace "C:\Work\Services\repos\api" --apply --preview "C:\Work\nested-parent-preview.json"
+workspace-pipeline init --workspace "C:\Work\Services" --manifest "C:\Work\workspace.json" --choices "C:\Work\choices.json"
+```
+
+Save the last command's new complete preview and apply it to `C:\Work\Services`
+through the normal `init --apply --preview` route. Do not reuse an `init` preview
+from before parent creation. Both sibling repositories can now be created by the
+same repository plan. For separate missing branches, prepare each required chain
+explicitly and inspect it separately. The manifest/schema/examples are unchanged.
+
+This route also works for an **existing quiescent wrapper**: the parent preview
+creates only missing descendants. Stop canonical-workspace CLI writers and agent
+sessions first. The parent primitive's lease covers its first missing path, **not
+the canonical workspace's writer locks**; it does not certify isolation against
+an active `init`, provider mutation, or arbitrary editor in that workspace. Do
+not run these operations concurrently. This is an explicit preparation route,
+not an automatically guarded one-shot nested bootstrap.
+
+Directory staging records exact per-directory identities before publication and
+retains a projection and receipt. If interrupted, use `continue-parent` with the
+same sentinel and original parent preview, then approve its fresh continuation.
+Unknown/incomplete staging stays blocked for manual review; no blind `mkdir`,
+recursive rollback, or automatic deletion is required or authorized. History
+may live at an existing ancestor inside the eventual wrapper; preserve it.
+
+If repository effects remain uncertain, explicit abandonment can retain the
+failed attempt as history without certifying completion. It preserves partial
+repository data; it is not rollback, cleanup, permission to delete data, or a
+claim the original operation succeeded. Inspect the entire fresh observation
+before applying, then reassess the preserved repositories in a new plan.
+
+```powershell
+workspace-pipeline repositories abandon --workspace "C:\Work\GameWorkspace"
+workspace-pipeline repositories abandon --workspace "C:\Work\GameWorkspace" --apply --preview "C:\Work\abandon-preview.json"
+workspace-pipeline repositories continue-abandon --workspace "C:\Work\GameWorkspace" --attempt "<attempt UUID>"
+workspace-pipeline repositories continue-abandon --workspace "C:\Work\GameWorkspace" --attempt "<attempt UUID>" --apply --preview "C:\Work\abandon-continuation.json"
+```
+
+The attempt UUID must come from the actual abandonment record. Unknown owners,
+changed subjects or unverifiable history still block these commands.
+
+## Corrected control records and recovery boundaries
+
+Full file observations and compact saved records are described in
+[repository observations](repository-observations.md). Separate user-repository
+clone ceilings are listed in [transport budgets](repository-transport-budgets.md),
+including their preview-visible pack/time limits; pipeline-package limits do not
+serve as implicit game-repository limits.
+
+Successful layout work reports `repositories-prepared` with
+`pipelineActivated:false`; it is not harness or game readiness.
+Abandonment refuses a finalizable completed operation: use the exact finalization
+route instead. Interrupted abandonment approvals are retained sequentially as
+`authorization-NNNN.json`, each bound to previous authorization hashes. Earlier
+development histories using UUID approval names are not rewritten or silently
+accepted under the new format; preserve them for manual inspection.
+First lock recovery now archives the whole gate as `recovery-gate` in its history,
+including the owner record, instead of deleting the gate in separate steps.
+
+## Packed regression details
+
+`npm run test:packed` packs and installs the npm tarball offline into a unique
+temporary directory. It verifies packaged files, runs the installed entrypoint,
+and retains `report.json` plus fixtures at the printed location. The S7 portion
+covers init, dirty/untracked wrap, destination collision, unavailable-source apply
+refusal, source-independent finalization, uncertain-effect refusal and stopped-lock recovery.
+
+Crash setup uses real exited children and native APIs **from the installed
+tarball**, not a hidden public CLI fault flag; recovery uses the public installed
+entrypoint. These are synthetic author tests, not independent review, real
+provider/runtime validation or permission to migrate a user's workspace.

package/docs/repository-manual-recovery.md

@@ -0,0 +1,102 @@
+# Repository recovery when ownership or evidence is incomplete
+
+This is the operator path for states that cannot safely enter a native recovery
+writer. An error or an empty lock directory is not evidence that nobody owns the
+operation. A missing result record is not evidence that a clone/move did not run.
+Nothing in this document authorizes deleting a lock, editing a journal, inventing
+an owner record, overwriting a repository, or converting an unknown result to PASS.
+
+## First: preserve and classify, without applying anything
+
+1. Record the exact absolute wrapper and the CLI error code. Keep the original
+   preview, operation UUID, reported journal/history locations and console output.
+   Do not select an operation by newest timestamp. These records may contain
+   private configuration: keep diagnostic copies local and access-restricted.
+2. Ask the people/process owners using that workspace to stop relevant installer,
+   recovery and repository-writing work through their normal controls. Do not
+   kill a PID merely because it appears in an old record: PIDs are reused. A
+   foreign hostname or inability to inspect a process leaves liveness unknown.
+3. Use the following read-only commands. A nonzero exit/error is useful evidence;
+   it does not mean the command repaired anything. Do not append `--apply`.
+
+   ```text
+   workspace-pipeline repositories status --workspace <absolute-wrapper>
+   workspace-pipeline logs list --workspace <absolute-wrapper>
+   ```
+
+   `repositories status` reads a pending operation and its retained inputs when
+   available; it reports persistent blockers. `no-pending-marker` does **not**
+   certify historical completion or absence of effects. `logs list` may report
+   inaccessible/incomplete records rather than parse them. Neither command repairs
+   missing records, retires locks or establishes unknown process ownership.
+4. Preserve original bytes in place. If an operator makes a diagnostic copy,
+   record source paths and hashes, distinguish a copy from the original, and do
+   not follow unknown links/reparse points. An inconsistent or changing copy is
+   not a stable before-state. Do not publish credentials or whole user configs.
+5. Compare with the cases below and select a matching preview-only route. A route
+   that rejects the state must not be bypassed by editing the record it rejected.
+
+## Cases and actual native boundaries
+
+| Observed state | Supported next observation/action | Boundary |
+| --- | --- | --- |
+| Completed repository effects with intact retained input/journal and no ownership blocker | `repositories finalize --workspace <wrapper>` previews exact finalization | Its approved apply only records verified completion; it does not repeat clone/init/move |
+| Completed evidenced effects but stopped, attributable locks remain | `repositories recover-locks --workspace <wrapper> --journal <uuid>` | Preview/apply checks exact journal, owner and effects; live/unknown owners remain blocked |
+| Wrapper absent; bootstrap lock contains only a complete valid local owner record | `repositories retire-bootstrap --workspace <wrapper>` | Eligible only when that local owner is confirmed stopped; archives the lock, never certifies execution |
+| Original bootstrap preview is intact; exact intent with absent wrapper, or matching wrapper creation receipt | `repositories recover-bootstrap --workspace <wrapper> --bootstrap-preview <original-preview.json>` | First recovery only, with a confirmed stopped local owner; creates a fresh recovery preview without source lookup or repository replay |
+| Bootstrap recovery gate has a complete retained request and coherent original records | `repositories continue-bootstrap --workspace <wrapper>` | Continues only remaining attributable archival/receipt actions; fresh exact preview approval is required |
+| Interrupted repeated paired-lock continuation with intact approval chain | `repositories recover-locks` for the same explicit journal | Requires a fresh observed-state preview; does not reuse an old approval as ownership |
+| Pending repository operation with intact inputs, unchanged inventoried trees and attributable stopped locks, but effects not finalizable | `repositories abandon --workspace <wrapper>` | Explicitly preserves current source/destination trees and abandons the operation; does not call partial effects completed or undo them. New repository preview is required |
+| Interrupted abandon with intact retained request and guard | `repositories continue-abandon --workspace <wrapper> --attempt <uuid>` | Preview binds the named attempt; apply does not infer a different attempt |
+| Parent staging has a complete projection or was published before its receipt | `repositories continue-parent --workspace <wrapper> --parent-preview <original-preview.json>` | Fresh preview may finish the exact projection; foreign additions or identity drift reject continuation |
+| Parent staging stopped before a complete projection, with no live-path publication | Preserve that attempt; a fresh `repositories prepare-parent` preview can choose a new staging history | The earlier staging remains untouched. This does not adopt unknown directories or delete remnants |
+| Empty bootstrap lock; torn/invalid owner; wrong host or owner liveness unknown | Manual decision required; native owner retirement refuses | An empty record cannot prove a dead owner, even if no process is visible to this shell |
+| Recovery gate without a complete request; torn continuation authorization; corrupted input/receipt | Manual decision required; native readers refuse missing/inconsistent bindings | Do not fill gaps using similar neighboring files or remembered chat text |
+| Wrapper exists but there is no matching creation receipt, or clone/move effects conflict with retained evidence | Manual decision, or explicit abandon only if its independent eligibility checks pass | Compatible-looking files alone do not prove origin or successful completion |
+
+For each eligible route, save its full preview privately as UTF-8, inspect the
+exact operations and blockers, then separately approve the corresponding
+`--apply --preview <file>` command. See [native recovery](repository-recovery.md).
+Parent continuation retains each fresh approval as `authorization-NNNN.json`
+inside its history before remaining actions. Each record binds the exact observed
+state and preceding approval hashes; the chain admits at most 64 approvals.
+A torn authorization is not rewritten. A completed readback appends nothing.
+No route proves that unrelated harness sessions, Unity, Git helpers or other
+machines have stopped. Local IPC exclusion is cooperative and not a distributed
+or hostile-process safety boundary.
+
+## What an operator decision must establish
+
+A manual decision is a bounded escalation, not a hidden retry loop. Provide:
+
+- Exact affected wrapper, source/destination repositories, journal/attempt ID and
+  observed files; identities/hashes where the current observation supports them.
+- Who established quiescence, on which host, and which process identities were
+  actually checked. Unknown ownership stays explicitly unknown.
+- Original preview and independently retained request/receipt/backup, if they
+  exist. Identify their source and hashes. A user-supplied copy is evidence to
+  evaluate, not permission to replace a missing native record or proof of a
+  historical result. Human recollection can guide investigation, not manufacture
+  machine provenance.
+- Intended disposition: preserve the present repositories and start a new plan,
+  or a specific separately reviewed reconciliation/compensation. Enumerate exact
+  paths and preservation requirements. No broad cleanup or implicit origin change.
+- Remaining uncertainty and how the proposed action avoids touching files whose
+  ownership or before-state cannot be established.
+
+There is intentionally no force/unlock recipe here. If native prerequisites cannot
+be established, stop and review the exact situation with the workspace owner; an
+explicit separately designed recovery may be necessary. A diagnostic report can
+close the investigation step while the operation itself remains unresolved. Do
+not represent that as successful recovery, installation readiness or S7 runtime
+certification.
+
+## Why this is consistent with the execution contract
+
+The execution contract requires reinspection, a fresh preview before continuing or
+compensating, ownership-aware compensation, and owner/liveness review for abandoned
+locks. It explicitly forbids blind deletion and recursive repository rollback.
+It does not require the CLI to reconstruct absent proof or automatically repair
+every corrupted record. Partial moves still need a documented disposition:
+supported preserve-current-state abandonment is one such route when its bindings
+remain intact; genuinely unbound cases retain an explicit operator decision.

package/docs/repository-observations.md

@@ -0,0 +1,29 @@
+# Repository observations and control-record size
+
+Repository files (including ignored and untracked data) are fully inspected under
+the repository bounds: 200000 entries, 100 GiB content and depth128. Full entry
+lists are transient observations, not embedded into saved command previews or
+per-operation evidence. The shared JSON/YAML control parser retains its 2 MiB and
+50000-node limits; these are not user-repository file limits.
+
+Saved inventory summaries contain root identity, entry count, byte total, exact
+identity-inventory digest and a separate rename-stable content/mode digest.
+Committed-tree summaries contain commit, entry count, total bytes and tree digest.
+Apply still rebuilds the whole observation from original trusted inputs and
+compares the complete compact preview. After effects, native evidence records the
+new exact summary; reconciliation rescans current trees and compares it. A digest
+alone is neither an execution receipt nor authority to replay missing work.
+
+Historical full-entry evidence remains readable for reconciliation/retention where
+it fits the original parser bounds. Saved previews from the earlier development
+format are not silently rewritten; take a fresh preview before a new operation.
+Interrupted records that cannot be verified remain manual recovery cases.
+
+Filesystem identity uses mtime/ctime, not atime. Concurrent changes may refuse a
+preview even when an operator considers the content equivalent. Do not suppress
+drift checks to force apply; stop writers and obtain a fresh observation.
+
+Busy/access diagnostics are deliberately distinct: EBUSY is busy, EACCES/EPERM is
+access-denied (permissions or sharing policy may be responsible). A read-only
+preflight cannot guarantee that a later rename/open will be permitted. Such an
+apply failure preserves pending uncertainty and never claims automatic rollback.