owlrunkit 0.19.2 → 0.21.0

package/docs/architecture/OWLCODA_RUNKIT_021_TEAM_DELIVERY_PHASE2_PRODUCT_DECISION_20260813.md

@@ -0,0 +1,249 @@
+# OwlRunKit 0.21 Team Delivery Phase 2 Product Decision
+
+Date: 2026-08-13
+Status: `product_contract_definition / implementation_and_release_truth_tracked_separately`
+
+## Decision
+
+OwlRunKit 0.21 extends the existing Project Driver and read-only Team Delivery
+projection with two missing kinds of durable truth:
+
+1. typed external Gates produced by domain-owned adapters; and
+2. an evidence-bound delivery lifecycle that keeps source acceptance,
+   integration, materialization, deployment, live readback, and product acceptance separate.
+
+Project Driver remains the only active task graph. Phase 2 does not add a
+scheduler, start an Agent, select a model, increase assurance, parse arbitrary
+domain documents, or grant Git, release, deployment, production, or business
+authority.
+
+The implementation order is fixed:
+
+1. ExternalGateV1 plus DeliveryLifecycleV1 contracts and read-only projection;
+2. explicit Quick-receipt binding for WorkItems that declare an evidence
+   requirement;
+3. inventory of explicit candidate artifacts not yet represented as active
+   WorkItem lanes; and
+4. copyable fleet Skill dry-run, install, and rollback plans.
+
+The OwlFootball 0.20 dogfood adds three bounded Phase 2 corrections to the
+same release: a canonical candidate identity, controller-owned verification of
+a frozen foreign worktree, and explicit Doctor visibility for package/shared
+Skill drift. Commit-rebinding remains a separate future receipt contract and
+is not implied by these additions.
+
+Assisted or automatic Agent dispatch is not part of 0.21. It requires a later
+Owner decision after real dogfood demonstrates lower handoff time or lower
+controller intervention.
+
+## Stable product model
+
+The independent dimensions remain:
+
+```text
+continuity   none | project_driver
+coordination none | team_delivery
+assurance    none | quick | formal
+acceptance   L0 | L1 | L2 | L3
+authority    externally granted; never inferred by RunKit
+```
+
+Phase 2 adds delivery state without folding it into those dimensions:
+
+```text
+work ledger
+  -> source accepted
+  -> integrated
+  -> materialized
+  -> deployed
+  -> live readback
+  -> product accepted
+```
+
+Every arrow requires a new append-only fact and evidence. A passed source Gate
+does not imply integration. Integration does not imply a sealed or built
+artifact. Materialization does not imply deployment. Deployment does not imply
+a healthy readback. A healthy readback does not imply product or business
+acceptance.
+
+## ExternalGateV1
+
+RunKit does not know what an OwlFootball packaging Gate, a MES runtime Gate, or
+another domain decision means. The domain product owns that judgment. A
+domain-owned adapter may emit one strict generic Gate observation containing:
+
+- a stable Gate identity and title;
+- the delivery stage that requires it;
+- `pending`, `passed`, `blocked`, or `deferred` status;
+- the responsible Agent;
+- adapter identity, source reference, and exact SHA-256 source digest;
+- a concise summary and evidence references; and
+- an all-false authority boundary.
+
+The typed Project Driver command records the observation as an immutable event.
+A later observation must explicitly supersede the current observation for that
+Gate. RunKit validates the structure and source binding; it does not parse or
+reinterpret the domain source.
+
+An unresolved external Gate is visible throughout status projection. Once the
+work ledger is otherwise ready for the Gate's delivery stage, that Gate becomes
+the dominant gap and replaces any misleading execution next action.
+
+## DeliveryLifecycleV1
+
+The lifecycle contains six fixed stages:
+
+| Stage | Positive fact | Other honest outcomes |
+|---|---|---|
+| source | `accepted` | `rejected` |
+| integration | `integrated` | `rejected` |
+| materialization | `materialized` | `failed` |
+| deployment | `deployed` | `failed`, `rolled_back` |
+| live readback | `passed` | `failed` |
+| product acceptance | `accepted` | `rejected`, `deferred` |
+
+A lifecycle record binds one stage, outcome, responsible Agent, evidence, and
+the external Gates used for that transition. The current projection includes
+all six stages, the highest positively established stage, the next required
+stage, any blocking stage, and unresolved external Gates.
+
+The runtime enforces ordering. It rejects integration before source acceptance,
+materialization before integration, deployment before materialization, live
+readback before deployment, and product acceptance before a passed live
+readback. A later correction for the same stage
+must supersede the current stage record. A correction cannot silently rewrite
+downstream facts.
+
+Recording a deployed or accepted fact is evidence bookkeeping only. Every
+result continues to carry `authorizationGranted=false` and cannot authorize the
+underlying action.
+
+## Versioning and compatibility
+
+Published predecessor contracts are immutable:
+
+- TeamProject Event V1-V5 retain their existing bytes and meanings;
+- TeamProject Status V1-V3 retain their existing fields and projections; and
+- Team Delivery Status V1 retains its Phase 1 surface.
+
+Phase 2 uses successor contracts:
+
+- TeamProject Event V6 for external Gate and delivery lifecycle facts;
+- TeamProject Event V7 for WorkItem evidence policy and receipt-bound
+  checkpoint facts;
+- TeamProject Status V4 for ExternalGateV1 and DeliveryLifecycleV1 projection;
+- Team Delivery Status V2 for the corresponding read-only Team view.
+
+Raw generic capture may not create V6 or V7 facts. Operators use typed commands so
+the current Gate, lifecycle ordering, source binding, and exact retry rules are
+checked before the event is written.
+
+## Receipt binding
+
+Phase 2 adds `project work-item require-evidence` and
+`project checkpoint --from-quick-receipt`. The WorkItem policy is append-only
+and may select `none` or `quick`; it does not represent Formal acceptance.
+Receipt binding attests the current Quick receipt and persists an immutable
+reference. It becomes blocking only when the WorkItem contract explicitly
+requires Quick evidence. Existing WorkItems, measurable work, and
+assurance=`none` are not retroactively upgraded to Quick or Formal.
+
+## Explicit candidate inventory
+
+Team Delivery may report `unmodeled_candidate_lanes` only from artifacts RunKit
+can identify explicitly, such as a verified DeliveryPacket, target snapshot,
+data-candidate event, or external Gate. It may not infer a candidate from an
+arbitrary dirty worktree or create a second task graph.
+
+The inventory is read-only. Turning an artifact into active Project Driver work
+requires a separate typed project action and authority.
+
+## Fleet Skill operations
+
+Shared Skill drift remains non-blocking for a project-local CLI unless an exact
+project contract says otherwise. A fleet plan may show affected projects and
+copyable dry-run, install, and rollback commands. It may not silently update a
+shared Skill while any project has an active execution or lease.
+
+## Canonical candidate identity
+
+The primary dirty-candidate identity is a canonical ordered ledger, not a raw
+`git diff` digest. It records the target HEAD and tracked tree plus every
+changed path, prior rename path, operation, Git status, file kind, mode, byte
+length, and content SHA-256. Discovery uses `LC_ALL=C`, disables optional Git
+locks, and fixes `core.abbrev=40`; the command, environment, Git version,
+ledger byte length, ledger hash, and candidate fingerprint are persisted.
+
+The full-index binary diff remains available as a transport artifact with a
+fixed command, but its digest is explicitly not the candidate identity.
+
+## Controller-owned Foreign Quick
+
+`quick-verify --workspace <controller> --foreign-workspace <target>` keeps the
+project-local CLI and every RunKit artifact in the controller. The target must
+be a separate real Git worktree root. RunKit copies its visible source into a
+disposable consumer, optionally projects an already-installed disjoint
+dependency root, and binds Quick Receipt V4 to the target's canonical candidate
+and bounded filesystem identities before and after execution.
+
+The current resolver remains fail-closed: a controller CLI may not masquerade
+as the target's older or absent project-local CLI. `zeroWriteObserved` means
+the governed target state matched before and after; RunKit does not claim an OS
+write sandbox or prove that a transient write restored before the second
+observation never occurred.
+
+## Doctor Skill drift
+
+Doctor reports package-bound and discovered process-wide Skill versions and absolute
+paths. A mismatch is a visible non-blocking warning when the project-local CLI
+and Core are valid. RunKit cannot observe which instruction bytes an existing
+Agent process loaded, so `loadedSkillVersion` remains `unknown` and the repair
+guidance starts a new session using the package-bound Skill. Fleet mutation
+still requires the separate safe plan/install boundary.
+
+## Acceptance scenarios
+
+1. A typed pending external Gate is projected with its source hash, blocks the
+   relevant delivery stage, and becomes the unique dominant gap when due.
+2. A later exact superseding observation may pass the Gate; stale, duplicate,
+   or source-unbound observations fail closed.
+3. Source, integration, materialization, deployment, live readback, and product acceptance each
+   require a separate evidence-bound event and never auto-promote.
+4. Out-of-order lifecycle facts, unresolved required external Gates, and
+   attempts to revise an earlier stage beneath downstream truth fail before
+   writing.
+5. Status V1-V3 and Team Delivery Status V1 remain unchanged; V4/V2 expose the
+   new fields under new schema identities.
+6. Raw project capture cannot bypass typed V6 intake.
+7. Team and Project status remain read-only and dispatch remains disabled.
+8. No result grants Git, release, deployment, production, business, automation,
+   money, credential, or Agent-dispatch authority.
+9. Quick-receipt binding never forces assurance on an existing WorkItem that
+   did not explicitly require it.
+10. Candidate inventory is derived only from explicit artifacts and does not
+    infer arbitrary dirty-worktree truth.
+11. Canonical candidate identity remains byte-stable when only Git object
+    abbreviation settings or unrelated object-store population changes.
+12. Foreign Quick writes receipts only under the controller, creates no target
+    `.owlcoda/runkit`, binds target/dependency/command evidence, and invalidates
+    any permanent governed target delta observed after execution.
+13. Doctor exposes package/process Skill drift and absolute package Skill path
+    without claiming knowledge of the Skill already loaded by an Agent.
+
+## Non-goals
+
+- no automatic or assisted Agent launch;
+- no model or vendor selection;
+- no general scheduler or second graph;
+- no automatic assurance escalation;
+- no parsing of domain product contracts inside Core;
+- no implicit deployment, product acceptance, or business verdict;
+- no shared Skill mutation without fleet-safe explicit invocation;
+- no publication claim from repository source or test success.
+
+## Claims boundary
+
+This document defines the Phase 2 product contract. Its presence does not prove
+implementation completion, package publication, project adoption, shared Skill
+activation, runtime deployment, or business acceptance. Those facts require
+their own current receipts and external readback.

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

@@ -7,20 +7,114 @@ description: Run receipt-backed, project-owned work with OwlCoda RunKit. Use whe
 
 Use the bundled deterministic Core to coordinate work through project artifacts rather than chat memory. Require Node.js 20 or later.
 
-Bundled candidate: standalone `owlrunkit@0.19.2`, bundling Contract `0.2` and
-Core `0.19.2` with manifest
-`sha256:c46ae9d8ed0572e5636ab5725f922f8db3ee5bf0f966b200bce7b2287c9267c8`.
-This candidate is not published. The current published release remains
-`owlrunkit@0.19.1`, which is the trusted prior for rollback and the only
-registry-installable version named by this Skill before publication. 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
-`https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.16.1.tgz`.
+Bundled release artifact: standalone `owlrunkit@0.21.0`, bundling Contract `0.2` and
+Core `0.21.0` with manifest
+`sha256:f85b9bf8c32705d5f5dfebdb653e83ac8d1ac0468214c17f230cbd2de04246fd`.
+Registry adoption remains fail-closed until exact official npm registry
+provenance for `owlrunkit@0.21.0` is independently verified. The published
+rollback baseline for this artifact is `owlrunkit@0.20.0`, with SHA-1
+`b123f5ea33a4f500961a0df3226ed0ca409d111d` and canonical npm tarball URL
+`https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.20.0.tgz`.
 The root `owlcoda` package has a separate version lifecycle.
 
 The session is an execution interface. Project artifacts are the system of record.
 
+## Team Delivery Phase 1
+
+Use Team Delivery only when current Project Driver facts make coordination
+material. It is a read-only projection, not a second graph or an Agent launcher.
+
+```bash
+npx --no-install owlrunkit team recommend --workspace "$PROJECT_ROOT"
+npx --no-install owlrunkit team status --workspace "$PROJECT_ROOT"
+npx --no-install owlrunkit team packet validate --workspace "$PROJECT_ROOT" \
+  --packet /absolute/path/to/team-packet.json
+```
+
+An uninitialized project, no actionable work, or one ordinary ready WorkItem
+must remain off. Disjoint actionable lanes may be parallel-eligible; overlapping
+owned paths must block parallel writing. Independent verification, handoff,
+rework, candidate transfer, or multiple active owners may recommend Team without
+changing assurance. TeamTaskPacket V2, TeamAcceptancePacket V2, and
+CandidateTransferPacket V1 are package-owned portable contracts. Do not depend
+on a user-level `manage-agent-team` Skill at runtime. Core does not choose model
+vendors, score Agents, start tasks, or grant Git, release, deployment,
+production, business, automation, or money authority.
+
+## Team Delivery Phase 2
+
+Use successor status when external acceptance or delivery state must remain
+distinct from the Project Driver work ledger:
+
+```bash
+npx --no-install owlrunkit project reconcile --workspace "$PROJECT_ROOT" \
+  --reconciliation-id <id> --at <ISO-UTC> --gate-id <gate> --title <title> \
+  --required-for <source|integration|materialization|deployment|live_readback|product_acceptance> \
+  --gate-status <pending|passed|blocked|deferred> --owner-agent <agent> \
+  --source-adapter <adapter> --source-ref <ref> --source-sha256 <sha256:...> \
+  --summary <text> --evidence <ref>
+npx --no-install owlrunkit project delivery record --workspace "$PROJECT_ROOT" \
+  --record-id <id> --at <ISO-UTC> --stage <stage> --stage-status <outcome> \
+  --owner-agent <agent> --summary <text> --evidence <ref>
+npx --no-install owlrunkit team status --workspace "$PROJECT_ROOT"
+```
+
+ExternalGateV1 is a typed adapter observation; Core does not parse domain
+product documents. DeliveryLifecycleV1 records source acceptance, integration,
+materialization, deployment, live readback, and product acceptance separately and never
+auto-promotes. `unmodeledCandidateLanes` contains only explicit RunKit facts,
+not guesses from a dirty worktree. Dispatch and authority remain false.
+
+An existing WorkItem stays lightweight unless a typed policy explicitly
+requires Quick evidence. When required, bind one currently attested receipt:
+
+```bash
+npx --no-install owlrunkit project work-item require-evidence \
+  --workspace "$PROJECT_ROOT" --policy-id <id> --at <ISO-UTC> \
+  --work-item <id> --owner-agent <agent> --requirement quick \
+  --reason <text> --evidence <ref>
+npx --no-install owlrunkit project checkpoint --workspace "$PROJECT_ROOT" \
+  --checkpoint-id <id> --at <ISO-UTC> --assignment-id <id> --work-item <id> \
+  --state completed --summary <text> --from-quick-receipt <receipt.json>
+```
+
+For shared Skill drift, run the read-only fleet plan before any explicit
+installer action:
+
+```bash
+npx --no-install owlrunkit fleet skill-plan \
+  --skill-root "$RUNKIT_SKILL_TARGET" --archive-root "$RUNKIT_SKILL_ARCHIVE_ROOT"
+```
+
+Doctor reports both the package-bound and discovered shared Skill absolute
+paths and versions. Shared drift is visible but non-blocking for a valid
+project-local CLI. `loadedSkillVersion=unknown` is deliberate: RunKit cannot
+inspect which instructions an already-running Agent process loaded. Start a
+new Agent session with the package-bound Skill when current instructions are
+required.
+
+For one exact verification against a frozen worktree that must not receive
+RunKit state, use the controller-owned lane:
+
+```bash
+npx --no-install owlrunkit quick-verify \
+  --workspace "$CONTROLLER_ROOT" --foreign-workspace "$FROZEN_TARGET" \
+  --dependency-root "$DEPENDENCY_ROOT" -- <executable> [args...]
+```
+
+Receipt V4 stays under the controller and binds the target's canonical
+candidate ledger, before/after governed filesystem identity, disposable
+consumer, dependency environment, and exact command. Treat
+`zeroWriteObserved=true` as before/after observed evidence, not proof that an
+OS-level transient write could not have been restored. Never replace the
+existing project-local CLI fail-closed resolver with an ancestor/global CLI.
+
+Treat Team status warnings as typed advice. A
+`no_bound_verification_receipt` warning is non-blocking unless a separate gate
+contract says otherwise; do not make historical assurance=`none` work run
+Formal retroactively. Prefer the aggregated warning summary for blank-session
+recovery and expand individual WorkItems only when action is required.
+
 ## Project Driver actions
 
 Translate ordinary user requests into durable typed project actions. Do not ask
@@ -211,14 +305,22 @@ below has no CLI entry.
 
 ```bash
 npx --no-install owlrunkit bootstrap --workspace "$PROJECT_ROOT" \
-  --exact owlrunkit@0.19.1 --dry-run
+  --exact owlrunkit@0.21.0 --dry-run
 npx --no-install owlrunkit bootstrap --workspace "$PROJECT_ROOT" \
-  --exact owlrunkit@0.19.1 --apply
+  --exact owlrunkit@0.21.0 --apply
 npx --no-install owlrunkit init --workspace "$PROJECT_ROOT"
 npx --no-install owlrunkit inspect --json --workspace "$PROJECT_ROOT"
+npx --no-install owlrunkit inspect --json --compact --workspace "$PROJECT_ROOT"
 npx --no-install owlrunkit status --workspace "$PROJECT_ROOT"
 ```
 
+Use compact inspect for routine Agent recovery. It intentionally omits full
+execution and Project Driver history while retaining project truth, progress,
+dominant gap, owner, next action, warnings, execution counts, and false
+authority fields. Doctor reports project CLI/Core and shared Skill versions
+independently; process-level Skill drift is non-blocking and must not override
+the installed project Core.
+
 Prefer `bootstrap` for a new standalone-package consumer or an eligible idle
 project upgrade. Its dry-run is zero-write; apply rechecks the exact local
 package and official registry binding under a project-owned lock, then performs

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

@@ -2,9 +2,9 @@
   "schemaVersion": "OwlCodaRunKitConfigV2",
   "core": {
     "contractVersion": "0.2",
-    "coreVersion": "0.19.2",
-    "coreManifestSha256": "sha256:c46ae9d8ed0572e5636ab5725f922f8db3ee5bf0f966b200bce7b2287c9267c8",
-    "coreSourceRef": "artifact:sha256:c46ae9d8ed0572e5636ab5725f922f8db3ee5bf0f966b200bce7b2287c9267c8"
+    "coreVersion": "0.21.0",
+    "coreManifestSha256": "sha256:f85b9bf8c32705d5f5dfebdb653e83ac8d1ac0468214c17f230cbd2de04246fd",
+    "coreSourceRef": "artifact:sha256:f85b9bf8c32705d5f5dfebdb653e83ac8d1ac0468214c17f230cbd2de04246fd"
   },
   "authorizationPolicy": "external_explicit_authority_required"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "owlrunkit",
-  "version": "0.19.2",
+  "version": "0.21.0",
   "description": "Project Driver for cross-Agent project continuity and progression; execution, evidence, verification, and recovery are the underlying trust substrate.",
   "license": "GPL-3.0-or-later",
   "author": "yeemio <owlclaw@163.com>",

package/packages/attest/README.md

@@ -1,7 +1,7 @@
 # `@owlcoda/attest`
 
 `@owlcoda/attest` is OwlCoda RunKit's unsigned, read-only verification plane.
-It verifies Quick Receipt V1, V2, and V3 artifacts, Formal public verification
+It verifies Quick Receipt V1, V2, V3, and V4 artifacts, Formal public verification
 bundles, and local `OwlCodaAttestationRefV1` references without importing the
 private mutation Core. V2 adds one hash-bound stdin material while preserving
 the same unsigned, authorization-free assurance boundary. V3 adds a disposable
@@ -13,6 +13,12 @@ marked private until naming clearance and release authorization exist.
 `consumer-surface-v1.json` remains the byte-compatible predecessor contract.
 `consumer-surface-v2.json` adds Receipt V3, Snapshot V2, isolated Quick, and
 explicit ignored-path issue codes without reinterpreting V1.
+`consumer-surface-v3.json` adds Receipt V4 for controller-owned verification of
+a disjoint frozen Git worktree. It binds a canonical target candidate ledger,
+the before/after governed target filesystem identity, the disposable consumer,
+and any external dependency root. Its zero-write statement is an observed
+before/after fact; it does not claim that a transient write restored before the
+second observation was impossible.
 
 ## CLI