coilyco-flight-deck/agentic-os

Fork 0

Define the `blocked-on-dependency` contract: marker syntax, blocker pointer, and wake semantics #394

New issue

Closed

opened 2026-07-09 21:49:52 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-07-09 21:49:52 +00:00

Member

Why

blocked-on-dependency is already named in the prioritization docs, but only as vocabulary. The enforcement issue now needs a stable cross-repo contract so ward can implement detection and wake behavior without inventing ad-hoc semantics in code.

This issue is the upstream dependency for the corresponding ward implementation issue. ward should not ship classifier/pre-flight/wake behavior until this contract is frozen, because otherwise the metadata shape will drift.

Decide here

Freeze the product contract for all of the following:

Source of truth for the blocker pointer
- Recommendation: a machine-readable marker in the issue body or a dedicated bot comment.
- Example shape: 
- Labels alone are not enough because they cannot precisely encode the upstream ref.
Readiness semantics
- blocked-on-dependency stays a readiness property, not an automation mode.
- The common shape remains headless + blocked-on-dependency.
- If no concrete blocker ref is present, the issue must fail closed and not claim wake behavior.
Wake trigger semantics
- Recommendation for v1: wake when the pointed-to issue closes.
- Do not broaden v1 to release tags, PR merges, or generic events unless the pointer syntax explicitly models them.
Classifier contract
- A classifier may apply blocked-on-dependency only when it can name a concrete upstream ref.
- Otherwise it should leave the issue as ordinary mode/tier output and not imply auto-resume.

Acceptance

automation-mode-axis.md and/or readiness-axis.md define the final marker shape and wake rule.
The docs say explicitly where the blocker pointer lives and what exact event wakes dependents.
The docs say explicitly that blocked-on-dependency rides alongside a mode label and does not replace it.
The docs say explicitly that missing/ambiguous blocker refs fail closed.

Notes from research

The original motivating case, ward#124, is already closed as of 2026-07-09, so the contract should not overfit that one example.
ward already has a durable backlog ledger and re-queue machinery, so the missing piece is mostly the metadata contract, not queue invention.

Downstream dependency

The downstream implementation issue in coilyco-flight-deck/ward should wait on this contract landing first. Once this issue is closed, ward can implement classifier detection, pre-flight wording, and wake behavior against a frozen marker format.

Filed by ward agent advisor cross-repo fan-out from coilyco-flight-deck/agentic-os#282 (part 1 of 2, ward#424).

— Codex, via ward agent

## Why `blocked-on-dependency` is already named in the prioritization docs, but only as vocabulary. The enforcement issue now needs a **stable cross-repo contract** so `ward` can implement detection and wake behavior without inventing ad-hoc semantics in code. This issue is the **upstream dependency** for the corresponding `ward` implementation issue. `ward` should not ship classifier/pre-flight/wake behavior until this contract is frozen, because otherwise the metadata shape will drift. ## Decide here Freeze the product contract for all of the following: 1. **Source of truth for the blocker pointer** - Recommendation: a machine-readable marker in the issue body or a dedicated bot comment. - Example shape: `` - Labels alone are not enough because they cannot precisely encode the upstream ref. 2. **Readiness semantics** - `blocked-on-dependency` stays a **readiness** property, not an automation mode. - The common shape remains `headless` + `blocked-on-dependency`. - If no concrete blocker ref is present, the issue must **fail closed** and not claim wake behavior. 3. **Wake trigger semantics** - Recommendation for v1: wake when the pointed-to **issue closes**. - Do not broaden v1 to release tags, PR merges, or generic events unless the pointer syntax explicitly models them. 4. **Classifier contract** - A classifier may apply `blocked-on-dependency` only when it can name a concrete upstream ref. - Otherwise it should leave the issue as ordinary mode/tier output and not imply auto-resume. ## Acceptance - `automation-mode-axis.md` and/or `readiness-axis.md` define the final marker shape and wake rule. - The docs say explicitly where the blocker pointer lives and what exact event wakes dependents. - The docs say explicitly that `blocked-on-dependency` rides **alongside** a mode label and does not replace it. - The docs say explicitly that missing/ambiguous blocker refs fail closed. ## Notes from research - The original motivating case, `ward#124`, is already closed as of **2026-07-09**, so the contract should not overfit that one example. - `ward` already has a durable backlog ledger and re-queue machinery, so the missing piece is mostly the metadata contract, not queue invention. ## Downstream dependency The downstream implementation issue in `coilyco-flight-deck/ward` should wait on this contract landing first. Once this issue is closed, `ward` can implement classifier detection, pre-flight wording, and wake behavior against a frozen marker format. --- Filed by `ward agent advisor` cross-repo fan-out from coilyco-flight-deck/agentic-os#282 (part 1 of 2, ward#424).  — Codex, via `ward agent`

