owlrunkit 0.18.2 → 0.18.4

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 0.18.4
+
+- Adds controller-owned `project target-snapshot --dry-run|--apply` for binding
+  an immutable target HEAD, visible dirty overlay, WorkItem path boundary, and
+  full workspace fingerprint without writing the frozen target worktree.
+- Adds `project import-delivery --dry-run|--apply` for verifying an external
+  DeliveryPacket against that target and recording exact candidate identity in
+  Project Driver through append-only Event V3.
+- Distinguishes an attested entry-to-candidate overlay from `candidate_only`
+  intake when no entry snapshot exists, so current candidate verification is
+  never overstated as historical delta proof.
+- Classifies visible tool-cache and dependency-environment changes separately
+  while rejecting packet paths outside WorkItem ownership and any unclassified
+  source delta before project truth is written.
+- Documents project-local `npx --no-install owlrunkit` as the normal command
+  surface and treats an older global CLI or process-level Skill as version
+  drift, not as authority to reinterpret a newer project.
+- Makes `profiles detect --dry-run` return the V3 contract with real visible
+  changed paths, `profiles_insufficient` when source coverage is incomplete,
+  a minimal suggested profile, and copyable preview/apply repair commands.
+- Emits Status/Takeover V2 and extends takeover with stale-handoff reasons plus
+  the current external delivery and exact per-file delta from its predecessor,
+  while retaining the one-screen human projection.
+- Emits Assurance Route V2 and Usage Mode Recommendation V2 with project-local
+  commands. The published Profile Detection V2, Status/Takeover V1, Assurance
+  Route V1, and Usage Mode Recommendation V1 contracts remain unchanged for
+  existing consumers.
+- Adds action-specific `project assign --help` and makes `quick-metrics`
+  local-by-default without requiring `--local`; the old flag remains an
+  accepted compatibility no-op.
+- Requires disjoint controller and target workspaces, binds only an exact Git
+  worktree root, brackets DeliveryPacket verification with stable target
+  snapshots, and rejects base-identity drift plus both sides of any
+  cross-boundary rename.
+- Reserves Event V3 for verified `import-delivery` intake so legacy raw request
+  actions cannot inject external-delivery truth without checking target bytes.
+- Revalidates Git-visible changed paths between profile detection and apply;
+  Git-status failure and rename-source coverage now fail closed instead of
+  appearing as a high-confidence empty candidate.
+- Keeps target writes and every Git, release, deployment, production, UX, and
+  business authorization flag false.
+
+## 0.18.3
+
+- Adds `quick-verify --stdin-file <file>` so a local or remote verification
+  script can be copied into the receipt store, hash-bound, and supplied as
+  exact stdin without embedding its bytes in argv.
+- Returns bounded opening and closing Quick output lines while preserving the
+  complete stdout/stderr artifacts for later inspection.
+- Stops emitting the fixed `quick_ignored_artifact_unbound` noise on new Quick
+  receipts and omits it from attestation issue output for historical receipts.
+- Adds `quick-verify --attest` as one high-level command while preserving the
+  Quick receipt and attestation as separate evidence objects.
+- Adds action-specific `quick-metrics --help`; aggregate counts are now the
+  default output and receipt paths require `--verbose`.
+- Adds atomic `project reject-and-return` for a current failed checkpoint. It
+  preserves the failed attempt, records reviewer evidence, opens an assigned
+  rework attempt, and keeps every authority flag false.
+- Introduces `OwlCodaRunKitTeamProjectEventV2` for the new rework event instead
+  of changing the existing Event V1 contract in place.
+- Packages the Contract v0.1 and v0.2 references beside the bundled Codex Skill
+  so its relative links work before and after managed Skill installation.
+
 ## 0.18.2
 
 - Makes `project checkpoint --help` action-specific and returns a complete,

package/README.md

@@ -15,6 +15,28 @@ RunKit 0.18.2 is a focused dogfood patch for clearer CLI help, actionable
 checkpoint and canonical-path errors, bounded Quick output summaries, typed
 registry diagnostics, and explicit profile normalization previews.
 
