owlrunkit 0.18.2 → 0.18.3

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 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,12 @@ 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.
+
 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,7 +35,7 @@ separate authority boundaries.
 ## Install
 
 ```bash
-npm install --save-exact owlrunkit@0.18.2
+npm install --save-exact owlrunkit@0.18.3
 ```
 
 The `owlrunkit` bootstrap uses the project's exact locally bound CLI for
@@ -58,8 +64,8 @@ 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
@@ -77,6 +83,14 @@ owlrunkit project handoff --workspace . --handoff-id handoff-1 \
   --from-agent agent-runtime --to-agent agent-successor \
   --summary 'Source work is ready for continuation' --next 'Run verification' \
   --evidence evidence/source.txt
+# If review instead rejects a failed checkpoint, preserve it and open rework
+# without first mutating the WorkItem back to active:
+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
 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
@@ -121,6 +135,12 @@ 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.
+
 `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
@@ -226,12 +246,26 @@ Run Quick with:
 
 ```bash
 owlrunkit quick-verify --workspace . -- npm test
+owlrunkit quick-verify --workspace . --stdin-file ./remote-check.sh --attest \
+  -- ssh test-host /bin/sh
+owlrunkit quick-metrics --workspace . --local
+owlrunkit quick-metrics --workspace . --local --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 --local` returns aggregate counts only. Add `--verbose` when the
+individual receipt paths are needed. 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
 

package/docs/architecture/OWLCODA_RUNKIT_018_PROJECT_DRIVER_PRODUCT_DEFINITION.md

@@ -34,11 +34,13 @@ The ordinary user-facing flow is a typed direct CLI surface:
 3. `project checkpoint` records meaningful state and evidence.
 4. `project handoff` transfers a responsibility without overwriting its
    history.
-5. `project decision` opens or resolves a decision with rationale and evidence.
-6. `project integrate` records an integration-gate result with evidence.
-7. `project status` projects the current team state.
-8. `project takeover` builds the next bounded action for a successor Agent.
-9. After the project derives `overall=completed`, `project successor`
+5. `project reject-and-return` preserves a current failed checkpoint and opens
+   one evidence-linked rework assignment atomically.
+6. `project decision` opens or resolves a decision with rationale and evidence.
+7. `project integrate` records an integration-gate result with evidence.
+8. `project status` projects the current team state.
+9. `project takeover` builds the next bounded action for a successor Agent.
+10. After the project derives `overall=completed`, `project successor`
    archives it and installs one fresh project under explicit Owner invocation.
 
 Except for the one definition supplied to `init`, normal users provide typed
@@ -65,6 +67,11 @@ checkpoint.
 ## Continuity actions
 
 A handoff preserves the outgoing assignment and records the successor action.
+A reject-and-return event binds the current failed checkpoint, failed
+assignment, reviewer, evidence, target Agent, and new rework assignment in one
+append-only write. The failed event stays terminal and immutable; the WorkItem
+continues from a new derived active rework attempt. It cannot target completed,
+active, implicit execution-only failure, or historical failure state.
 A decision separates the open question from its later resolution, rationale,
 and evidence. An integration event records that the project gate was reached;
 it is not a Git merge, release, deployment, or publication operation. Status and
@@ -132,6 +139,10 @@ untrusted control state. Normal project coordination retains
 `authorizationGranted=false` unless a separately authorized boundary says
 otherwise.
 
+The new atomic rework record uses `OwlCodaRunKitTeamProjectEventV2`; existing
+Event V1 bytes and meanings are unchanged and remain readable. This avoids
+silently adding a new event meaning to the versioned V1 contract.
+
 ## Assurance boundary
 
 Multiple Agents coordinating a project do not make project coordination Formal

package/docs/architecture/OWLCODA_RUNKIT_USAGE_MODE_SELECTION_PRODUCT_DECISION_20260811.md

@@ -1,6 +1,6 @@
 # OwlCoda RunKit 使用模式选择：Sierac MES Dogfood 产品决议
 
-状态：**0.18.1 已发布；本文主体保留发布前产品决议，文末追加 0.18.2 dogfood 补丁候选**
+状态：**0.18.2 已发布；本文主体保留既有产品决议，文末追加未发布的 0.18.3 dogfood 修复候选**
 日期：2026-08-11
 
 ## 已验证现场事实
@@ -162,5 +162,55 @@ RunKit contract/package gate、Core 身份同步、pack 内容检查和安装 sm
 - profile 纯格式规范化计划显式返回 `normalizationOnly: true`；
 - package README 与五模式、profile reconcile 的已实现真值一致。
 
-当前这些内容只是本地 `owlrunkit@0.18.2` 候选。它不代表 commit、tag、npm 发布、
-全局 Skill 更新、OwlChen/OwlFootball 迁移或任何业务授权已经发生。
+上述 0.18.2 内容已经发布；准确 Git/npm 身份以 `docs/PRODUCT-TRUTH.md` 和独立发布
+回执为准。发布本身没有更新全局 Skill、迁移外部项目或授予业务权限。
+
+## 0.18.3 Sierac recovery dogfood 修复候选
+
+### 新增现场事实
+
+Sierac MES 三轮 0.18.2 实测继续支持“普通小任务少用、跨窗口使用 Project Driver、
+高价值状态转换使用 Quick”的模式决议。冷启动 takeover 约 0.4 秒恢复了当前 truth，
+并正确识别陈旧 handoff；一次 W1.8 回滚与 W1.9 恢复在串行读回后留下 GO Quick
+attestation，且没有扩大到 Formal、生产、Git 或业务验收。
+
+同一轮暴露了五个可复现的 Quick 产品缺口：
+
+- 为把远端脚本精确交给 SSH，操作者只能把 base64 放进 argv；单个参数达到
+  14,469 bytes，整条 argv 约 14,539 bytes，receipt 为 79,591 bytes。
+- 顶层摘要只保留最后三行，无法同时展示前半段 W1.8 回滚与后半段 W1.9 恢复。
+- 项目现存 13/13 Quick 都携带固定 `quick_ignored_artifact_unbound`，没有可行动差异。
+- 日常 Quick 仍需第二次调用 `quick-attest`。
+- `quick-metrics --help` 返回通用 invalid-input，默认结果无条件展开全部 receipt 路径。
+
+### 本轮实现
+
+- `quick-verify --stdin-file <file>` 将最多 1 MiB 的 regular non-symlink 输入复制到
+  receipt store，以路径、大小和 SHA-256 生成 `OwlCodaQuickVerificationReceiptV2`，
+  再把已保存字节作为 exact stdin；脚本内容不进入 argv 或 receipt JSON。
+- `outputSummary` 同时返回有界 head 与 tail，完整 stdout/stderr 仍是唯一证据材料。
+- 新 Quick 不再生成固定 ignored-artifact issue；历史 receipt 仍严格可读，但 attest
+  不再把该推测性代码作为问题输出。未声明 ignored output 仍不属于 Quick 证明范围。
+- `quick-verify --attest` 在一个高层调用中返回独立 attestation 对象，不把 Quick
+  提升为 Formal。
+- `quick-metrics --local` 默认只返回聚合；`--verbose` 才返回 receipt 路径，并新增
+  action-specific help。
+- 后续真实候选复核证明 RunKit 能保存“测试全绿但版本合同错误”的 rejection、Quick
+  receipt、源码未变事实和重新责任人。`project reject-and-return` 因此作为同一
+  0.18.3 候选的原子 Project Driver 动作：只接受当前显式 failed checkpoint，保留
+  失败事件，记录 reviewer/reason/evidence，并创建新的 rework assignment。新记录使用
+  Event V2，不改写 Event V1 合同。
+- standalone npm 构建把 Contract v0.1/v0.2 的权威字节复制到 Skill 自身的
+  `references/`，使发布包内相对链接和之后的 managed Skill 安装保持一致。
+
+### 后续缺口
+
+本轮没有实现次优先级的 `project takeover` stale-handoff delta，也没有新增 recovery
+evidence 的 `captured_before` / `restores_to` 语义字段。Project Driver 自动 ID、时间戳、
+单项完成与 integrate 合并，以及路径范围指纹仍保留在既有 backlog。
+
+### 不能声称
+
+`0.18.3` 当前只是隔离 worktree 内的源码候选。它尚未 commit、合并、tag、publish、
+安装、全局 Skill 更新或外部项目 adoption；聚焦测试也不构成发布授权、生产授权或
+业务验收。

package/docs/architecture/OWLCODA_RUN_KIT_CONTRACT_V0_2.md

@@ -471,6 +471,13 @@ project-owned receipt store and performs no telemetry or network access. A
 Quick `GO` remains `captured_verification`; it cannot satisfy the Formal
 Contract v0.2 acceptance gate.
 
+Core `0.18.3` adds `OwlCodaQuickVerificationReceiptV2` only when the caller
+uses `quick-verify --stdin-file`. RunKit copies at most 1 MiB from a regular
+non-symlink file into the receipt store before execution, supplies those stored
+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.
+
 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

package/integrations/codex/skills/owlcoda-runkit/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: owlcoda-runkit
-description: Run receipt-backed, project-owned work with OwlCoda RunKit. Use when Codex needs to coordinate a large multi-Agent project, show per-Agent progress, manage dependencies or decisions, record intentionally deferred verification without repeating covered tests, hand work to another Agent, recover a blank-session next action, initialize or inspect `.owlcoda/runkit/`, plan bounded work with engine pins and leases, capture exact verification evidence, close an execution, produce a ready-for-commit receipt, or perform a read-only foreign-project shadow without widening Git or release authority.
+description: Run receipt-backed, project-owned work with OwlCoda RunKit. Use when Codex needs to coordinate a large multi-Agent project, show per-Agent progress, manage dependencies or decisions, atomically return failed work for evidence-linked rework, record intentionally deferred verification without repeating covered tests, hand work to another Agent, recover a blank-session next action, initialize or inspect `.owlcoda/runkit/`, plan bounded work with engine pins and leases, capture exact verification evidence, close an execution, produce a ready-for-commit receipt, or perform a read-only foreign-project shadow without widening Git or release authority.
 ---
 
 # OwlCoda RunKit
 
 Use the bundled deterministic Core to coordinate work through project artifacts rather than chat memory. Require Node.js 20 or later.
 
-Bundled release: standalone `owlrunkit@0.18.2`, bundling Contract `0.2` and
-Core `0.18.2` with manifest
-`sha256:abe17ff794b4019d8d476f09eb5d4105bae1070b1df0aab53e6c94c7ec8b65a6`.
-The published `owlrunkit@0.18.1` package is the trusted prior for rollback;
+Bundled release: standalone `owlrunkit@0.18.3`, bundling Contract `0.2` and
+Core `0.18.3` with manifest
+`sha256:cc7a923649592084150828f24f0d90f280af92514bafdbc4999f4015b3175d5c`.
+The published `owlrunkit@0.18.2` package is the trusted prior for rollback;
 verify exact official npm registry provenance before adoption. The immutable
 rollback baseline for the prior release is `owlrunkit@0.16.1` with SHA-1
 `1bc119d24879bdd8959af16b364af55ca9d61ea9` and canonical npm tarball URL
@@ -24,8 +24,9 @@ The session is an execution interface. Project artifacts are the system of recor
 Translate ordinary user requests into durable typed project actions. Do not ask
 the user to operate the CLI when the request and authority are already clear.
 
-The normal mainline is `init`, `assign`, `checkpoint`, `handoff`, `decision`,
-`verification`, `integrate`, `status`, and `takeover`. After a project
+The normal mainline is `init`, `assign`, `checkpoint`, `handoff`,
+`reject-and-return`, `decision`, `verification`, `integrate`, `status`, and
+`takeover`. After a project
 derives completed, `successor` is the bounded lifecycle step. `init` accepts one project definition
 JSON; subsequent actions use direct typed flags. Normal users do not author
 request, event, receipt, or hash JSON. The legacy `--request <event.json>` form
@@ -40,6 +41,9 @@ remains available for existing automation and compatibility.
 - "I decided ...": append a decision resolution with rationale and evidence.
 - "Hand this to another Agent": append the handoff, then a successor assignment;
   never overwrite the old assignment.
+- "Reject this failed candidate and return it": use one `project
+  reject-and-return` event. Preserve the failed checkpoint, bind the review
+  evidence, create the rework assignment, and never rewrite failure as active.
 - "Continue/take over": build `project takeover` for the current Agent and use
   its bounded next action and evidence refs.
 - "Start the next project": only after status derives `overall=completed`,
@@ -76,6 +80,10 @@ owlrunkit project handoff --workspace "$PROJECT_ROOT" --handoff-id "$HANDOFF_ID"
   --at "$OCCURRED_AT" --assignment-id "$ASSIGNMENT_ID" --work-item "$WORK_ITEM_ID" \
   --from-agent "$AGENT_ID" --to-agent "$SUCCESSOR_AGENT_ID" \
   --summary "$SUMMARY" --next "$NEXT_ACTION" --evidence "$EVIDENCE_REF"
+owlrunkit project reject-and-return --workspace "$PROJECT_ROOT" \
+  --rework-id "$REWORK_ID" --at "$OCCURRED_AT" --work-item "$WORK_ITEM_ID" \
+  --reviewer-agent "$REVIEWER_AGENT_ID" --to-agent "$AGENT_ID" \
+  --reason "$REJECTION_REASON" --next "$NEXT_ACTION" --evidence "$EVIDENCE_REF"
 owlrunkit project decision --workspace "$PROJECT_ROOT" --resolve \
   --decision-id "$DECISION_ID" --at "$OCCURRED_AT" --resolution "$RESOLUTION" \
   --rationale "$RATIONALE" --evidence "$EVIDENCE_REF"
@@ -199,15 +207,26 @@ For one low-risk exact command, use the Core v0.13 Quick path:
 owlrunkit quick-verify \
   --workspace "$PROJECT_ROOT" -- "$ABSOLUTE_EXECUTABLE" "arg-one"
 
+owlrunkit quick-verify \
+  --workspace "$PROJECT_ROOT" --stdin-file "$SCRIPT_FILE" --attest \
+  -- ssh test-host /bin/sh
+
 owlrunkit quick-attest \
   --workspace "$PROJECT_ROOT" --receipt "$QUICK_RECEIPT"
 
 owlrunkit quick-metrics \
   --workspace "$PROJECT_ROOT" --local
+
+owlrunkit quick-metrics \
+  --workspace "$PROJECT_ROOT" --local --verbose
 ```
 
-Quick receipts are `captured_verification`, not Formal acceptance. Metrics are
-local-only and perform no telemetry or network request.
+`--stdin-file` copies and SHA-256-binds at most 1 MiB of regular non-symlink
+input before supplying the stored bytes as exact stdin. `--attest` returns the
+separate attestation object in the same high-level invocation. Quick receipts
+remain `captured_verification`, not Formal acceptance. Metrics are aggregate by
+default; `--verbose` adds receipt paths. Both forms are local-only and perform
+no telemetry or network request.
 
 Core v0.13 also adds deterministic repair and exact-byte offline transport:
 

package/integrations/codex/skills/owlcoda-runkit/assets/templates/config.json

@@ -2,9 +2,9 @@
   "schemaVersion": "OwlCodaRunKitConfigV2",
   "core": {
     "contractVersion": "0.2",
-    "coreVersion": "0.18.2",
-    "coreManifestSha256": "sha256:abe17ff794b4019d8d476f09eb5d4105bae1070b1df0aab53e6c94c7ec8b65a6",
-    "coreSourceRef": "artifact:sha256:abe17ff794b4019d8d476f09eb5d4105bae1070b1df0aab53e6c94c7ec8b65a6"
+    "coreVersion": "0.18.3",
+    "coreManifestSha256": "sha256:cc7a923649592084150828f24f0d90f280af92514bafdbc4999f4015b3175d5c",
+    "coreSourceRef": "artifact:sha256:cc7a923649592084150828f24f0d90f280af92514bafdbc4999f4015b3175d5c"
   },
   "authorizationPolicy": "external_explicit_authority_required"
 }

package/integrations/codex/skills/owlcoda-runkit/references/contract-v0.1.md

@@ -0,0 +1,160 @@
+# OwlCoda RunKit Contract v0.1
+
+Status: **frozen for Codex-side project execution**
+Frozen at: 2026-07-13
+Runner prerequisite: Node.js 20+
+
+## Purpose
+
+RunKit Contract v0.1 defines the smallest reusable execution contract proven while developing OwlCoda inside Codex. It coordinates project-owned truth, bounded workers, delivery evidence, stage verification, invalidation and replacement without relying on chat history or agent memory.
+
+This is a control and evidence contract. It is not an OwlCoda product API, a workflow designer, a memory system or a release system.
+
+## Frozen principles
+
+1. **Project-owned truth** — goals, packets, profiles, receipts and decisions live as project artifacts. Agent memory may help locate them but is never authoritative.
+2. **One owner per write scope** — every work item has an explicit lease and owned paths. Parallelism is allowed only across non-overlapping scopes.
+3. **Complete a phase before stage verification** — implementation lanes may batch a coherent phase and stop at `ready_for_stage_verification`; the stage gate runs once after all dependencies are fresh.
+4. **Evidence travels with delivery** — a delivery packet records scoped whole-file hashes, canonical fingerprint, commands already run and repository actions. The controller verifies hashes instead of repeating covered commands.
+5. **Stale evidence fails before execution** — a scoped source mismatch returns `invalidated_by_concurrent_write`; verification commands must remain at zero until a fresh replacement packet is valid.
+6. **Uncovered change fails closed** — if no profile covers a changed path, the decision is `full_profile_required`, never an empty successful selection.
+7. **Lineage validity is not verification success** — a structurally valid receipt graph becomes accepted only when the active receipt binds the current source fingerprint, exact selected profiles and real command receipts.
+8. **Append-only replacement** — invalidated receipts remain immutable. A replacement references the parent receipt SHA-256 and becomes the only active leaf.
+9. **Foreign projects remain project-owned** — read-only shadow runs may read another repository but must write all runner artifacts and scratch outside that repository and prove its start/end state is unchanged.
+10. **Runtime truth beats transcript appearance** — gate decisions consume files, hashes, exit codes and receipts, not worker summaries.
+
+### Additive clarifications
+
+These rules narrow unsafe or ambiguous inputs without changing the frozen v0.1 semantics:
+
+1. **Runtime state is never product source** — `.owlcoda/runkit` and every descendant are reserved. They are forbidden in delivery `changedFiles`, verification profile path rules and lease owned paths. A violation is `invalid_input` / exit `3`, never a source change or profile match.
+2. **One execution pins one engine** — execution creation records `contractVersion`, `coreVersion`, `coreManifestSha256` and an immutable or content-addressed `coreSourceRef`. Every later core invocation compares this pin before acting. A mismatch fails closed as `engine_changed_during_execution` / exit `2`; it cannot silently mix implementations inside one lineage.
+3. **Core and producer data are separate** — acceptance semantics consume the contract version, pinned core identity and core payload. Producer identity is provenance. Adapter-specific extensions are namespaced and cannot add authority or change acceptance.
+4. **Configuration is data, not authority** — project configuration, profiles and command declarations never authorize Git, publish, deploy, destructive actions, credential use or foreign-project writes.
+
+## Artifact chain
+
+```text
+GoalContract
+  -> ExecutionPlan
+  -> WorkItem + WorkerLease
+  -> ExecutionDeliveryPacket
+  -> VerificationProfile selection
+  -> Stage VerificationReceipt
+  -> GateDecision
+  -> CloseoutReceipt
+```
+
+`events.jsonl` is the append-only transition ledger. `execution-plan.json` is a derived mutable snapshot and must not override contradictory events or receipts.
+
+## Delivery source contract
+
+An `ExecutionDeliveryPacket` contains exactly one source hash map:
+
+- `changedFiles.files`, or
+- `changedFiles.wholeFileSha256`.
+
+Both shapes present is malformed. Paths must be safe repository-relative paths: no absolute path, Windows rooted or drive-relative path, backslash, NUL, empty segment, `.` or `..`. Selected sources must be regular files inside the physical workspace root; symlinks and root escapes are rejected. The reserved `.owlcoda/runkit` subtree is rejected even though it is otherwise repository-relative, preventing receipts from recursively changing the fingerprint they describe.
+
+Canonical stream:
+
+```text
+<path><TAB>sha256:<lowercase-whole-file-sha256><LF>
+```
+
+Rows are ordered by ascending Unicode code units, independent of locale and ICU. The source fingerprint is SHA-256 of the UTF-8 bytes of the canonical stream.
+
+Source gate results and process exit codes:
+
+- `valid` — exit `0`
+- `invalidated_by_concurrent_write` — exit `2`
+- `malformed_packet` — exit `3`
+
+## Verification profile contract
+
+A profile has a stable `id` and path rules. v0.1 supports only:
+
+- exact safe repository-relative path;
+- safe non-empty `directory/**` prefix.
+
+For legal inputs the resolver returns deterministic, de-duplicated profile IDs. Any uncovered changed path returns:
+
+```json
+{
+  "decision": "full_profile_required",
+  "profileIds": [],
+  "uncoveredPaths": ["..."]
+}
+```
+
+Unsafe input is `invalid_input` / exit `3`; it is not converted into a profile decision. Profiles may not name `.owlcoda/runkit`, `.owlcoda/runkit/**` or a descendant exact path.
+
+## Receipt lineage contract
+
+Each lineage entry contains:
+
+- a 64-hex `receiptSha256` matching canonical receipt content;
+- a receipt object;
+- optional 64-hex `parentReceiptSha256` referencing an earlier invalidated receipt.
+
+Receipt SHA values are globally unique. The lineage rejects malformed entries, hash mismatch, missing or non-prior parent, parent with the wrong state, cycles, branches and multiple active leaves.
+
+Lineage CLI exit codes:
+
+- structurally valid — exit `0`
+- well-formed but invalid — exit `2`
+- malformed input — exit `3`
+
+## Joint verification gate
+
+The active receipt must bind:
+
+- a current source gate with `status=valid` and exit `0`;
+- the exact recomputed source fingerprint;
+- the exact targeted profile IDs;
+- a valid single-leaf receipt lineage.
+
+For `status=passed`, `commandRuns` must be greater than zero and equal the number of command receipts. Every command receipt requires a non-empty command, exit `0`, and SHA-256 for stdout and stderr.
+
+A zero-command receipt may remain `shadow_validated` or `ready_for_verification`, but it cannot be accepted as passed.
+
+## Stage verification economy
+
+- Implementation lanes complete a coherent phase before testing when the round contract selects stage verification.
+- A stage owner consumes all fresh packets and runs one declared top-level profile.
+- The controller validates the packet and receipt hashes and does not repeat covered commands.
+- A failed stage is classified before repair. Only the affected stage is rerun after a replacement packet; unrelated profiles remain valid.
+- Full regression belongs at an integration, merge or release boundary, not every feature delivery.
+
+## Foreign-project read-only mode
+
+Before and after the stage, record at minimum:
+
+- foreign HEAD;
+- raw Git status bytes and SHA-256;
+- a declared workspace manifest fingerprint appropriate to the project;
+- selected file hashes.
+
+All foreign build scratch and receipts must be redirected to the controller project's artifact directory. Any start/end mismatch is `foreign_workspace_changed_during_shadow`, even when the verifier itself passed.
+
+## Provenance
+
+- Run001 proved leases, receipt-first handoff, targeted repair and controller economy.
+- Run002 proved a packaged provider-backed synthetic coding loop and restart recovery.
+- Run003 proved stale packet invalidation, minimal affected profile selection and append-only replacement.
+- Run004 proved the contract against the foreign Swift/macOS OwlOps project with one stage command, one focused Swift verifier and zero foreign repository writes.
+
+The exact evidence hashes are recorded in the Run004 manifest and closeout receipt.
+
+## Versioning rule
+
+The semantics above are frozen as v0.1. New optional fields are allowed when they do not weaken these invariants. Any change to path grammar, canonicalization, exit meanings, invalidation timing, receipt parentage, acceptance evidence or foreign-write policy requires a new contract version.
+
+## Not yet included
+
+- reusable npm package or global installation;
+- Codex plugin or skill distribution;
+- remote worker transport;
+- UI/workflow designer;
+- cloud/team memory;
+- automatic commit, publish or deployment authority.