Skip to content

docs(adr): resolve ADR-0031 open questions (proposal, stays Proposed) - #187

Open
avalla wants to merge 23 commits into
mainfrom
docs/adr-0031-open-questions
Open

avalla wants to merge 23 commits into
mainfrom
docs/adr-0031-open-questions

Conversation

@avalla

@avalla avalla commented Oct 16, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • Records the owner's decisions on the three open questions of ADR-0031: a new delivery-run aggregate with an optional pipeline-run reference, evidence stored as reference and hash only, and no rejection of a head commit the Runtime cannot see.
  • Documents the existing delivery state that predates the ADR: delivery:setup:* storage (migration 0050_task_delivery_setup, M19-T4) and the file checkpoint store (M19-T2).
  • Proposes answers to the two remaining questions, reviewed by an independent reviewer: a separate aggregate beside delivery:setup:* with an immutable snapshot of the resolved configuration, and a complementary relation to the file checkpoint store with an idempotent, conflict-explicit reconciliation protocol and conservative resume.
  • Documents the local file-store portability limit as a known limitation.

Scope

Documentation only, one file: docs/adr/ADR-0031-runtime-owned-delivery-state.md. The ADR stays Proposed; this PR is the review and approval point for the proposal. No code, migration or Runtime behavior changes.

Validation

  • git diff --check clean.
  • bun run check not run: documentation-only change.

Review focus

  • Is the aggregate separation from delivery:setup:* the intended direction?
  • Is the checkpoint reconciliation protocol (publish, register idempotently, conflict on hash mismatch, fail explicitly on resume) acceptable?
  • Accepting the ADR accepts these answers.

🤖 Generated with Claude Code

https://claude.ai/code/session_011c1gCVpVzPiTk9yVgUSiMU

Hardening update (2026-10-19) - HEAD f6b7b02

Documentation only; ADR-0031 stays Proposed and no owner decision was made.

  • Invariant 1 allowed setting the pipeline run reference once after creation, but the Decision lists no operation for it: now stated explicitly and left to the implementation plan and the owner.
  • The ADR credited task-delivery-config.ts with reading the Runtime setup; the reader is setup-resolution.ts (delivery:setup:show), now named correctly.
  • Prettier conformance of the file restored (the base file was conformant).

Evidence: bun run check exit 0 on f6b7b02 (3455 passed, 239 skipped; one earlier run failed on the timing-bound dashboard-task-graph test under concurrent load, a file this PR does not touch, and it passes 3/3 in isolation); GitHub CI 13/13 green; git diff --check clean. Independent read-only review: 1 P3 (the script name), fixed.

Still for the owner, unchanged: Question A (abandoning a creation-pending marker) and Question B (a creation conflict naming the existing run). Merging this PR is not acceptance of the ADR.

External review (Codex): not satisfied on the final head. The Codex CLI and the GitHub connector are unavailable (usage limit); no other review stands in for it. The independent review below is by a subagent of the same model family, not Codex.

avalla and others added 2 commits October 15, 2026 18:54
Resolve the three open questions (new delivery-run aggregate with an optional
pipeline-run reference, evidence stored as reference and hash only, no
rejection of an unseen head commit) and document the existing delivery state
(delivery:setup:* storage and the file checkpoint store). Two questions on the
relation to that state remain open. The ADR stays Proposed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011c1gCVpVzPiTk9yVgUSiMU
Propose a separate delivery-run aggregate beside delivery:setup:*, with an
immutable snapshot of the resolved configuration, and a complementary
relation to the file checkpoint store with an idempotent, conflict-explicit
reconciliation protocol and conservative resume. Document the local
file-store portability limit. The ADR stays Proposed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011c1gCVpVzPiTk9yVgUSiMU
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 16, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-16T09:49:37.017864Z 7100944 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a1ef025447

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/adr/ADR-0031-runtime-owned-delivery-state.md
Comment thread docs/adr/ADR-0031-runtime-owned-delivery-state.md Outdated
Comment thread docs/adr/ADR-0031-runtime-owned-delivery-state.md Outdated
avalla and others added 2 commits October 16, 2026 10:15
Require same-project and same-task validation when a delivery run links a
pipeline run, keep delivery gates and pipeline stages independent with no
implicit mapping, specify the immutable configuration snapshot alongside the
dynamic floor, and require a durable pending marker so retention never prunes
an unregistered checkpoint. The ADR stays Proposed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011c1gCVpVzPiTk9yVgUSiMU
Make the pending marker durable before publication so a crash cannot leave an
unregistered checkpoint prunable, and limit pending to checkpoints of a
Runtime delivery run so offline retention is unchanged. Verify task-to-project
ownership at creation, define the set-once pipeline link and the registration
identity, report whether an enforced pipeline governs the task independently
of the link, record gate forms in the snapshot and floor additions, never
label delivery:next as effective, and correct the lowering-below-floor rule.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011c1gCVpVzPiTk9yVgUSiMU
@avalla

