owlrunkit 0.18.3 → 0.19.0

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.

package/docs/architecture/OWLCODA_RUNKIT_0190_CONSOLIDATED_DAILY_USE_PRODUCT_DECISION_20260812.md

@@ -0,0 +1,97 @@
+# OwlRunKit 0.19.0 Consolidated Daily-Use Product Decision
+
+状态：**Owner 已授权实施；七个 Wave 的源代码候选已完成，正式发布验证进行中**
+
+## Decision
+
+0.19.0 是一次整合型小版本后的次版本升级。它不会继续拆出多个 0.18.x，
+而是在一个 release candidate 中收敛 0.18.4 明确留下、且已被 OwlChen、MES、
+OwlFootball 和 MERM dogfood 重复验证的十类摩擦。
+
+长期产品原则保持不变：RunKit 默认轻、必要时重。它是飞行记录仪和阶段控制器，
+不是每条研发命令的审批系统。
+
+## Product Axes
+
+用户可见 mode 继续只是两个正交维度的 preset：
+
+- continuity：`none | project_driver`
+- assurance：`none | quick | formal`
+
+长周期、跨会话和多阶段主要提高 continuity。只有多 authority、多 writer、资金、
+权限、安全、不可逆变更、回滚不确定、schema/data migration 或明确 Formal
+acceptance 才强制 Formal。风险解除后允许降级，升级不成为粘性状态。
+
+## 0.19.0 Scope
+
+### Wave 1 — Atomic onboarding
+
+- 一条可预览、可原子应用、失败可回滚的 bootstrap；
+- `init --help` 与空 profile 首次接入死锁；
+- project-local exact binding 和 shared Skill drift 的明确诊断。
+
+### Wave 2 — Isolated verification
+
+- 临时 dependency consumer 和工具缓存隔离；
+- 源码、ignored cache、dependency environment 三类变化分离；
+- 只有任务明确需要时才哈希绑定 ignored paths。
+
+### Wave 3 — Evidence reuse
+
+- 旧 receipt + 小范围允许 delta 的复用规划与精确增量 gate；
+- 大 artifact 以 content-addressed hash/reference 去重，保留可恢复性。
+
+### Wave 4 — Runtime and recovery truth
+
+- `workspaceMutation`、`externalMutation`、`rollbackPerformed`、
+  `finalExternalState`、`failedStage`、`lastPassedStage`、`rollbackOutcome`；
+- recovery evidence 明确 `capturedBefore`、`restoresTo` 等语义。
+
+### Wave 5 — Rework lifecycle
+
+- 原生 reopen/invalidate upstream WorkItem；
+- downstream waiting propagation；
+- 原子 transfer/reject-and-return 高层动作，同时保留不可变底层事件。
+
+### Wave 6 — Human outcome and economics
+
+- 收据先展示业务阶段结果、验收层级和未证明边界；
+- 统计重复命令、误阻塞、人工介入、handoff 等待和 time-to-acceptable-result；
+- 指标用于约束 RunKit 自身摩擦，不以 receipt 数量冒充价值。
+
+### Wave 7 — Release closure
+
+- predecessor contracts 精确兼容或显式版本化 successor；
+- 独立风险审查、Core identity、packed Skill/package、registry consumer；
+- 一次性发布 `owlrunkit@0.19.0`。
+
+## Safety And Authority Boundaries
+
+- 用户 mode 是偏好，不是授权；较轻 mode 不能绕过强制 Formal 事实；
+- RunKit 结果始终保持 `authorizationGranted=false`；
+- receipt acceptance 不等于 commit、push、tag、publish、deploy、production 或业务验收；
+- controller/target 必须是分离的真实目录，冻结 target 不接受控制 artifacts 注入；
+- 已发布 strict schema 不原地重解释，破坏性变化必须新建版本并让 predecessor 共存；
+- bootstrap 不静默刷新用户级/fleet Skill，不静默修改 Git，不联网执行发布动作。
+
+## Evidence Layers
+
+界面与 receipt 必须依次区分：
+
+1. candidate file identity；
+2. workspace/overlay attestation；
+3. verification command/test result；
+4. UX 或独立产品验收；
+5. deployment/runtime activation；
+6. production 或业务有效性。
+
+低层证据不得自动提升为高层结论。
+
+## What Cannot Be Claimed Yet
+
+- 0.19.0 尚未 tag、publish 或被任何外部项目采用；
+- 本文不是 npm registry receipt，源代码完成不能替代 packed consumer 与
+  registry consumer 验证；
+- 当前可以声称七个 Wave 已进入单一 0.19.0 release candidate，不能声称
+  npm latest 已改变；
+- public mirror、官网、8019、全局 Skill 与外部项目升级不属于本次授权。

