owlrunkit 0.18.1 → 0.18.3

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # 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,
+  shell-safe correction command when a measured checkpoint omits
+  `--completed-units`.
+- Keeps symlinked workspace roots fail-closed while reporting the canonical
+  `--workspace` path, including the macOS `/tmp` to `/private/tmp` case.
+- Returns a bounded stdout/stderr `outputSummary` at the top level of Quick
+  results without changing the receipt or weakening full-output binding.
+- Retries one transient registry transport failure while retaining the existing
+  per-attempt timeout, and distinguishes DNS, connection, timeout, HTTP,
+  authentication, and missing-version failures.
+- Aligns the packaged README with five-mode routing and existing profile
+  reconciliation instead of treating long-running, release, or production
+  labels as automatic Formal triggers.
+- Adds action-specific `quick-verify --help`, lists canonical risk-category
+  values in mode help and validation errors, and marks formatting-only profile
+  reconcile plans with `normalizationOnly: true`.
+
 ## 0.18.1
 
 - Adds read-only `mode recommend` and `mode status` commands with five

package/README.md

@@ -11,6 +11,16 @@ continuity and assurance independently. It keeps ordinary development light
 while preserving mandatory Formal routing for material safety and authority
 facts.
 
+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
@@ -25,7 +35,7 @@ separate authority boundaries.
 ## Install
 
 ```bash
-npm install --save-exact owlrunkit@0.18.1
+npm install --save-exact owlrunkit@0.18.3
 ```
 
 The `owlrunkit` bootstrap uses the project's exact locally bound CLI for
@@ -54,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
@@ -73,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
@@ -112,9 +130,16 @@ Normal users supply the one definition JSON to `init`, then use typed flags and
 values. They do not need to author request, event, receipt, or hash JSON. The
 legacy `--request <event.json>` path remains available for existing automation
 and compatibility. Multiple Agents do not make project coordination Formal by
-themselves. This flow does not make project coordination Formal by itself; the
-assurance lane follows the underlying high-risk integration,
-release, production, migration, destructive, or explicit Formal-acceptance boundary.
+themselves. Project Driver continuity does not make project coordination Formal
+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
@@ -166,30 +191,52 @@ 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 .
 ```
 
-`--apply` is create-only. It refuses ambiguous or low-confidence candidates,
-source drift, symlinks, and launchers that do not resolve to exact local files.
-It directly supports lock-bound npm plus exact project-installed pnpm, Yarn,
-and Bun launchers. A PATH-only package manager remains review-required. It
-never silently replaces an existing profile set.
+`profiles detect --apply` is create-only. `profiles reconcile` previews or
+atomically updates an existing profile set and leaves a migration receipt. Both
+paths refuse ambiguous or low-confidence candidates, source drift, symlinks,
+and launchers that do not resolve to exact local files. Detection directly
+supports lock-bound npm plus exact project-installed pnpm, Yarn, and Bun
+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.
+
+## Choose auto, off, light, managed, or formal
+
+Start with the human-first read-only recommendation:
+
+```bash
+owlrunkit mode recommend --workspace .
+```
+
+- **off / No RunKit** uses neither continuity nor assurance for analysis,
+  documentation, and disposable exploration that needs no reusable evidence.
+- **light / Quick Verification** runs one exact low-risk, source-bound command.
+- **managed** adds Project Driver continuity; each WorkItem may still use no
+  assurance, Quick, or Formal according to its own facts.
+- **formal / Formal Delivery** is forced by multiple writers, permission or
+  security boundaries, funds, irreversible work, uncertain rollback,
+  schema/data migration, or an explicit Formal acceptance contract.
+- **auto** derives the preset from supplied facts and is the default.
 
-## Choose No RunKit, Quick, or Formal
+Production, release, deployment, long duration, and interruption recovery do
+not force Formal by themselves. Long or interrupted work primarily selects
+Project Driver continuity. Risk containment permits a fresh lower-assurance
+recommendation; escalation is not sticky.
 
-Route explicit risk facts before starting work:
+Machine integrations may route an explicit risk-facts document directly:
 
 ```bash
 owlrunkit assurance route --workspace . \
   --request ./scripts/runkit-contract/templates/assurance-request.json
 ```
 
-- **No RunKit** is for work that needs neither a reusable receipt nor controlled
-  writes.
-- **Quick Verification** is for one low-risk, source-bound command that needs a
-  reusable receipt but no writer lease or Formal acceptance.
-- **Formal Delivery** is for multi-writer, long-running, migration, integration,
-  release, production, funds, destructive, or formally accepted work.
+`mode recommend --help` lists every accepted `--risk-category`; an invalid
+category reports both the rejected value and the canonical allowed list.
 
 The router fails closed to Formal when required risk facts are incomplete.
 Quick receipts cannot become Formal acceptance, and Formal acceptance does not
@@ -199,8 +246,27 @@ 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
 ```
 
+`--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
 
 Given a Goal Contract and the paths this work item may write, the happy path is:

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 已发布；本文主体保留既有产品决议，文末追加未发布的 0.18.3 dogfood 修复候选**
 日期：2026-08-11
 
 ## 已验证现场事实
@@ -125,8 +125,9 @@ global gate 仍正确失效。
 
 ## 不能声称的内容
 
-- 这份文档和当前 worktree 不是已发布的 0.18.1，也不是 npm、Core、Skill 或任何
-  项目的升级完成证明。
+- 本文主体形成时记录的是 0.18.1 发布前候选；0.18.1 后续发布事实以
+  `docs/PRODUCT-TRUTH.md` 和独立 release receipt 为准。本文本身不证明 npm、Core、
+  Skill 或任何项目已升级。
 - `mode recommend` 根据调用者提供的结构化事实路由；它不会自动发现所有业务、
   权限、资金或迁移风险。
 - RunKit 降低进度、证据和完成状态幻觉，不直接解决 Sierac MES 业务问答幻觉。
@@ -136,7 +137,80 @@ global gate 仍正确失效。
 
 ## 版本建议
 
-本组变更适合形成 `owlrunkit@0.18.1` 小版本候选：它保持 0.18 的 Project Driver
+本组变更当时适合形成 `owlrunkit@0.18.1` 小版本候选：它保持 0.18 的 Project Driver
 和回执合同，新增只读 CLI，并修复 dogfood 验证出的行为缺陷。候选只有在聚焦测试、
 RunKit contract/package gate、Core 身份同步、pack 内容检查和安装 smoke 都通过后
 才具备发布评审资格；发布、项目升级与运行时激活仍是之后的独立动作。
+
+## 0.18.2 dogfood 补丁追加
+
+0.18.1 发布后，Sierac MES 与 OwlChen 的项目级使用继续证明 `managed + quick` 是普通
+跨会话源码 Wave 的合适默认，Formal 只应由真实高风险事实触发。OwlChen 已读回项目
+本地 0.18.1 的 doctor、profiles、Formal、Quick、metrics 与模式选择器主路径；进程级
+共享 Skill 因另一项目存在 active execution/lease 而停止升级，这是正确的安全边界，
+不是缺陷。
+
+这些后续 dogfood 暴露的缺口适合形成 0.18.2 patch，而不是新增平台能力：
+
+- symlink workspace 拒绝时直接给出 canonical `--workspace`，包括 macOS
+  `/tmp` 到 `/private/tmp`；
+- `project checkpoint --help` 和 measured WorkItem 缺参错误给出完整命令；
+- Quick 顶层返回有界 stdout/stderr 摘要，同时完整日志继续由回执绑定；
+- doctor 对 registry transport 做一次重试、每次保留原有超时上限，并区分 DNS、连接、
+  超时、HTTP、认证和版本缺失；
+- `quick-verify --help` 可用，risk category 的帮助与错误列出同一组规范值；
+- profile 纯格式规范化计划显式返回 `normalizationOnly: true`；
+- package README 与五模式、profile reconcile 的已实现真值一致。
+
+上述 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.1`, bundling Contract `0.2` and
-Core `0.18.1` with manifest
-`sha256:349b4157d3d089462b172de1619ccd169b5c1669b9322e2580ac6ec4f8616b07`.
-The published `owlrunkit@0.18.0` 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.1",
-    "coreManifestSha256": "sha256:349b4157d3d089462b172de1619ccd169b5c1669b9322e2580ac6ec4f8616b07",
-    "coreSourceRef": "artifact:sha256:349b4157d3d089462b172de1619ccd169b5c1669b9322e2580ac6ec4f8616b07"
+    "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.