+RunKit 0.18.3 turns the next Sierac recovery dogfood findings into a smaller
+Quick surface: hash-bound stdin scripts, bounded opening and closing summaries,
+actionable-only receipt issues, optional one-command attestation, and concise
+metrics by default. It also adds one atomic failed-work return path and makes
+the bundled Skill's contract references self-contained.
+
+RunKit 0.18.4 lets one controller project bind a separate frozen target
+worktree without installing dependencies or `.owlcoda` into that target. It
+captures an immutable entry snapshot, verifies an external DeliveryPacket,
+classifies visible dirty-overlay changes, and imports the candidate identity
+into Project Driver. Missing entry truth is reported as `candidate_only`, not
+as an attested delta. Tool-cache and dependency-environment changes are
+disclosed separately; unclassified source changes fail closed. The release
+also makes project-local `npx --no-install owlrunkit` the documented command
+surface so an older global binary cannot reinterpret newer project truth.
+Profile detection now exposes real uncovered source paths and copyable repair
+commands instead of reporting a non-actionable success. Takeover reports stale
+handoffs and the exact current-versus-previous external candidate delta.
+These additions use Profile Detection V3, Status/Takeover V2, Assurance Route
+V2, and Usage Mode Recommendation V2; the published predecessor contracts
+remain unchanged.
+
 The 0.18 Project Driver is a bounded surface for new projects and controlled
 dogfood. Its product name does not claim to be a general long-running,
 multi-phase, or enterprise control plane. Version 0.18 adds one bounded
@@ -29,10 +51,11 @@ separate authority boundaries.
 ## Install
 
 ```bash
-npm install --save-exact owlrunkit@0.18.2
+npm install --save-exact owlrunkit@0.18.4
 ```
 
-The `owlrunkit` bootstrap uses the project's exact locally bound CLI for
+Use `npx --no-install owlrunkit` for project commands. The package bootstrap
+uses the project's exact locally bound CLI for
 ordinary project commands. The installed current package remains responsible
 for bootstrap operations such as initialization, adoption, and Core successor
 migration, so a global CLI does not reinterpret an older project's control
@@ -42,11 +65,11 @@ the current bootstrap Core or its embedded prior-release identity catalog, and
 the project Config must independently bind the same Core.
 
 ```bash
-owlrunkit --version
-owlrunkit init --workspace /absolute/path/to/project
-owlrunkit doctor --workspace /absolute/path/to/project
-owlrunkit mode recommend --workspace /absolute/path/to/project
-owlrunkit mode status --workspace /absolute/path/to/project
+npx --no-install owlrunkit --version
+npx --no-install owlrunkit init --workspace /absolute/path/to/project
+npx --no-install owlrunkit doctor --workspace /absolute/path/to/project
+npx --no-install owlrunkit mode recommend --workspace /absolute/path/to/project
+npx --no-install owlrunkit mode status --workspace /absolute/path/to/project
 ```
 
 `mode recommend` is read-only and defaults to human output; add `--json` for a
@@ -58,56 +81,64 @@ grant Git, release, deployment, production, or business authority.
 
 RunKit 0.18 keeps the project alive independently of any one Agent or chat.
 Initialize a definition, then use typed direct commands for the normal