package/docs/architecture/OWLCODA_RUNKIT_USAGE_MODE_SELECTION_PRODUCT_DECISION_20260811.md

@@ -1,6 +1,6 @@
 # OwlCoda RunKit 使用模式选择：Sierac MES Dogfood 产品决议
 
-状态：**0.18.2 已发布；本文主体保留既有产品决议，文末追加未发布的 0.18.3 dogfood 修复候选**
+状态：**0.18.3 已发布；本文主体保留既有产品决议，0.18.4 外部候选纳管决议另见同日架构文档**
 日期：2026-08-11
 
 ## 已验证现场事实
@@ -165,7 +165,7 @@ RunKit contract/package gate、Core 身份同步、pack 内容检查和安装 sm
 上述 0.18.2 内容已经发布；准确 Git/npm 身份以 `docs/PRODUCT-TRUTH.md` 和独立发布
 回执为准。发布本身没有更新全局 Skill、迁移外部项目或授予业务权限。
 
-## 0.18.3 Sierac recovery dogfood 修复候选
+## 0.18.3 Sierac recovery dogfood 修复（已发布）
 
 ### 新增现场事实
 
@@ -205,12 +205,13 @@ attestation，且没有扩大到 Formal、生产、Git 或业务验收。
 
 ### 后续缺口
 
-本轮没有实现次优先级的 `project takeover` stale-handoff delta，也没有新增 recovery
-evidence 的 `captured_before` / `restores_to` 语义字段。Project Driver 自动 ID、时间戳、
+`project takeover` stale-handoff 与外部候选 delta 已进入未发布的 0.18.4 源码候选；
+recovery evidence 的 `captured_before` / `restores_to` 语义字段仍未实现。Project Driver 自动 ID、时间戳、
 单项完成与 integrate 合并，以及路径范围指纹仍保留在既有 backlog。
 
 ### 不能声称
 
-`0.18.3` 当前只是隔离 worktree 内的源码候选。它尚未 commit、合并、tag、publish、
-安装、全局 Skill 更新或外部项目 adoption；聚焦测试也不构成发布授权、生产授权或
-业务验收。
+`0.18.3` 已在后续独立发布 Gate 中完成 commit、tag、npm publication 与 registry
+consumer smoke；安装、项目 adoption、共享 Skill 激活和业务结果仍是不同事实。
+`0.18.4` 的 controller/target 分离与外部 DeliveryPacket 纳管边界见
+`OWLCODA_RUNKIT_0184_EXTERNAL_DELIVERY_INTAKE_PRODUCT_DECISION_20260812.md`；该版本当前仍只是源码候选。

package/docs/architecture/OWLCODA_RUN_KIT_CONTRACT_V0_2.md

@@ -478,6 +478,44 @@ bytes as exact stdin, and binds their workspace-relative path, byte size, and
 SHA-256. V1 remains the no-stdin receipt and stays readable. Neither schema
 binds undeclared ignored outputs or grants any authority.
 
