workflow(meta): key delivery on agent context; retire checkpoint-at-entry (#353 corpus) - #355
Merged
Merged
Conversation
…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
force-pushed
the
workflow/353-context-scoped-delivery
branch
from
July 30, 2026 07:03
8e6d948 to
dcbbb2a
Compare
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>
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
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Corpus half of #353 (§2.1, §2.2). Merge this first — the server PR (#356,
fix/353-dispatch-overhead→main) 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-deliverywas not the defect; the ledger was. It readstate.deliveredContent[state.agentId], and a dispatched worker authenticates against the orchestrator'ssession_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-callagent_id, so the rule can now key on the question that matters: is this the same agent context?workflow-engine::TECHNIQUE.mdagent-id-scopes-delivery— the authoritative statement: passagent_idon the three delivery calls; a fresh id takes full delivery, the same id resumed may passbundle: "reference"workflow-engine::dispatch-activityworkers-need-full-delivery→delivery-keys-on-agent-context, rewritten to the orchestrator-side duty: mint per dispatch, reuse on resume, keepcontext_mode: "persistent"off worker sessionsworkflow-engine::activity-workeragent-id-on-delivery-calls, mirroring the existingsession-index-on-each-callshapeworkflow-engine::compose-promptget_activity { session_index, context_tokens, agent_id }harness-compat::continue-agentresume-preserves-delivery-scope— the resume re-binds the workflow-server workeragent_id, called out as distinct from the harness{agent_id}this op resumesagent_idis not a new designator:activity-workeralready declares it ("Worker agent identity for this dispatch"),compose-promptalready requires it in{substitutions}, anddispatch-activityalready binds it into the stub. It simply never reached the wire.force-full-after-summarizationstays 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:anchorsproves 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:work-packagelocal-validation-permission10-post-impl-reviewtail, gatedhas_critical_blocker != trueunproduced-value-read)prism-evaluateconfirm-apply05-resolution-dialoguetailcompile-planproduces the plan the confirmation is aboutwork-packagesanalysis-type-selection02-folder-setup, beforefolder-createdfolder-created's options carry the routing effects, so it stays the activity's last stepworkflow-designdesign-contextset-design-dimensions, same activityWhy
design-contextmoves within its activity rather than to the predecessor's tail:requirements-refinementis reachable on more than one transition condition from01-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 adefaultOptionandautoAdvanceMs, so it forces no resume where it now sits; moving it off step 0 satisfies the guard and keeps itsoperation_type != updategate untouched.One subtlety worth review attention.
local-validation-permissionused to set bothrun_local_validationandmark_progress_na.mark_progress_nais consumed bycommit-and-persistat 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 setsrun_local_validationonly, and11-validatederives the flag itself in a firstkind: actionstep gatedwhen: run_local_validation == false. Same observable Progress behaviour, correct owner.Restatement sweep
stale-restatement-after-changeapplies 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.mdvalidate + post-impl-review diagrams,prism-evaluate05/06 sections and root flow + roster,work-packagesfolder-setup/analysis diagrams,workflow-design/activities/README.mdordering clause).Verification
npm run check:all— 18/18 guards pass, including the newcheckpoint-entryguard,resource-anchors(the renamed rule's citations),variable-model(the relocatedsetVariableeffects), andreview-mode-gating.🤖 Generated with Claude Code