avalla commented Oct 16, 2026

Copy link
Copy Markdown
Owner Author

@codex review

Review the head 33eca25. Scope: documentation only, docs/adr/ADR-0031-runtime-owned-delivery-state.md. The three earlier findings (project and task validation when linking a pipeline run, independence of pipeline stages and delivery gates, and retention of unregistered checkpoints) are addressed by invariants 1, 2 and 4, and invariant 3 covers the immutable snapshot with the dynamic floor. The ADR stays Proposed.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 33eca25ccd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/adr/ADR-0031-runtime-owned-delivery-state.md Outdated
Comment thread docs/adr/ADR-0031-runtime-owned-delivery-state.md Outdated
avalla and others added 2 commits October 16, 2026 10:50
…tions

Define how a delivery run is created: the client sends the resolved
configuration as data, the Runtime re-validates it and never reads
caller-local files, and the snapshot is recorded as claimed. Note that
delivery:setup:* does not hold the profile or gate selection. Make floor
additions durable pending entries with an idempotent identity that a reset or
handoff carries, so a failed registration cannot make a required gate be
forgotten. The ADR stays Proposed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011c1gCVpVzPiTk9yVgUSiMU
Record whether an external review command is configured in the snapshot,
state that delivery:setup:* keys stay outside it, keep floor additions
append-only in the file store so an outage cannot lose a registered one, keep a
task on the Runtime path once a run exists, define at most one open run per
task with reported handling of a superseded run's pending items, and clarify
floor-addition identity, handoff listing, refusal ownership and the canonical
hash. The ADR stays Proposed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011c1gCVpVzPiTk9yVgUSiMU
@avalla

avalla commented Oct 16, 2026

Copy link
Copy Markdown
Owner Author

@codex review

Review the head 20a31ff. Scope: documentation only, docs/adr/ADR-0031-runtime-owned-delivery-state.md. Since 33eca25: invariant 5 defines how run creation obtains the profile and gate snapshot (client-supplied data, re-validated by the Runtime, no caller-local file reads), and invariant 3 now keeps floor additions as durable, append-only, idempotent entries that a handoff carries, with the Runtime path, run multiplicity and external-review presence flag specified. The ADR stays Proposed.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 20a31ff6bf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/adr/ADR-0031-runtime-owned-delivery-state.md Outdated
Add the floor additions already determined for a task to the creation input,
validated like any other and registered atomically with the run, so a run
created part-way through a task cannot start without the gates its floor
already required. The ADR stays Proposed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011c1gCVpVzPiTk9yVgUSiMU
@avalla

avalla commented Oct 16, 2026

Copy link
Copy Markdown
Owner Author

@codex review

Review the head 0260bc7. Scope: documentation only, docs/adr/ADR-0031-runtime-owned-delivery-state.md. Since 20a31ff: invariant 5 now accepts the floor additions already determined for the task in the creation input, validated like any other and registered atomically with the run, so a run created part-way through a task cannot start without the gates its floor already required. The ADR stays Proposed.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0260bc7171

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/adr/ADR-0031-runtime-owned-delivery-state.md Outdated
avalla and others added 3 commits October 16, 2026 11:25
…n field

