fix(#4594): one canonical dispatch-identity owner — the emitted format and the parser that reads it back (#4693)

* fix(#4594): give dispatch identity one owner for the emitted format and its parser

The isolation guards decided whether a run-scoped sentinel applied to a
dispatch by regex-scraping model-authored prose. The scrape returned values in
a different namespace from the ones the sentinel records, so the comparison
could never succeed:

  sentinel  { phase: "03", plan: "03-02-hardening" }   <- $PHASE_NUMBER / $plan_id
  prose     "Execute plan 02 of phase 03-auth."
  scraped   { phase: "03-auth.", plan: "02" }          <- greedy (\S+), both wrong

#4594 reports only the phase half. Measured against a real phase-plan-index
run, plans[].id is phase-prefixed, plan-numbered AND slugged, while the prose
carries a bare in-phase plan number — so the plan field mismatches too, and the
Claude path is dead rather than latent. A fresh sentinel was therefore
discarded on every executor dispatch and every legitimate ISOLATION=none
degrade was denied, leaving the work unrun.

hooks/lib/dispatch-identity.js is now the single owner of both halves. The two
prompt-body producers emit a canonical marker carrying the same shell values
the sentinel records, so producer and consumer agree by construction. The prose
frame stays as a fallback, bounded by the phase-token grammar ADR-2121 owns and
deliberately reporting no plan — an absent identifier means "cannot compare"
and is safe; a wrong one is a false mismatch and is not.

The prose sentence itself is byte-identical: the executor agent reads it too,
so the marker is purely additive (Hyrum's Law).

An inapplicable sentinel is now named in the guards' deny reason instead of
being dropped silently — the silence is why this survived three producers and
two consumers unnoticed. Interpolated values come from a sentinel file and from
prompt text, so both are length-bounded and stripped of control characters.

ADR-4630 locks the seam and maps the epic's three phases.

Refs #4630
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(#4594): resolve eight review findings across the dispatch-identity seam

Three orthogonal review engines ran on 43418af144 — the code-review skill's
Standards and Spec axes, and an isolated adversarial security pass — plus a
self-review of the committed diff. Every finding is fixed here; none deferred.

F1 (major, reproduced). A keyless or unknown-key-only marker — the literal
"[gsd:dispatch]" or "[gsd:dispatch run=..]" — matched the marker grammar and
returned source:'marker' with both fields null, suppressing the prose fallback
entirely. Any prompt text containing that literal silently disabled identity
narrowing, so a fresh sentinel applied to a dispatch it was never scoped to,
defeating #3045 SECURITY F2. Prompt text is attacker-influenceable. A marker
that yields neither recognized key is no longer a marker: the scan continues to
later markers, then later texts, then prose. Forward-compatible tolerance of
unknown keys is unchanged.

F2/F3 (major). The first cut duplicated sanitizeForReason,
describeSentinelDiscard and REASON_INTERPOLATION_MAX_LEN byte-for-byte across
both guards — the exact defect class this epic exists to delete, and with no
cold-load justification, since both hooks already require hooks/lib/. They now
live in hooks/lib/isolation-deny-reason.js, and buildSentinelDiscard lives in
isolation-sentinel.js beside the comparison it mirrors, returning the nested
{sentinel:{phase,plan}, dispatch:{phase,plan}} shape instead of a bespoke
four-field bag that renamed the pairs already flowing through the seam.

F4 (hard violation). The visibility test asserted on the deny reason's prose.
CONTRIBUTING.md prohibits raw text matching on hook output, which is why every
deny carries a stable reason_code. The discard is now a structured
sentinel_discarded field on each hook's stdout JSON, and the test asserts that;
the sentence stays for the operator but is no longer the contract.

F5 (hard violation). The 64-character truncation limit had no boundary
coverage. 63/64/65 are now exercised against the single consolidated helper.

F6 (minor). sanitizeForReason stripped C0/C1 controls but not U+2028/U+2029 or
the bidi overrides, so a crafted value could still reflow or reverse the
message. Both classes are stripped, with a test each.

F7 (major). The producer/template parity test was vacuous — it rendered a
marker and re-parsed its own output, and would have passed with both templates
deleted. It now reads the two workflow templates, extracts each marker line,
substitutes the measured values and asserts the owner's parser returns them.
Proven red by deleting one template's marker line before being proven green.

F8 (doc). ADR-4630 and the design notes claimed the marker is guaranteed on the
orchestrator-worktree path because that prompt is built in shell. It is not:
executor-isolation-dispatch.md:131 says plainly that those are template
placeholders, not shell variables, so {plan_id} is model-substituted there too.
A false guarantee in a design lock is worse than a stated limit. Both documents
now say the marker is model-substituted on both paths and that the prose
fallback is the real floor everywhere. The "3 workflow templates" count was
also wrong — 3 prose sites across 2 files, 2 of which carry the marker.

Refs #4630
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(#4594): refresh the compact-content baseline and acknowledge execute-phase.md growth

Refs #4630.

The dispatch-identity marker and its substitution note grew
gsd-core/workflows/execute-phase.md by 525 bytes (91846 -> 92371), which drifts
two real-tree guards that lint:ci does not run:

- tests/benchmark-compact-content.test.cjs asserts the committed baseline is
  "up to date"; the split for execute-phase.md moved off 25827 -> 25952 and on
  23576 -> 23701, taking its compaction reduction 8.72% -> 8.67%. Baseline
  regenerated with scripts/benchmark-compact-content.cjs --write.
- tests/emitted-attribution.test.cjs requires a growth acknowledgment trailer
  for any emitted file that grows, keyed on the bare filename. Added below.

The growth is two additions and no rewrites: the [gsd:dispatch ...] marker line
inside the Agent() prompt's <objective>, and the note telling the orchestrator
to substitute {plan_id} with the plan's id verbatim. Both are load-bearing --
the marker is what lets a guard hook match a dispatch to the sentinel the
per-plan gate wrote, and without the note the orchestrator has no instruction
telling it the value must not be paraphrased.

Emitted-Drift-Ack-Growth: execute-phase.md — adds the canonical [gsd:dispatch] identity marker and its {plan_id} substitution note, which the isolation guards compare verbatim against the run-scoped sentinel (#4594)
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(#4594): set changeset fragment pr to 4693

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

---------

Co-authored-by: sim <sim@local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-09-13 15:36:08 -04:00
committed by GitHub
parent a155ff4fb6
commit c0b2a05d2f
27 changed files with 1226 additions and 59 deletions

View File

@@ -56,6 +56,7 @@
const fs = require('fs');
const path = require('path');
const { parseDispatchIdentity } = require('./dispatch-identity.js');
// Isolation modes ADR-1239 declares (mirrors gsd-tools.cjs
// routeDispatchIsolation / routeRecordDispatchIsolation).
@@ -223,26 +224,40 @@ function readSentinel(cwd, { clock = Date } = {}) {
}
/**
* #3045 SECURITY F2: extract the `{plan, phase}` a specific Agent()/Task()
* dispatch is FOR, from the one place that data is reliably embedded today —
* the dispatch prompt/description text (`execute-phase.md`'s Agent() block
* uses the literal shape `description="Execute plan {plan_number} of phase
* {phase_number}"`, and the prompt body's `<objective>` repeats "Execute plan
* {plan_number} of phase {phase_number}-{phase_name}." verbatim — the SAME
* text the orchestrator-worktree EXECUTOR_PROMPT template and Cursor's `task`
* field carry, since Cursor dispatches the same prompt content). There is no
* structured per-dispatch kwarg carrying plan/phase identifiers today (#3045
* would need a larger dispatch-protocol change to add one) — this is
* therefore a best-effort, NOT a guaranteed, extraction: a dispatch whose
* text doesn't match the expected shape returns `{ plan: null, phase: null }`
* and the caller must NOT treat that as a mismatch (see
* `sentinelAppliesToDispatch`).
* #3045 SECURITY F2 / #4594: extract the `{plan, phase}` a specific
* Agent()/Task() dispatch is FOR. Variadic — accepts any number of text
* sources (short description, full prompt body, etc) and delegates to
* `hooks/lib/dispatch-identity.js::parseDispatchIdentity`, the one canonical
* owner of both the `[gsd:dispatch phase="…" plan="…"]` marker format and its
* prose fallback (see `.gsd/phase/fix-4594-dispatch-identity-seam/40-design.md`).
*
* MARKER-FIRST CONTRACT: producers embed a structured marker carrying the
* exact shell values the sentinel itself records (`$PHASE_NUMBER`,
* `$plan_id`), so producer and consumer agree by construction, independent
* of how the prose reads or whether a model paraphrases the dispatch
* sentence. Only when no marker is found anywhere in the supplied texts does
* this fall back to scanning for the prose frame "execute plan <token> of
* phase <PHASE TOKEN>".
*
* The prose fallback is now CORRECT-OR-ABSENT rather than possibly-wrong:
* the phase token is bounded by the same grammar `src/phase-id.cts` owns
* (ADR-2121), so a directory-name slug or trailing punctuation can no longer
* leak into the phase value, and the prose plan token is never reported at
* all (it lives in a different namespace than the sentinel's phase-prefixed,
* slugged `plan_id` — reporting it was the #4594 false-mismatch bug).
*
* This is still a best-effort, NOT a guaranteed, extraction: a dispatch that
* carries neither a marker nor a matching prose frame in ANY supplied text
* returns `{ plan: null, phase: null }`, and the caller MUST NEVER treat
* that as a mismatch — see `sentinelAppliesToDispatch`, whose whole
* contract depends on "missing" and "wrong" being distinguishable.
*
* Returns only the two-field `{ plan, phase }` shape existing callers
* depend on — `parseDispatchIdentity`'s `source` field is discarded here.
*/
function extractDispatchIdentifiers(text) {
if (typeof text !== 'string' || text.length === 0) return { plan: null, phase: null };
const m = /execute\s+plan\s+(\S+)\s+of\s+phase\s+(\S+)/i.exec(text);
if (!m) return { plan: null, phase: null };
return { plan: m[1], phase: m[2] };
function extractDispatchIdentifiers(...texts) {
const { phase, plan } = parseDispatchIdentity(...texts);
return { plan, phase };
}
/**
@@ -265,6 +280,29 @@ function sentinelAppliesToDispatch(sentinel, dispatchIds) {
return true;
}
/**
* #4594 F3: build the structured "a fresh sentinel was present but did not
* apply to this dispatch" descriptor, mirroring the exact comparison
* `sentinelAppliesToDispatch` performs. Returns `null` when the sentinel is
* absent, stale, malformed, or DOES apply — i.e. exactly when there is
* nothing to report as discarded. Otherwise returns the nested
* `{ sentinel: {phase, plan}, dispatch: {phase, plan} }` shape, reusing the
* `{phase, plan}` pair already flowing through this module end to end rather
* than renaming its fields into an ad hoc `sentinelPhase`/`dispatchPlan` bag
* (previously rebuilt identically at two call sites in the guard hooks).
*/
function buildSentinelDiscard(sentinel, dispatchIds) {
if (!sentinel || !sentinel.present || sentinel.stale) return null;
if (sentinelAppliesToDispatch(sentinel, dispatchIds)) return null;
return {
sentinel: { phase: sentinel.phase ?? null, plan: sentinel.plan ?? null },
dispatch: {
phase: dispatchIds ? (dispatchIds.phase ?? null) : null,
plan: dispatchIds ? (dispatchIds.plan ?? null) : null,
},
};
}
module.exports = {
VALID_ISOLATION,
SENTINEL_RELATIVE_PATH,
@@ -274,4 +312,5 @@ module.exports = {
readSentinel,
extractDispatchIdentifiers,
sentinelAppliesToDispatch,
buildSentinelDiscard,
};