Skip to content

workflow(meta): key delivery on agent context; retire checkpoint-at-entry (#353 corpus) - #355

Merged
m2ux merged 7 commits into
workflowsfrom
workflow/353-context-scoped-delivery
Jul 30, 2026
Merged

workflow(meta): key delivery on agent context; retire checkpoint-at-entry (#353 corpus)#355
m2ux merged 7 commits into
workflowsfrom
workflow/353-context-scoped-delivery

Conversation

@m2ux

@m2ux m2ux commented Jul 30, 2026

Copy link
Copy Markdown
Owner

Corpus half of #353 (§2.1, §2.2). Merge this first — the server PR (#356, fix/353-dispatch-overheadmain) carries §2.3's pointer bump, so the relaxed rule reaches the server only through that gitlink and never goes live without the context-scoped ledger underneath it.

§2.1 — delivery keyed on agent context

workers-need-full-delivery was not the defect; the ledger was. It read state.deliveredContent[state.agentId], and a dispatched worker authenticates against the orchestrator's session_index — so every worker of a session shared one ledger, and reference delivery on a worker session would have handed worker B unchanged-markers for content worker A received. The rule was a correct guard over a ledger that could not tell contexts apart. The server PR scopes that ledger on a per-call agent_id, so the rule can now key on the question that matters: is this the same agent context?

Surface Change
workflow-engine::TECHNIQUE.md new agent-id-scopes-delivery — the authoritative statement: pass agent_id on the three delivery calls; a fresh id takes full delivery, the same id resumed may pass bundle: "reference"
workflow-engine::dispatch-activity workers-need-full-deliverydelivery-keys-on-agent-context, rewritten to the orchestrator-side duty: mint per dispatch, reuse on resume, keep context_mode: "persistent" off worker sessions
workflow-engine::activity-worker agent-id-on-delivery-calls, mirroring the existing session-index-on-each-call shape
workflow-engine::compose-prompt the worker's entry instruction becomes get_activity { session_index, context_tokens, agent_id }
harness-compat::continue-agent resume-preserves-delivery-scope — the resume re-binds the workflow-server worker agent_id, called out as distinct from the harness {agent_id} this op resumes

agent_id is not a new designator: activity-worker already declares it ("Worker agent identity for this dispatch"), compose-prompt already requires it in {substitutions}, and dispatch-activity already binds it into the stub. It simply never reached the wire. force-full-after-summarization stays the escape and is cited, not restated at both call sites.

Rule renamed rather than left contradicting its body; all four citation sites updated (TECHNIQUE.md#dispatch-topology, workflow-orchestrator, create-session, and the definition). check:anchors proves they resolve.

§2.2 — no activity opens with a checkpoint

The issue named 11-validate. The new guard found four. Each relocation keeps the checkpoint atomic (no combining — atomic-checkpoints) and preserves reachability exactly:

Workflow Checkpoint Moved to Why there
work-package local-validation-permission 10-post-impl-review tail, gated has_critical_blocker != true validate's only predecessor; the gate is the exact complement of the blocker branch, so producer and readers stay exhaustive (unproduced-value-read)
prism-evaluate confirm-apply 05-resolution-dialogue tail after compile-plan produces the plan the confirmation is about
work-packages analysis-type-selection 02-folder-setup, before folder-created folder-created's options carry the routing effects, so it stays the activity's last step
workflow-design design-context after set-design-dimensions, same activity see below

Why design-context moves within its activity rather than to the predecessor's tail: requirements-refinement is reachable on more than one transition condition from 01-intake-and-context, so relocating would have required duplicating those conditions at the predecessor — a state shadow for no gain. It is non-blocking with a defaultOption and autoAdvanceMs, so it forces no resume where it now sits; moving it off step 0 satisfies the guard and keeps its operation_type != update gate untouched.

One subtlety worth review attention. local-validation-permission used to set both run_local_validation and mark_progress_na. mark_progress_na is consumed by commit-and-persist at the completing activity and then reset — so setting it in post-impl-review would have marked that activity cancelled/N/A instead of validate. The relocated checkpoint therefore sets run_local_validation only, and 11-validate derives the flag itself in a first kind: action step gated when: run_local_validation == false. Same observable Progress behaviour, correct owner.

Restatement sweep

stale-restatement-after-change applies to a relocation. Swept and updated in this commit: activity and root READMEs for all four workflows, including the mermaid flows that drew the moved gates (work-package/activities/README.md validate + post-impl-review diagrams, prism-evaluate 05/06 sections and root flow + roster, work-packages folder-setup/analysis diagrams, workflow-design/activities/README.md ordering clause).

Verification

  • npm run check:all18/18 guards pass, including the new checkpoint-entry guard, resource-anchors (the renamed rule's citations), variable-model (the relocated setVariable effects), and review-mode-gating.
  • Full server suite green against this corpus, with the walk re-baselined in the server PR. The snapshot delta is the relocation and nothing else.

🤖 Generated with Claude Code

…ty entry

Corpus half of #353. Merges before the server PR bumps the pointer to it.

Delivery mode keyed on agent context (#353 2.1)
-----------------------------------------------
workers-need-full-delivery was a correct guard over a ledger that could not
tell worker contexts apart: it read session.agentId, shared by every worker
dispatched against a session, so reference delivery on a worker session would
have handed worker B unchanged-markers for content worker A received. The
server now scopes the ledger on a per-call agent_id, so the rule can key on
the question that actually matters — is this the same agent context?

- workflow-engine::TECHNIQUE.md gains agent-id-scopes-delivery, the
  authoritative statement: pass agent_id on the three delivery calls; a fresh
  id takes full delivery, the same id resumed may pass bundle: "reference".
- dispatch-activity's rule is renamed delivery-keys-on-agent-context and
  rewritten to the orchestrator-side duty (mint per dispatch, reuse on resume,
  keep context_mode: persistent off worker sessions). Every citation updated:
  TECHNIQUE.md#dispatch-topology, workflow-orchestrator, create-session.
- activity-worker and compose-prompt carry agent_id onto the worker's calls;
  continue-agent states that a resume preserves the delivery scope.
- force-full-after-summarization stays the escape and is cited, not restated.

No checkpoint opens an activity (#353 2.2)
------------------------------------------
The issue named 11-validate; the new guard found four. Each relocation keeps
the checkpoint atomic and preserves reachability exactly:

- work-package validate -> post-impl-review tail, gated has_critical_blocker
  != true (the complement of the blocker branch, so the gates stay
  exhaustive). It sets run_local_validation only: mark_progress_na is
  consumed by commit-and-persist at the COMPLETING activity, so setting it in
  post-impl-review would have marked that activity N/A instead of validate.
  validate derives it from run_local_validation in a first action step.
- prism-evaluate apply-mitigations -> resolution-dialogue tail, after
  compile-plan produces the plan the confirmation is about.
- work-packages analysis -> folder-setup, before folder-created, whose
  options carry the routing effects and stay the activity's last step.
- workflow-design requirements-refinement: design-context moves after
  set-design-dimensions rather than to the predecessor's tail —
  requirements-refinement is reachable on more than one transition condition,
  and relocating would have needed those conditions duplicated at the
  predecessor. It is non-blocking with an auto-advance default, so it costs no
  resume where it now sits.

Restatements swept in the same edit: activity/workflow READMEs for all four
workflows, including the mermaid flows that drew the moved gates.

18 guards pass, including the new checkpoint-entry guard.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@m2ux
m2ux force-pushed the workflow/353-context-scoped-delivery branch from 8e6d948 to dcbbb2a Compare July 30, 2026 07:03
resource-section-or-whole covered the two delivery keys as they behave under explicit
get_resource fetches, which left the eager bundle unstated: a delivered whole resource
carries its own sections, so a technique citing a resource both ways receives the file
alone and reads the section out of that body.

Without the clause the rule reads as though a section always arrives under its own key,
and an agent finding no entry for one would fetch what it already holds.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
m2ux and others added 5 commits July 30, 2026 11:20
Two files needed a decision; the rest auto-merged.

workflow-orchestrator's orchestrator-worker-boundaries lists the dispatch rules an
orchestrator honours, and each branch had changed a different entry: this one renamed
workers-need-full-delivery to delivery-keys-on-agent-context, while #346 folded
worker-bag-takes-precedence into distrust-then-reconcile. The list carries both
outcomes, and both anchors resolve in the merged dispatch-activity.

dispatch-activity's version was bumped on both sides from a common ancestor; 1.11.0
covers this branch's changes sitting on top of #346's.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Four rules read as instructions — "Pass agent_id on...", "Mint a worker agent_id per
dispatch", "Load each step's bound technique as you reach it" — which is a Protocol
phase wearing a rule's clothes. Each could have stood as a numbered step unaltered,
which is the test AP-19 applies.

They stay in Rules, because each constrains every delivery call an operation makes
rather than one phase of it, and a container TECHNIQUE.md has no Protocol to hold a
phase. What changes is the mood: agent-id-scopes-delivery, agent-id-on-delivery-calls
and progressive-step-technique-load now state what holds of a call and its response.

delivery-keys-on-agent-context loses two clauses outright. Minting an agent_id per
dispatch is dispatch-activity's Protocol step 3, and reusing it on resume is step 4's
caveat, so the rule was restating phases that already own the work. The invariants
remain — one context per worker, a fresh context takes full delivery, a retry's new
worker is a new context — as does the prohibition on session-wide persistent mode.

Left as they are: follow-bundled-rules, which is where AP-121 says a "follow X
throughout" duty belongs; session-index-on-each-call and orchestrator-worker-boundaries,
which carry cross-cutting constraints citing the home that owns each; and
validation-warnings and resource-section-or-whole, which state a standing duty and a
choice policy no single phase can hold.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Seven sequential nodes with no branch between them occupied most of the diagram's
height and told a reader nothing a single block does not: resolving host_repo_path,
updating repo-root submodules, the GitNexus analyze, the commit-signing check, and
detecting merge strategy, project type and an existing issue.

They are one block now, so the checkpoints and the review-mode fork — the places the
activity actually branches or stops for the user — carry the diagram.

Only update-repo-submodules is gated, on host_repo_path existing, which the step before
it sets; the diagram drew it unconditionally already.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Both setup runs are one block each, named for what they establish rather than listing
the steps that establish it. An enumeration inside a node is the sequence it replaced,
written sideways; a reader who wants the steps reads the YAML this section links.

The second run collapses the planning-folder bind, its README, the problem overview, the
branch-name derivation, the target_path computation, the worktree creation and the
branch and PR checks. Binding the folder path was a node of its own that the block's
own name already covers, so both edges that reached it now reach the block.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…one block

Ten runs across nine activity diagrams were chains where nothing branched, nothing
merged and no checkpoint stopped for the user — height without information. Each is one
block named for what the run establishes.

The assumptions cycle drove most of it: collect, write the document, update the log,
reconcile, present. It recurs in design-philosophy, requirements-elicitation, research
and implementation-analysis, and each of those now carries it as a single "record X and
reconcile its assumptions" block. plan-prepare's run was nine nodes, from creating the
plan through to rendering the PR description.

Loop bodies collapse the same way and keep their edge: comprehension's targeted
deep-dive returns to the sufficiency checkpoint, and validate's diagnose-fix-rerun
returns to its failure gate.

The two activity-to-activity flows in README.md and REVIEW-MODE.md keep every node.
There the nodes are the activities, so a run of them is the diagram's subject rather
than filler.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@m2ux
m2ux merged commit 6bc46fa into workflows Jul 30, 2026
m2ux added a commit that referenced this pull request Jul 30, 2026
Three files needed a decision; workflow-tools.ts, the state schema, the site tools page,
the walk snapshots and mcp-server.test.ts all auto-merged.

AGENTS.md held two versions of "Describe the design, not the change to it" — this branch
and #357 wrote it independently, with different carve-outs. The rule now carries both:
main's PR and issue bodies alongside this branch's commit body and provenance-bearing
measurement, plus the live-hazard-as-invariant guidance and the link to principle 17.
CLAUDE.md takes the same union, since this branch had only edited its twin and the two
are kept in sync by merging.

The worktree-naming rule rides in here too. It was committed to
docs/agent-authoring-guidance after #357 had already merged at 618d9ff, so it never
reached main and would have been lost with the branch.

The workflows pointer moves to 6bc46fa, the corpus tip carrying both #351 and #355, and
the stamp names the same commit.

binding-fidelity passes: main's detector predicate and reconciled triage arrive with this
merge, which is what the 17 stale entries on this branch were waiting for.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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