Require the complete set of inherited floor additions in the creation input
(explicitly empty when none), require the client to read its local state
before creating a run, and state that completeness is a client obligation the
Runtime cannot verify, with an omission caught at the next floor evaluation
point. The ADR stays Proposed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011c1gCVpVzPiTk9yVgUSiMU
Drop part-way run creation and run supersession, which required inheriting
floor determinations the offline handoff packet does not record. A task has one
delivery run, created at preflight, so no floor additions or checkpoints exist
to inherit; migrating an offline task or adopting a changed configuration
mid-task is left to a separate decision. Also define "client" as the skill
acting through the CLI, state that no command removes a recorded addition,
state the floor-entry packet property instead of a mechanism, and restrict
clearing a pending marker to a successful registration. The ADR stays Proposed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011c1gCVpVzPiTk9yVgUSiMU
…re outcome

Make creation idempotent on project, task and snapshot hash so a retry after a
lost reply is safe, state that an unreachable Runtime or failed creation at
preflight leaves the task on the offline path, order creation before the
preflight floor evaluation, give a run a terminal state, align Decision 2, and
extend the known limitations to unregistered floor entries and delivery
restarts. The ADR stays Proposed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011c1gCVpVzPiTk9yVgUSiMU
@avalla

avalla commented Oct 16, 2026

Copy link
Copy Markdown
Owner Author

@codex review

Review the head d73e790. Scope: documentation only, docs/adr/ADR-0031-runtime-owned-delivery-state.md. Since 0260bc7: the ADR is simplified so a task has one delivery run, created at the start of preflight, which removes part-way creation, inherited floor additions and run supersession. Run creation is idempotent on project, task and snapshot hash, an unreachable Runtime at preflight leaves the task on the offline path, and the known limitations record what is not covered. The ADR stays Proposed.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d73e7902cb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/adr/ADR-0031-runtime-owned-delivery-state.md Outdated
Comment thread docs/adr/ADR-0031-runtime-owned-delivery-state.md Outdated
Comment thread docs/adr/ADR-0031-runtime-owned-delivery-state.md Outdated
Make a creation-pending marker durable before a creation request so an
uncertain outcome blocks checkpoints and gates until an idempotent retry shows
whether a run exists, limit the offline fallback to a Runtime confirmed
unreachable with no request sent, treat typed rejections as stop conditions, and
compare the complete creation payload (including the pipeline run reference)
for idempotency. The ADR stays Proposed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011c1gCVpVzPiTk9yVgUSiMU
@avalla

avalla commented Oct 16, 2026

Copy link
Copy Markdown
Owner Author

@codex review

Review the head 7100944. Scope: documentation only, docs/adr/ADR-0031-runtime-owned-delivery-state.md. Since d73e790: the skill writes a durable creation-pending marker before a creation request; an uncertain outcome blocks checkpoints and gates until an idempotent retry shows whether a run exists; the offline fallback applies only when the Runtime is confirmed unreachable and no request was sent; typed rejections are stop conditions; creation is idempotent on the complete payload including the pipeline run reference. The ADR stays Proposed.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 71009443fb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/adr/ADR-0031-runtime-owned-delivery-state.md Outdated
…ation-pending marker

The marker now holds the complete creation payload and an uncertain-outcome
retry replays exactly that payload, so a changed configuration or pipeline
link cannot turn the retry into a conflict or a divergent run.

Claude-Session: https://claude.ai/code/session_01Q21NUKiVwrCvpZ5YgzjM5W
…r questions

Stop list now names not found as including ownership; a creation conflict and
a marker whose outcome is never learned are explicit limitations with two
open owner questions. Marker replay is not a creation, and the handoff packet
lists the marker.

Claude-Session: https://claude.ai/code/session_01Q21NUKiVwrCvpZ5YgzjM5W
…flict reply

Question A: an approval cannot prove that no delivery run exists, so no abandon
command is recommended; the idempotent retry resolves the marker, and a lost
Runtime is a separate authority-rebind decision. The conditions any abandon
must meet are listed. Question B: a conflict may identify the existing run
(same project and task only, read-only); adoption is a separate explicit,
audited, compatibility-checked step and never automatic. ADR-0031 stays Proposed.

Claude-Session: https://claude.ai/code/session_01FKM37BV4LS8Rc8ny5GCwXy
…h invariant 3

The offline rule now excludes tasks holding a creation-pending marker or a
creation stop. Replay compares the immutable recorded creation payload and an
exact match returns the run before re-validation. Question B states that it
amends invariant 3 (a conflict keeps the marker). The abandon conditions name
the nonce cost and the undefined authorization; adoption compares the stored
marker payload, not the current configuration.