coilyco-ops referenced this issue from coilyco-flight-deck/ward

2026-07-09 21:49:53 +00:00

Implement blocked-on-dependency in triage, pre-flight, and director auto-resume #872

coilyco-ops referenced this issue

2026-07-09 21:49:55 +00:00

Enforce blocked-on-dependency: classifier detection, pre-flight reasoning, auto-resume wake #282

coilysiren referenced this issue from coilyco-flight-deck/ward

2026-07-10 04:03:12 +00:00

ward release race condition #935

coilyco-ops commented

2026-07-10 04:50:14 +00:00

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-codex-agentic-os-394 on host kais-macbook-pro-2.local.

Reserved by ward agent --harness codex (reserved 2026-07-10T04:50:13Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (1h TTL). --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/agentic-os#394 · branch issue-394 · harness codex · workflow direct-main
Run: engineer-codex-agentic-os-394 · ward v0.555.0 · dispatched 2026-07-10T04:50:13Z
Comment thread: 0 included in the pre-flight read, 0 stripped (ward's own automated comments).

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.555.0).

— Codex, via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-codex-agentic-os-394` on host `kais-macbook-pro-2.local`. Reserved by `ward agent --harness codex` (reserved 2026-07-10T04:50:13Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (1h TTL). `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh**. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/agentic-os#394` · branch `issue-394` · harness `codex` · workflow `direct-main` - **Run:** `engineer-codex-agentic-os-394` · ward `v0.555.0` · dispatched `2026-07-10T04:50:13Z` - **Comment thread:** 0 included in the pre-flight read, 0 stripped (ward's own automated comments). Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.555.0). </details> </details>  — Codex, via `ward agent`

coilyco-ops referenced this issue from a commit

2026-07-10 05:03:28 +00:00

docs: freeze blocked-on-dependency contract

coilyco-ops closed this issue

2026-07-10 05:03:28 +00:00

coilyco-ops commented

2026-07-10 05:04:36 +00:00

Author

Member

WARD-OUTCOME: done

details

workflow: direct-main; review summary: review gate skipped by ~/.ward/config.yaml default
retrospective: the contract stayed small once the marker lived only in readiness, but the merge path was noisy because pre-commit kept hitting container temp-space limits
confidence: high
surprise: the remote main moved while the run was in flight, so the landing needed a fresh merge before push
follow-ups: none

WARD-OUTCOME: done <details><summary>details</summary> workflow: direct-main; review summary: review gate skipped by ~/.ward/config.yaml default retrospective: the contract stayed small once the marker lived only in readiness, but the merge path was noisy because pre-commit kept hitting container temp-space limits confidence: high surprise: the remote main moved while the run was in flight, so the landing needed a fresh merge before push follow-ups: none </details>

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

coilyco-flight-deck/agentic-os#394

No description provided.

Rows
Columns

Define the blocked-on-dependency contract: marker syntax, blocker pointer, and wake semantics #394

Why

Decide here

Acceptance

Notes from research

Downstream dependency

Define the `blocked-on-dependency` contract: marker syntax, blocker pointer, and wake semantics #394