-assignment, checkpoint, handoff, decision, integration, status, and takeover
-flow:
+assignment, checkpoint, handoff, failed-work return, decision, integration,
+status, and takeover flow:
 
 ```bash
 cp node_modules/owlrunkit/scripts/runkit-contract/templates/team-project-definition.json ./project-definition.json
-owlrunkit project init --workspace . \
+npx --no-install owlrunkit project init --workspace . \
   --definition ./project-definition.json
-owlrunkit project assign --workspace . --assignment-id assign-1 \
+npx --no-install owlrunkit project assign --workspace . --assignment-id assign-1 \
   --at 2026-08-09T00:00:00.000Z --work-item work-item-1 --agent agent-runtime
-owlrunkit project checkpoint --workspace . --checkpoint-id checkpoint-1 \
+npx --no-install owlrunkit project checkpoint --workspace . --checkpoint-id checkpoint-1 \
   --at 2026-08-09T00:05:00.000Z --assignment-id assign-1 --work-item work-item-1 \
   --state active --summary 'Implement the bounded work item' \
   --completed-units 0 \
   --next 'Run the focused verification'
-owlrunkit project handoff --workspace . --handoff-id handoff-1 \
+npx --no-install owlrunkit project handoff --workspace . --handoff-id handoff-1 \
   --at 2026-08-09T00:10:00.000Z --assignment-id assign-1 --work-item work-item-1 \
   --from-agent agent-runtime --to-agent agent-successor \
   --summary 'Source work is ready for continuation' --next 'Run verification' \
   --evidence evidence/source.txt
-owlrunkit project assign --workspace . --assignment-id assign-2 \
+# If review instead rejects a failed checkpoint, preserve it and open rework
+# without first mutating the WorkItem back to active:
+npx --no-install owlrunkit project reject-and-return --workspace . --rework-id review-1 \
+  --at 2026-08-09T00:10:30.000Z --work-item work-item-1 \
+  --reviewer-agent agent-control --to-agent agent-runtime \
+  --reason 'The candidate violates its versioned contract' \
+  --next 'Repair the contract and rerun the focused check' \
+  --evidence evidence/rejected-review.txt
+npx --no-install owlrunkit project assign --workspace . --assignment-id assign-2 \
   --at 2026-08-09T00:11:00.000Z --work-item work-item-1 \
   --agent agent-successor --supersedes assign-1
-owlrunkit project decision --workspace . --open --decision-id decision-1 \
+npx --no-install owlrunkit project decision --workspace . --open --decision-id decision-1 \
   --at 2026-08-09T00:12:00.000Z --title 'Choose the accepted source path' \
   --question 'Which source path should continue?' --owner-agent agent-successor \
   --blocking-work-item work-item-1 --option accepted --option rejected
-owlrunkit project decision --workspace . --resolve --decision-id decision-1 \
+npx --no-install owlrunkit project decision --workspace . --resolve --decision-id decision-1 \
   --at 2026-08-09T00:13:00.000Z --resolution 'Use the accepted source path' \
   --rationale 'It preserves the project contract' --evidence evidence/decision.txt
-owlrunkit project checkpoint --workspace . --checkpoint-id checkpoint-2 \
+npx --no-install owlrunkit project checkpoint --workspace . --checkpoint-id checkpoint-2 \
   --at 2026-08-09T00:14:00.000Z --assignment-id assign-2 \
   --work-item work-item-1 --state completed --completed-units 1 \
   --summary 'Accepted work is complete' --evidence evidence/completion.txt
-owlrunkit project verification --workspace . --defer \
+npx --no-install owlrunkit project verification --workspace . --defer \
   --verification-id release-batch --at 2026-08-09T00:14:30.000Z \
   --work-item work-item-1 --owner-agent agent-successor \
   --check typecheck --check full-suite --check package-smoke \
   --reason 'Run broad checks once after the related changes settle' \
   --due-gate integration-ready
 # After those checks run once against the frozen candidate:
-owlrunkit project verification --workspace . --close \
+npx --no-install owlrunkit project verification --workspace . --close \
   --verification-id release-batch --at 2026-08-09T00:14:45.000Z \
   --disposition verified --summary 'The batched release checks passed' \
   --evidence evidence/release-batch.txt
-owlrunkit project integrate --workspace . --gate integration-ready \
+npx --no-install owlrunkit project integrate --workspace . --gate integration-ready \
   --at 2026-08-09T00:15:00.000Z --summary 'Integration gate evidence is complete' \
   --evidence evidence/integration.txt
-owlrunkit project status --workspace .
-owlrunkit project takeover --workspace . --agent agent-successor
-owlrunkit project successor --workspace . --transition-id project-next-001 \
+npx --no-install owlrunkit project status --workspace .
+npx --no-install owlrunkit project takeover --workspace . --agent agent-successor
+npx --no-install owlrunkit project successor --workspace . --transition-id project-next-001 \
   --at 2026-08-09T00:16:00.000Z --definition ./next-project-definition.json \
   --reason 'Archive the completed project and begin the next bounded project'
 ```
@@ -121,6 +152,53 @@ by itself. The assurance lane follows actual writer and authority count,
 rollback certainty, permissions, security, funds, irreversibility, schema/data
 migration, and explicit acceptance contracts—not environment labels alone.
 
+`project reject-and-return` applies only to the current explicit failed
+checkpoint. One Event V2 atomically binds that failure, its prior assignment,
+the reviewer, evidence, target Agent, and new assignment. The failed checkpoint
+remains immutable; status and takeover expose the rework relation and attempt.
+The command is not a Git rejection, merge action, or release authorization.
+
+### Import a frozen external source lane
+
+Capture the target before delegating source work, then import the producer's
+DeliveryPacket after it freezes the candidate:
+
+```bash
+npx --no-install owlrunkit project target-snapshot --workspace . \
+  --snapshot-id w2-5-entry --at 2026-08-12T08:00:00.000Z \
+  --work-item work-item-1 --target-workspace /absolute/frozen/worktree --apply
+
+npx --no-install owlrunkit project import-delivery --workspace . \
+  --delivery-id w2-5-luna --at 2026-08-12T09:00:00.000Z \
+  --assignment-id assign-1 --work-item work-item-1 --producer luna-max \
+  --target-workspace /absolute/frozen/worktree \
+  --packet /absolute/delivery-packet.json \
+  --entry-snapshot w2-5-entry --apply
+```
+
+Both commands support `--dry-run` instead of `--apply`. Artifacts are written
+only under the controller's `.owlcoda/runkit/project`; the target is read-only.
+Controller and target must be disjoint real directories, and the target must
+be the exact Git worktree root rather than a nested repository directory.
+The imported Event V3 records `deliveryCandidateFingerprint`,
+`workspaceSnapshotFingerprint`, target HEAD, candidate file hashes, overlay
+classification, and explicit `proven` / `notProven` statements. Omitting
+`--entry-snapshot` verifies the current candidate bytes but records
+`overlayStatus=candidate_only`.
+
+The cache classification covers cache paths visible to Git status, such as
+`.vitest/**`, `.vite/**`, `.pytest_cache/**`, and `__pycache__/**`. It does not
+claim to bind ignored paths (`ignoredPathsBound=false`) and does not yet create
+an isolated dependency consumer or temporary test cache. Lockfile or
+`node_modules` changes outside the packet are disclosed as dependency
+environment changes. Any other entry-to-candidate delta, or any packet path
+outside the WorkItem's allowed ownership, blocks import before project truth is
+written. This includes the deleted source side of a Git rename; changing target
+HEAD, tracked tree, or submodule identity also blocks overlay attestation.
+Event V3 can be created only by this verified intake path, not a legacy raw
+project request. No imported delivery grants Git, release, deployment,
+production, UX, or business acceptance.
+
 `project verification --defer` is a small deferred-verification ledger, not a
 test scheduler. It records stable check IDs, why they were intentionally not
 run yet, the responsible Agent, and the integration gate before which they
@@ -158,6 +236,11 @@ WorkItem. An assignment may bind an exact RunKit execution and lease; in that
 case, the WorkItem cannot complete until the execution has a trusted accepted
 closeout and its lease is released.
 
+`project takeover` adds the current candidate, its exact added/changed/removed
+path delta from the previous imported delivery, and handoffs that are stale
+because later project truth superseded them. These are read-only projections;
+they do not reopen work or grant writer authority.
+
 The Agent-facing natural actions are stable: split and assign work, report
 status, open or resolve a decision, hand off, take over, capture evidence, and
 verify. The CLI is the durable implementation surface; users can keep speaking
@@ -169,11 +252,11 @@ Preview deterministic, project-local commands, or atomically adopt only
 high-confidence candidates:
 
 ```bash
-owlrunkit profiles detect --workspace . --dry-run
-owlrunkit profiles detect --workspace . --apply
-owlrunkit profiles reconcile --workspace . --dry-run
-owlrunkit profiles reconcile --workspace . --apply
-owlrunkit profiles validate --workspace .
+npx --no-install owlrunkit profiles detect --workspace . --dry-run
+npx --no-install owlrunkit profiles detect --workspace . --apply
+npx --no-install owlrunkit profiles reconcile --workspace . --dry-run
+npx --no-install owlrunkit profiles reconcile --workspace . --apply
+npx --no-install owlrunkit profiles validate --workspace .
 ```
 
 `profiles detect --apply` is create-only. `profiles reconcile` previews or
@@ -185,12 +268,21 @@ launchers. A PATH-only package manager remains review-required. A dry-run that
 only canonicalizes JSON formatting reports `normalizationOnly: true` instead of
 showing unexplained hash drift with an empty update list.
 
+The dry-run is the V2 detection contract. It reports `profiles_insufficient`
+instead of `profiles_detected` when Git-visible source paths are uncovered or
+no actionable primary exists. `changedPaths`, `uncoveredSourcePaths`,
+`primaryBlockers`, `minimalSuggestedProfile`, and `repairCommands` explain the
+gap using only real project surfaces; absent conventional `src/` or `tests/`
+directories are never invented as blockers. Detection records both sides of a
+Git rename, reports Git-status failure, and rechecks the exact changed-path set
+before apply so a stale dry-run cannot write incomplete coverage.
+
 ## Choose auto, off, light, managed, or formal
 
 Start with the human-first read-only recommendation:
 
 ```bash
-owlrunkit mode recommend --workspace .
+npx --no-install owlrunkit mode recommend --workspace .
 ```
 
 - **off / No RunKit** uses neither continuity nor assurance for analysis,
@@ -211,7 +303,7 @@ recommendation; escalation is not sticky.
 Machine integrations may route an explicit risk-facts document directly:
 
 ```bash
-owlrunkit assurance route --workspace . \
+npx --no-install owlrunkit assurance route --workspace . \
   --request ./scripts/runkit-contract/templates/assurance-request.json
 ```
 
@@ -225,13 +317,28 @@ grant Git, release, publish, deploy, or business authority.
 Run Quick with:
 
 ```bash
-owlrunkit quick-verify --workspace . -- npm test
+npx --no-install owlrunkit quick-verify --workspace . -- npm test
+npx --no-install owlrunkit quick-verify --workspace . --stdin-file ./remote-check.sh --attest \
+  -- ssh test-host /bin/sh
+npx --no-install owlrunkit quick-metrics --workspace .
+npx --no-install owlrunkit quick-metrics --workspace . --verbose
 ```
 
-The top-level Quick result includes a bounded `outputSummary` with the last
-meaningful stdout/stderr lines, so common summaries such as `155 passed` are
-visible without opening `stdout.log`. The receipt still binds the complete
-stdout and stderr artifacts; the summary is presentation only.
+`--stdin-file` accepts a regular non-symlink file up to 1 MiB, copies its exact
+bytes into the receipt store, and binds its path, size, and SHA-256 in a V2
+Quick receipt before supplying those stored bytes as stdin. This avoids putting
+large scripts into SSH argv or receipt JSON. The top-level `outputSummary`
+includes bounded opening and closing stdout/stderr lines, so both rollback and
+restore phases remain visible while the complete artifacts stay receipt-bound.
+`--attest` runs the existing attestation immediately and returns its independent
+object alongside the Quick result; it does not promote Quick to Formal.
+
+`quick-metrics` is local-only and returns aggregate counts. Add `--verbose`
+when the individual receipt paths are needed. The former `--local` flag remains
+accepted as a compatibility no-op. New successful receipts no longer carry
+the fixed `quick_ignored_artifact_unbound` issue; historical receipts remain
+strictly readable without surfacing that non-actionable code as an attestation
+issue.
 
 ## Formal Delivery in three commands
 
@@ -240,13 +347,13 @@ Given a Goal Contract and the paths this work item may write, the happy path is:
 ```bash
 NODE_BIN="$(node -p 'process.execPath')"
 
-owlrunkit formal start --workspace . --run-id release-001 \
+npx --no-install owlrunkit formal start --workspace . --run-id release-001 \
   --goal .owlcoda/runkit/goal.json --owned-path 'src/**'
 
-owlrunkit formal check --workspace . --run-id release-001 \
+npx --no-install owlrunkit formal check --workspace . --run-id release-001 \
   --check-id source-syntax -- "$NODE_BIN" --check src/index.js
 
-owlrunkit formal finish --workspace . --run-id release-001 \
+npx --no-install owlrunkit formal finish --workspace . --run-id release-001 \
   --decision accepted
 ```
 
@@ -262,7 +369,7 @@ Formal also accepts a real project command through an enforced Verification
 Envelope:
 
 ```bash
-owlrunkit formal check --workspace . --run-id release-001 \
+npx --no-install owlrunkit formal check --workspace . --run-id release-001 \
   --work-item delivery --check-id project-tests \
   --envelope scripts/runkit-contract/templates/verification-envelope.json
 ```
@@ -277,7 +384,7 @@ the policy, the command is not run and no Formal acceptance is possible.
 Existing legacy verification may still capture evidence, but it is not silently
 promoted into this Formal path.
 
-Use `owlrunkit status --workspace .` for a concise human view of what is ready,
+Use `npx --no-install owlrunkit status --workspace .` for a concise human view of what is ready,
 what has not happened, how many gates remain, and the next allowed action.
 
 ## Freeze a dirty worktree safely
@@ -287,11 +394,11 @@ artifact. It binds the baseline, exact owned-path closure, source manifest,
 and payload bytes without requiring a Git commit.
 
 ```bash
-owlrunkit candidate freeze --workspace . --run-id release-001 \
+npx --no-install owlrunkit candidate freeze --workspace . --run-id release-001 \
   --from-lease delivery --candidate-id rc-001
-owlrunkit candidate verify --workspace . \
+npx --no-install owlrunkit candidate verify --workspace . \
   --candidate .owlcoda/runkit/executions/release-001/source-candidates/rc-001.json
-owlrunkit candidate materialize --workspace . \
+npx --no-install owlrunkit candidate materialize --workspace . \
   --candidate .owlcoda/runkit/executions/release-001/source-candidates/rc-001.json \
   --target-workspace /absolute/clean/materialization
 ```
@@ -310,10 +417,10 @@ Register every coverage root once. Later discovery and process-wide migration
 commands use the persistent registry automatically:
 
 ```bash
-owlrunkit fleet register-root --fleet-root /absolute/projects
-owlrunkit fleet register-root --fleet-root /absolute/other-projects
-owlrunkit fleet inspect-registry
-owlrunkit fleet discover
+npx --no-install owlrunkit fleet register-root --fleet-root /absolute/projects
+npx --no-install owlrunkit fleet register-root --fleet-root /absolute/other-projects
+npx --no-install owlrunkit fleet inspect-registry
+npx --no-install owlrunkit fleet discover
 ```
 
 The registry lives under the user-owned OwlCoda home. Initial discovery stops
@@ -338,10 +445,10 @@ Core successor separates an immutable candidate and fleet-wide plan from the
 Owner-authorized migration:
 
 ```bash
-owlrunkit core-successor plan --workspace . --plan-id core-016 \
+npx --no-install owlrunkit core-successor plan --workspace . --plan-id core-016 \
   --run-id release-001 --from-lease delivery --candidate-id rc-001
 
-owlrunkit core-successor apply --workspace . \
+npx --no-install owlrunkit core-successor apply --workspace . \
   --plan .owlcoda/runkit/core-successors/core-016/plan.json \
   --owner-authority ./owner-core-successor-authority.json \
   --receipt-id core-016-apply
@@ -361,19 +468,19 @@ Build and verification stay separate from the later permission to change a
 machine:
 
 ```bash
-owlrunkit deployment prepare --workspace . --run-id build-001 \
+npx --no-install owlrunkit deployment prepare --workspace . --run-id build-001 \
   --artifact dist/app.tgz --media-type application/gzip \
   --owner-decision ./owner-deployment-decision.json \
   --output .owlcoda/runkit/deployments/app-prepare.json
 
-owlrunkit deployment execute --workspace . \
+npx --no-install owlrunkit deployment execute --workspace . \
   --prepare .owlcoda/runkit/deployments/app-prepare.json \
   --owner-decision ./owner-deployment-decision.json \
   --owner-authority ./deployment-owner-authority.json \
   --manifest ./remote-deployment-manifest.json
 
 # Resume the automatic child after an interrupted or indeterminate stage.
-owlrunkit deployment execute --workspace . --resume \
+npx --no-install owlrunkit deployment execute --workspace . --resume \
   --prepare .owlcoda/runkit/deployments/app-prepare.json \
   --owner-decision ./owner-deployment-decision.json \
   --owner-authority ./deployment-owner-authority.json \

package/docs/architecture/OWLCODA_RUNKIT_0184_EXTERNAL_DELIVERY_INTAKE_PRODUCT_DECISION_20260812.md

@@ -0,0 +1,209 @@
+# OwlRunKit 0.18.4 External Delivery Intake Product Decision
+
+> Status: implemented source candidate; unpublished, uninstalled, unadopted
+>
+> Date: 2026-08-12, Asia/Shanghai
+>
+> Scope: controller/target separation, external DeliveryPacket intake,
+> dirty-overlay classification, actionable profile detection, takeover truth
+> delta, and project-local command identity
+
+## Decision
+
+RunKit remains a flight recorder and stage controller. Its default posture is
+light: ordinary analysis and small reversible source work do not require a
+RunKit execution. Quick binds one important verification command. Project
+Driver preserves continuity across sessions and writers. Formal remains
+reserved for facts that actually require stronger assurance, such as multiple
+writers or authorities, permissions, security, funds, irreversible change,
+uncertain rollback, schema/data migration, or an explicit Formal acceptance
+contract.
+
+Version 0.18.4 addresses one narrower gap: a Project Driver in a controller
+worktree must be able to record a candidate produced in a different frozen
+worktree without installing dependencies, writing `.owlcoda`, or changing
+package metadata in the target. Three adjacent onboarding and recovery defects
+are included because they otherwise leave this path non-actionable: false-success
+profile detection, missing stale/current candidate truth in takeover, and
+inconsistent CLI help/local metrics behavior.
+
+## Accepted dogfood facts
+
+These facts come from the Sierac MES, OwlChen, OwlFootball, Luna, and Cursor
+dogfood reports accepted as product input. This candidate does not re-run those
+foreign-project workflows.
+
+- Project Driver is a net benefit for long threads, cross-session takeover,
+  multi-stage test deployment, and explicit Gate ownership.
+- Quick is useful when it binds a frozen candidate and one decision-changing
+  command. It is not the mechanism that discovers most source bugs.
+- Ordinary single-writer source micro-batches become slower when every command
+  is wrapped in RunKit ceremony.
+- A controller worktree may have a valid RunKit project while a frozen source
+  worktree cannot accept `.owlcoda`, `package.json`, a lockfile, or
+  `node_modules` changes.
+- External Luna and Cursor deliveries currently require manual path/hash
+  aggregation before their candidate identity appears in Project Driver.
+- `npx --no-install owlrunkit` can use the exact project package while a bare
+  `owlrunkit` may resolve an older global binary. An old binary cannot safely
+  predict or trust a future Core identity.
+- Visible test-tool cache files can change a dirty-worktree fingerprint even
+  when the intended source candidate did not change.
+- Profile detection can look successful while its candidates do not cover the
+  Git-visible source candidate or provide an actionable primary repair.
+- A blank-session takeover needs to distinguish stale handoffs and show the
+  current external candidate delta instead of presenting historical facts as
+  competing next actions.
+- Source/test success is not UX completion, deployment activation, production
+  truth, or business effectiveness.
+
+## Long-term product decision
+
+Continuity and assurance remain independent dimensions. External source lanes
+do not become Formal merely because they use another worktree or Agent.
+
+| Situation | Continuity | Assurance |
+| --- | --- | --- |
+| Analysis, documentation discussion, disposable exploration | none | none |
+| One low-risk frozen candidate and one exact command | none | quick |
+| Cross-session or multi-stage ordinary reversible source work | project_driver | none or quick |
+| Mandatory high-risk fact or explicit Formal acceptance | as needed | formal |
+
+The user-facing presets remain `off`, `light`, `managed`, `formal`, and `auto`.
+They are preferences, not authorization, and cannot weaken a mandatory Formal
+route.
+
+## Released capability before this candidate
+
+The public npm release remains `owlrunkit@0.18.3`. It already provides:
+
+- independent continuity/assurance mode recommendation;
+- one-command `quick-verify --attest`;
+- hash-bound `--stdin-file` input;
+- bounded head-and-tail Quick output;
+- actionable Quick issues and aggregate-by-default metrics;
+- atomic failed-work `reject-and-return`;
+- self-contained packaged Skill contract references.
+
+Those features are not new 0.18.4 claims.
+
+## 0.18.4 candidate implementation
+
+### Controller-owned entry snapshot
+
+`project target-snapshot --dry-run|--apply` reads a target Git worktree twice
+and binds:
+
+- canonical target workspace reference;
+- repository identity and target HEAD;
+- tracked tree, submodules, dependency lockfiles, and visible dirty overlay;
+- the WorkItem's allowed path boundary;
+- one full workspace snapshot fingerprint.
+
+Only the controller's `.owlcoda/runkit/project/target-snapshots` path may be
+written. Controller and target must be disjoint real directories, and target
+must resolve to the exact Git worktree root. The target worktree is read-only.
+
+### External DeliveryPacket import
+
+`project import-delivery --dry-run|--apply` verifies the packet's exact
+whole-file hashes against the target and records append-only Event V3 with:
+
+- `deliveryCandidateFingerprint` for the packet file set;
+- `workspaceSnapshotFingerprint` for the complete target snapshot;
+- target HEAD, producer, WorkItem, and current assignment;
+- entry snapshot reference and hash when available;
+- candidate paths and entry-to-candidate changed paths;
+- tool-cache, dependency-environment, unchanged-packet, and out-of-scope
+  classifications;
+- explicit `proven` and `notProven` statements;
+- `targetWritePerformed=false` and `authorizationGranted=false`.
+
+If no entry snapshot exists, the packet can still prove the current candidate
+bytes. The event is then `candidate_only`; it cannot claim that the historical
+entry-to-candidate delta was observed. Any packet path outside WorkItem
+ownership or any unclassified source delta rejects the import before project
+truth is written. Import brackets packet verification with stable workspace
+snapshots, compares HEAD, tracked tree, submodules, and visible dirty overlay,
+and treats both source and destination of a rename as changed paths. Event V3
+is reserved for this verified intake path; legacy raw event requests cannot
+manufacture an external-delivery fact.
+
+### Command and Skill identity
+
+Installed-project instructions use `npx --no-install owlrunkit`. A process-level
+shared Skill or bare global CLI with an older version is reported as drift, not
+used as authority to reinterpret current project truth. Safe fleet Skill
+replacement remains a separate installation action and is not performed by
+this candidate.
+
+### Actionable profile onboarding
+
+Public `profiles detect --dry-run` returns Profile Detection V3. V2 remains an
+unchanged compatibility contract for existing consumers; V3 adds actionable
+coverage fields. It reads Git-visible changed paths without writing the
+workspace and reports
+`profiles_insufficient` when source paths remain uncovered or no actionable
+primary exists. The result includes exact uncovered paths, primary blockers, a
+minimal profile using only real project surfaces, and copyable preview/apply
+repair commands. Existing-profile repair continues through atomic
+`profiles reconcile`; absent conventional directories are not blockers.
+Detection and apply bind the same Git-visible changed-path set, including both
+sides of a rename. Status failure or drift blocks apply before configuration is
+written.
+
+### Takeover truth delta and CLI consistency
+
+`project status` and `project takeover` emit V2 projections while their V1
+exports remain unchanged for existing consumers. Takeover V2 projects handoffs
+made stale by later project facts, the current imported external delivery, and
+an exact added/changed/removed path
+delta from the previous delivery. The human projection remains one-screen.
+`project assign --help` is action-specific, and `quick-metrics` is local by
+definition: `--local` is optional and retained only as a compatibility no-op.
+
+Assurance and usage-mode routing follow the same rule: their V1 contracts retain
+the original bare-command machine values, while the CLI uses Assurance Route V2
+and Usage Mode Recommendation V2 with project-local
+`npx --no-install owlrunkit` commands.
+
+## Acceptance-level presentation
+
+Every imported delivery must keep these layers distinct:
+
+1. candidate file identity verified;
+2. entry-to-candidate visible overlay attested, or explicitly not attested;
+3. verification command/test result, if separately run;
+4. UX or independent product acceptance, if separately performed;
+5. deployment/runtime activation, if separately authorized and read back;
+6. production or business effectiveness, if separately accepted.
+
+No lower layer promotes a higher one.
+
+## Follow-up gaps
+
+Ten issue classes remain outside 0.18.4 and need separate contracts:
+
+- isolated temporary dependency consumer and test-cache execution;
+- binding ignored paths when a task explicitly needs them;
+- delta-oriented reuse of an older receipt plus a small allowed-path change;
+- external runtime mutation, rollback, final-state, and stage-failure fields;
+- upstream WorkItem invalidation/reopen with downstream waiting propagation;
+- recovery evidence semantics;
+- large-artifact deduplication;
+- atomic onboarding/bootstrap and safer shared-Skill fleet activation;
+- business-first stage summaries and acceptance-level UI projection;
+- efficiency metrics for repeated commands, false blocks, manual intervention,
+  handoff wait, and time to acceptable result.
+
+## What this candidate cannot claim
+
+- It is not published `owlrunkit@0.18.4`.
+- It is not installed, adopted, activated, committed, tagged, or pushed.
+- It does not auto-detect a source lane that was never assigned or imported.
+- It does not prove ignored cache paths; workspace snapshots continue to say
+  `ignoredPathsBound=false`.
+- It does not isolate dependencies or automatically reuse prior tests.
+- It does not run tests, create a Quick/Formal execution, modify Git, deploy,
+  access production, or grant business authority.
+- It does not move domain contracts or product judgment into OwlCoda.