+Core `0.19.0` adds `OwlCodaQuickVerificationReceiptV3` for explicit isolation,
+dependency-environment binding, and ignored-path binding. `--isolate` runs a
+Git-visible candidate copy in a disposable consumer and records consumer source
+versus discarded ignored-artifact deltas. `--dependency-root` binds an existing
+dependency environment without installing it. `--bind-ignored` is the only
+operation that emits `OwlCodaWorkspaceSnapshotV2` and claims those selected
+ignored bytes. Workspace source, selected ignored paths, dependency metadata,
+and consumer source mutations are distinct fail-closed facts. Disposable
+ignored artifacts do not mutate or become evidence for the source checkout.
+
+Core `0.19.0` also adds `OwlCodaQuickEvidenceReusePlanV1` and
+`OwlCodaQuickEvidenceReuseReceiptV1`. A reuse plan verifies one earlier strict,
+passed, source-unchanged Quick receipt from the same workspace, derives the
+current candidate delta from Git objects plus both snapshots, and refuses any
+path outside literal caller allowances before command execution. Byte-identical
+dirty content later committed to Git remains unchanged evidence. Apply runs one
+exact delta gate through Quick and records both receipt hashes; it grants no
+authority and does not satisfy Formal or higher acceptance layers.
+
+Quick output and Verification Envelope stdout/stderr evidence use a project-
+global create-only SHA-256 object store. Existing Quick receipt-local material
+paths remain valid; no historical tree is rewritten or deleted. Object reuse is
+storage/provenance behavior, never additional assurance.
+
+Core `0.19.0` can additionally bind external transition truth without changing
+Quick Receipt V1/V2/V3. `quick-verify --capture-runtime` gives the exact child
+an initially absent receipt-local `OWLRUNKIT_RUNTIME_REPORT` path. A strict
+`OwlCodaRunKitExternalRuntimeReportV1` there is projected into a separately
+hashed `OwlCodaRunKitRuntimeTransitionReceiptV1` that binds the Quick receipt
+bytes, report bytes, derived workspace mutation, command-reported external
+mutation, ordered stages, rollback outcome, final external state, and recovery
+artifact `capturedBefore` / `restoresTo` semantics. A failed stage followed by
+a successful rollback remains a failed transition with useful evidence; it is
+not promoted to Quick, Formal, deployment, or business acceptance. Missing or
+inconsistent runtime truth fails closed while preserving the base Quick
+receipt. `quick-runtime-verify` rechecks stored bytes and projection integrity;
+it does not independently re-observe the external runtime or grant authority.
+
 Deterministic `repair` persists a reviewable plan before replay, reuses only
 fresh receipt-bound coverage, replays pending exact argv, and appends
 replacement lineage. Failed and orphaned attempts remain inspectable. Repair
@@ -539,6 +577,25 @@ stale Packet, invalid evidence or engine drift must still follow the Core's
 foreign-project authority. Signing, keys, external anchors and GitHub Actions
 remain deferred.
 
+## Core v0.19 atomic onboarding
+
+Core `0.19.0` keeps Contract `0.2` and all existing authority boundaries. The
+versioned `OwlCodaRunKitOnboardingBootstrapPlanV1` dry-run binds the exact
+project-local package and official registry release, checks upgrade safety,
+previews profile reconciliation, reports shared Skill drift, and performs zero
+writes. `bootstrap --apply` rechecks that plan under a project-owned lock, then
+runs Core initialization, profile reconcile/validation, exact adoption and
+doctor readback as one high-level transaction.
+
+The transaction governs RunKit config, profiles, their migration/apply
+receipts, and adoption evidence. A failure after mutation restores their exact
+preimage before writing an append-only
+`OwlCodaRunKitOnboardingBootstrapReceiptV1`. A concurrent bootstrap, active or
+invalid project lifecycle, ambiguous project tool, exact-package mismatch, or
+registry mismatch fails closed. The command does not modify package files,
+source, Git, deployments, production, business state, or shared Skills, and it
+never grants those authorities.
+
 ## Deferred work
 
 Contract v0.2 still does not add a built-in browser or Electron driver, Plugin,