Claude-Session: https://claude.ai/code/session_01FKM37BV4LS8Rc8ny5GCwXy
… persist creation stops

Review hardening. The marker records the identity of the Runtime the request
was addressed to, and a retry answered by another Runtime is refused, so a
replacement Runtime cannot resolve the old authority's marker. A typed
rejection writes a durable creation-stop record before the marker is cleared,
so a restart or handoff still finds the stop and never classifies the task as
offline.

Claude-Session: https://claude.ai/code/session_01FKM37BV4LS8Rc8ny5GCwXy
…a creation stop

Review hardening. The rule that forbids creating a run once a handoff packet
exists now exempts the retry of a recoverable creation stop (validation or not
found), so the documented correct-and-retry path is not turned into a permanent
stop by the handoff. A conflict stop stays unrecoverable by retry.

Claude-Session: https://claude.ai/code/session_01FKM37BV4LS8Rc8ny5GCwXy
A crash after the pending marker and before publication left a marker with
nothing to register. Such an unpublished intent is republished or recorded as
cancelled, reported, and then cleared; no pinning guarantee for published
checkpoints changes.

Claude-Session: https://claude.ai/code/session_01FKM37BV4LS8Rc8ny5GCwXy
@avalla

avalla commented Oct 19, 2026

Copy link
Copy Markdown
Owner Author

Update for head 21ddb66 (docs only, ADR-0031 stays Proposed): Question A (no abandon command recommended; safe-recovery conditions listed) and Question B (conflict may name the same-project run read-only; adoption separate, explicit, never automatic) are presented for owner decision. Review fixes: offline rule excludes pending/stop tasks, replay compares the recorded payload, creation stop persisted before clearing the marker, retry bound to the original Runtime identity, recovery of unpublished checkpoint intents. Evidence: bun run check exit 0, CI green (13/13), independent architect review, Codex static review of the diff text (final pass: no findings).

@avalla avalla left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent ChatGPT ADR review — HEAD 21ddb66 (static source review, not Codex CLI)

Technical verdict: no newly confirmed P1/P2 contradictions in the reviewed proposal. Reviewed the creation-pending and creation-stop records, stored canonical creation payload, Runtime identity pinning, idempotent replay, checkpoint registration and retention, cross-project pipeline ownership and the separation between delivery gates and pipeline stages. The revised draft addresses the previous reported ambiguities as proposed future invariants.

Owner decisions still open, not silently approved: Question A (no unsafe abandon/offline fallback under uncertain creation) and Question B (whether a same-project conflict may disclose the existing run, with any adoption separate and explicit). Keep ADR-0031 Proposed until the owner decides; merging a proposal is not acceptance or implementation.

Evidence: GitHub workflows on this HEAD are green. I did not execute the implementation tests locally (documentation-only PR). The PR description's consolidation note names an earlier HEAD and should be updated.

Gate: This is not a successful repository-aware Codex CLI review; the configured external-review requirement is separately pending.

…decided

Invariant 1 allowed the pipeline run reference to be set once after creation,
but the Decision lists no operation that does it. Say so explicitly and leave
the operation, and whether it exists, to the implementation plan and the
owner. Also restore Prettier conformance of the file, which the proposal had
lost. The ADR stays Proposed.

Claude-Session: https://claude.ai/code/session_01FKM37BV4LS8Rc8ny5GCwXy
The ADR said the skill reads the Runtime-stored setup through
task-delivery-config.ts, which only validates the local YAML. The reader is
setup-resolution.ts, which runs delivery:setup:show. Name both correctly.

Claude-Session: https://claude.ai/code/session_01FKM37BV4LS8Rc8ny5GCwXy
@avalla

avalla commented Oct 19, 2026

Copy link
Copy Markdown
Owner Author

Hardening cycle closed on f6b7b02: two documentation inconsistencies fixed (undefined post-creation link operation; wrong script named for the Runtime setup reader). No owner decision made, ADR stays Proposed; Questions A and B remain for the owner. bun run check exit 0 (3455 passed; one earlier run hit a load-sensitive timing test in an untouched file, 3/3 pass in isolation), CI 13/13. Codex gate: not satisfied.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant