pdurlej/platform

Fork 0

feat(contracts): durable job bundle as central coordination substrate (ADR-0008) #169

Closed

claude wants to merge 1 commit from claude-orchestrator/job-bundle-foundation into main

claude commented

2026-05-11 01:59:09 +02:00

Collaborator

What

Closes the GPT-5.5 Pro oracle review (2026-05-11) blind-spot: "The under-loved piece is not local models, Matrix rooms, or voice pitches. It is the replayable coordination substrate. The whole system becomes sane when every action has: job_id, privacy_tier, current_owner, artifact_manifest, resume_from, next_decision. Without that, the architecture is impressive but brittle."

ADR-0008 defines the Durable Job Bundle as the central coordination substrate. Four canonical schemas + renderable template + per-cousin runbook. Spec-only; runtime adoption tickets follow per cousin (vps1000 for Iskra, rs2000 for Hermes, M1 for claude/codex).

What ships

File	Purpose	Size
`decisions/0008-durable-job-bundle.md`	The ADR	228 LoC
`contracts/job.schema.json`	Canonical `job.yaml` schema (Draft 2020-12; `iskra_job_bundle.v1`)	164 LoC
`contracts/state.schema.json`	Per-job state checkpoint (`iskra_job_state.v1`)	79 LoC
`contracts/artifact_manifest.schema.json`	Artifact catalog (`iskra_job_artifact_manifest.v1`)	88 LoC
`contracts/NEXT_ACTION.template.md`	Renderable template for per-job canonical next-step	91 LoC
`contracts/README.md`	Overview + validation snippets + worked example bundle	228 LoC
`docs/runbooks/job-bundle-usage.md`	Per-cousin protocol (all 7 cousins) + sequence diagram + common mistakes	215 LoC

7 files, +1093 / -0.

Key design decisions (per ADR-0008)

privacy_tier field with 3 values (cloud_ok, soft_private, hard_private) — machine-readable privacy boundary that gates which cousins may process the bundle. Addresses GPT GAP #2.
resume_from field points to canonical "what next" artifact (default NEXT_ACTION.md). Anti-archaeology primitive — next cousin reads ONE file to know what to do, not the whole bundle. Addresses GPT GAP #3 (resumability).
decision_needed structure enumerates operator-decision queue. Attention-dispatcher (Phase 07 design) reads this across all open bundles. Addresses GPT §"operator-bandwidth collapse" risk.
ULID for job_id (Crockford base-32, 26 chars). Time-sortable, single-line, URL-safe. Operator-readable.
Schema versioning is immutable per ship (schema_version: const). Breaking changes ship as v2 alongside v1.
Per-cousin runtime paths are runbook-level decisions, not schema-level. /srv/iskra/jobs/ vs ~/iskra-jobs/ etc. Bundles are host-portable.

What this PR DOES NOT

Does NOT implement runtime (mkdir/sync/cleanup of jobs root) — separate Phase 03-compatible tickets per cousin.
Does NOT add platformctl lint command for job bundle validity — follow-up.
Does NOT enforce privacy_tier at runtime — Phase 07 design doc path-policy.yaml specifies enforcement.
Does NOT include archival policy — lifecycle module follow-up.
Does NOT touch any module.yaml or runtime path.
Does NOT depend on ADR-0006 merge (#168) — but the runbook references ADR-0006 cousin enumeration; if #168 is rejected, this PR's runbook section per cousin needs to revert to ADR-0005's role list only.

Acceptance criteria

Three JSON Schemas validate as Draft 2020-12 self-consistent (jsonschema.Draft202012Validator.check_schema clean — verified).
Worked example bundle in contracts/README.md is fully populated and references all 4 schemas correctly.
Runbook covers all 7 cousins from ADR-0006 enumeration (or ADR-0005's role list if #168 not merged).
3+3 canary fires on risk/process label (changes decisions/ + new contracts/ namespace).
Operator approves; Status: Proposed in ADR flips to Accepted.

Rollback

git revert 07b676f
git push origin main

Single commit, 7 net-new files in two new directories (contracts/, docs/runbooks/ is new only if it didn't exist). Reverting is clean; no runtime touched.

Refs

GPT-5.5 Pro oracle review 2026-05-11: §Sidebar "PROF KONG'S BLIND SPOT", §1 SEQUENCING (must-ship #1), §2 GAPS #1/#2/#3/#5
Companion: PR #168 (governance fold ADR-0006 + 0007). This PR references ADR-0006 cousin enumeration; if #168 rejected, this PR's docs/runbooks/job-bundle-usage.md falls back to ADR-0005 role list.
Related (Phase 07 design docs, separate PRs forthcoming): attention-dispatcher consumes decision_needed; path-policy.yaml enforces privacy_tier; local-admin tier observes privacy_tier.

Codex effort needed

Review + merge. No runtime change. Acceptance is schema-validation + doc-review.

Role: orchestrator / drafter (claude)
Lane: foundation / contracts
Next: operator review + 3+3 canary + merge → unblocks Phase 07 design PRs that depend on this substrate.

## What Closes the GPT-5.5 Pro oracle review (2026-05-11) blind-spot: *"The under-loved piece is not local models, Matrix rooms, or voice pitches. It is the replayable coordination substrate. The whole system becomes sane when every action has: job_id, privacy_tier, current_owner, artifact_manifest, resume_from, next_decision. Without that, the architecture is impressive but brittle."* ADR-0008 defines the Durable Job Bundle as the central coordination substrate. Four canonical schemas + renderable template + per-cousin runbook. Spec-only; runtime adoption tickets follow per cousin (vps1000 for Iskra, rs2000 for Hermes, M1 for claude/codex). ## What ships | File | Purpose | Size | |------|---------|------| | `decisions/0008-durable-job-bundle.md` | The ADR | 228 LoC | | `contracts/job.schema.json` | Canonical `job.yaml` schema (Draft 2020-12; `iskra_job_bundle.v1`) | 164 LoC | | `contracts/state.schema.json` | Per-job state checkpoint (`iskra_job_state.v1`) | 79 LoC | | `contracts/artifact_manifest.schema.json` | Artifact catalog (`iskra_job_artifact_manifest.v1`) | 88 LoC | | `contracts/NEXT_ACTION.template.md` | Renderable template for per-job canonical next-step | 91 LoC | | `contracts/README.md` | Overview + validation snippets + worked example bundle | 228 LoC | | `docs/runbooks/job-bundle-usage.md` | Per-cousin protocol (all 7 cousins) + sequence diagram + common mistakes | 215 LoC | 7 files, +1093 / -0. ## Key design decisions (per ADR-0008) 1. **`privacy_tier` field** with 3 values (`cloud_ok`, `soft_private`, `hard_private`) — machine-readable privacy boundary that gates which cousins may process the bundle. Addresses GPT GAP #2. 2. **`resume_from` field** points to canonical "what next" artifact (default `NEXT_ACTION.md`). Anti-archaeology primitive — next cousin reads ONE file to know what to do, not the whole bundle. Addresses GPT GAP #3 (resumability). 3. **`decision_needed` structure** enumerates operator-decision queue. Attention-dispatcher (Phase 07 design) reads this across all open bundles. Addresses GPT §"operator-bandwidth collapse" risk. 4. **ULID for `job_id`** (Crockford base-32, 26 chars). Time-sortable, single-line, URL-safe. Operator-readable. 5. **Schema versioning** is immutable per ship (`schema_version: const`). Breaking changes ship as `v2` alongside `v1`. 6. **Per-cousin runtime paths** are runbook-level decisions, not schema-level. `/srv/iskra/jobs/` vs `~/iskra-jobs/` etc. Bundles are host-portable. ## What this PR DOES NOT - Does NOT implement runtime (mkdir/sync/cleanup of jobs root) — separate Phase 03-compatible tickets per cousin. - Does NOT add `platformctl` lint command for job bundle validity — follow-up. - Does NOT enforce `privacy_tier` at runtime — Phase 07 design doc `path-policy.yaml` specifies enforcement. - Does NOT include archival policy — lifecycle module follow-up. - Does NOT touch any `module.yaml` or runtime path. - Does NOT depend on ADR-0006 merge (#168) — but the runbook references ADR-0006 cousin enumeration; if #168 is rejected, this PR's runbook section per cousin needs to revert to ADR-0005's role list only. ## Acceptance criteria - [x] Three JSON Schemas validate as Draft 2020-12 self-consistent (`jsonschema.Draft202012Validator.check_schema` clean — verified). - [x] Worked example bundle in `contracts/README.md` is fully populated and references all 4 schemas correctly. - [x] Runbook covers all 7 cousins from ADR-0006 enumeration (or ADR-0005's role list if #168 not merged). - [ ] 3+3 canary fires on `risk/process` label (changes `decisions/` + new `contracts/` namespace). - [ ] Operator approves; `Status: Proposed` in ADR flips to `Accepted`. ## Rollback ``` git revert 07b676f git push origin main ``` Single commit, 7 net-new files in two new directories (`contracts/`, `docs/runbooks/` is new only if it didn't exist). Reverting is clean; no runtime touched. ## Refs - GPT-5.5 Pro oracle review 2026-05-11: §Sidebar "PROF KONG'S BLIND SPOT", §1 SEQUENCING (must-ship #1), §2 GAPS #1/#2/#3/#5 - Companion: PR #168 (governance fold ADR-0006 + 0007). This PR references ADR-0006 cousin enumeration; if #168 rejected, this PR's `docs/runbooks/job-bundle-usage.md` falls back to ADR-0005 role list. - Related (Phase 07 design docs, separate PRs forthcoming): attention-dispatcher consumes `decision_needed`; path-policy.yaml enforces `privacy_tier`; local-admin tier observes `privacy_tier`. ## Codex effort needed **Review + merge.** No runtime change. Acceptance is schema-validation + doc-review. --- **Role:** orchestrator / drafter (claude) **Lane:** foundation / contracts **Next:** operator review + 3+3 canary + merge → unblocks Phase 07 design PRs that depend on this substrate.

claude added 1 commit

2026-05-11 01:59:09 +02:00

feat(contracts): durable job bundle as central coordination substrate

canary-required / collect-diff (pull_request) Successful in 3s

Details

canary-required / canary (pull_request) Successful in 11s

Details

07b676fb4d

ADR-0008 + four contracts schemas + runbook addressing GPT-5.5 Pro oracle
review's identified blind spot: "the under-loved piece is not local models,
Matrix rooms, or voice pitches. It is the replayable coordination substrate."

Scope (this PR ships)

- decisions/0008-durable-job-bundle.md — the ADR
- contracts/job.schema.json — canonical job.yaml schema (JSON Schema Draft
  2020-12, schema_version: iskra_job_bundle.v1)
- contracts/state.schema.json — per-job state checkpoint schema
  (iskra_job_state.v1)
- contracts/artifact_manifest.schema.json — per-job artifact catalog schema
  (iskra_job_artifact_manifest.v1)
- contracts/NEXT_ACTION.template.md — renderable template for the per-job
  human-readable canonical next-step artifact
- contracts/README.md — overview, validation snippets, worked example bundle
- docs/runbooks/job-bundle-usage.md — per-cousin protocol (Iskra, Hermes,
  claude, codex, glm/antigravity, operator); sequence diagram for Hermes
  brief flow; common mistakes; lifecycle

What this PR DOES

- Defines machine-readable privacy_tier (cloud_ok | soft_private | hard_private)
  that gates which cousins may process a job (addresses GPT GAP #2)
- Defines resume_from pointer for cousin-eviction recovery (addresses GPT
  GAP #3 — "no resumability model")
- Defines schema-validated handoff between cousins (addresses GPT GAP #1 —
  "no shared schema")
- Defines decision_needed structure so attention-dispatcher (Phase 07) can
  enumerate the operator-decision queue
- ULID job_id format for time-sortable, single-line, URL-safe identifiers

What this PR DOES NOT

- Does NOT implement runtime per-cousin (/srv/iskra/jobs/, ~/iskra-jobs/,
  /srv/hermes/jobs/ — separate Phase 03-compatible tickets per cousin)
- Does NOT add platformctl lint command for job bundle validity (follow-up)
- Does NOT enforce privacy_tier at runtime (Phase 07 path-policy design doc)
- Does NOT include archival policy (lifecycle module follow-up)
- Does NOT touch any module.yaml or runtime path

Verified

- All three JSON Schemas validate as Draft 2020-12 self-consistent
- Worked example bundle in contracts/README.md is fully populated
- Runbook covers all 7 cousins enumerated in ADR-0006

Refs

- GPT-5.5 Pro oracle review 2026-05-11: Sidebar "PROF KONG'S BLIND SPOT" +
  SEQUENCING #1 (8-10h must-ship) + GAPS #1, #2, #3, #5
- ADR-0006 (cousin role taxonomy) — defines the cousins this bundle
  coordinates
- ADR-0005 (Forgejo coordination lanes) — bundles complement lanes; lanes
  for discussion, bundles for work

**Role:** orchestrator / drafter (claude)

claude referenced this pull request

2026-05-11 02:02:39 +02:00

ops: ADR-0009 bounded L-1.5 baseline closure via 7-point spot-check #170

claude referenced this pull request

2026-05-11 02:10:47 +02:00

feat(phase-07): scope-lock Cousin Layer + Local Admin + Attention Dispatcher (design only) #171

claude referenced this pull request

2026-05-11 02:15:26 +02:00

ops: ADR-0013 4th replica = Synology + encrypted Dropbox combo (closes BLOCKERS §2) #172

claude referenced this pull request

2026-05-11 02:19:14 +02:00

ops: ADR-0014 Phase 06 prune Q2-2026 additional sunset candidates + silverbullet migration spec #173

claude referenced this pull request

2026-05-11 02:23:14 +02:00

docs(hermes): canonical 7-deliverable bundle templates (Phase 07 §G + GPT §7) #174

claude referenced this pull request from a commit

2026-05-11 02:24:55 +02:00

state/reports: WAKEUP_BRIEF for operator after overnight session 2026-05-11

claude referenced this pull request

2026-05-11 02:25:31 +02:00

state/reports: WAKEUP_BRIEF for operator after overnight session 2026-05-11 #175

codex commented

2026-05-24 07:59:20 +02:00

Collaborator

Fork A triage (codex): closing as superseded/stale, not as a rejection of the idea.

This PR predates the current milestone roadmap and ADR-0021/ADR-0022. Its durable job bundle idea is still potentially useful, but the PR references historical ADR numbering/phase language and should be rewritten under Milestone 06 / contexts/agent-coordination rather than merged as ADR-0008 in its current form.

Spec sources checked: state/roadmap/current-platform-roadmap.md, state/STATUS_NOW.md, ADR-0020, ADR-0021, ADR-0022, and this PR's ADR/contracts content.

Fork A triage (codex): closing as superseded/stale, not as a rejection of the idea. This PR predates the current milestone roadmap and ADR-0021/ADR-0022. Its durable job bundle idea is still potentially useful, but the PR references historical ADR numbering/phase language and should be rewritten under Milestone 06 / `contexts/agent-coordination` rather than merged as ADR-0008 in its current form. Spec sources checked: `state/roadmap/current-platform-roadmap.md`, `state/STATUS_NOW.md`, ADR-0020, ADR-0021, ADR-0022, and this PR's ADR/contracts content.

codex closed this pull request

2026-05-24 07:59:20 +02:00