Merge pull request #191 from speakeasy-api/fix/guide-context-order

fix(factory): allow interleaved context reads

Author: walker-tx

factory/coordinator.md

@@ -45,7 +45,7 @@ return if context_attempt.caught {
 }
 ```
 
-If the program returns `factory_status`, set terminal state to `failed`, record the fixed blocker `Phase 1 guide-context inspection failed.`, set `stop_model_phases = true`, skip every remaining model phase, and continue to atomic report creation. Otherwise the program must return the successful shell result object unchanged; do not parse, project, or reshape it inside compose. Read authority, role, schema, persona, representative-guide, and target-artifact contents only from its `.files` object. If Kit spills this large result, consume it only through the repository spill reader. First execute exactly `bash factory/scripts/read-guide-context-spill.sh <artifact> index` in a caught boundary, where `<artifact>` is the exact path returned by Kit. Then consume every listed file in index order with caught commands shaped exactly `bash factory/scripts/read-guide-context-spill.sh <artifact> read <index> <offset>`: start each file at offset 0, use only the returned next_offset, and repeat until done=true before moving to the next index. Never construct jq, sed, Python, or other free-form spill commands; never read a spill with shell redirection or a generic file command. A rejected spill, missing index/chunk, changed path/index/offset, or incomplete file consumption selects failed; never inspect repository files directly or run another Phase 1 file-discovery tool. Resolve the persona only after reading every available definition under `doctrine/personas/`: default to `it-admin`; override it only when the issue confidently names an available repository persona. Pass the selected `doctrine/personas/<persona>.md` file to every downstream agent and reviewer. Resolve catalog presence only from the `.catalog` object returned by the initial command; never inspect `/input/catalog.json` directly. Preserve tenanted remote and `speakeasy_add_server` catalog/custom-remote doctrine. Skipped, malformed, stale, or ambiguous lookup means unknown, never absence; preserve both safe setup paths and record a research limitation rather than asking the operator to repeat the lookup.
+If the program returns `factory_status`, set terminal state to `failed`, record the fixed blocker `Phase 1 guide-context inspection failed.`, set `stop_model_phases = true`, skip every remaining model phase, and continue to atomic report creation. Otherwise the program must return the successful shell result object unchanged; do not parse, project, or reshape it inside compose. Read authority, role, schema, persona, representative-guide, and target-artifact contents only from its `.files` object. If Kit spills this large result, consume it only through the repository spill reader. First execute exactly `bash factory/scripts/read-guide-context-spill.sh <artifact> index` in a caught boundary, where `<artifact>` is the exact path returned by Kit. Consume listed files with caught commands shaped exactly `bash factory/scripts/read-guide-context-spill.sh <artifact> read <index> <offset>`. Files may be consumed in any order or interleaved. For each index, start each file at offset 0 and use only that file's returned next_offset until it reaches done=true; never use one file's offset for another index. Every listed file must reach done=true before Phase 2. Never construct jq, sed, Python, or other free-form spill commands; never read a spill with shell redirection or a generic file command. A rejected spill, missing index/chunk, changed path/index/offset, or incomplete file consumption selects failed; never inspect repository files directly or run another Phase 1 file-discovery tool. Resolve the persona only after reading every available definition under `doctrine/personas/`: default to `it-admin`; override it only when the issue confidently names an available repository persona. Pass the selected `doctrine/personas/<persona>.md` file to every downstream agent and reviewer. Resolve catalog presence only from the `.catalog` object returned by the initial command; never inspect `/input/catalog.json` directly. Preserve tenanted remote and `speakeasy_add_server` catalog/custom-remote doctrine. Skipped, malformed, stale, or ambiguous lookup means unknown, never absence; preserve both safe setup paths and record a research limitation rather than asking the operator to repeat the lookup.
 
 ## Phase 2 — research and scope gate
 

factory/tests/test-coordinator.sh

@@ -26,7 +26,9 @@ for phrase in \
   'never inspect repository files directly or run another Phase 1 file-discovery tool' \
   'bash factory/scripts/read-guide-context-spill.sh <artifact> index' \
   'bash factory/scripts/read-guide-context-spill.sh <artifact> read <index> <offset>' \
-  'start each file at offset 0, use only the returned next_offset' \
+  'Files may be consumed in any order or interleaved' \
+  'start each file at offset 0 and use only that file' \
+  'Every listed file must reach done=true before Phase 2' \
   'Never construct jq, sed, Python, or other free-form spill commands' \
   'incomplete file consumption selects failed' \
   "catalog presence only from the \`.catalog\` object returned by the initial command" \
@@ -63,6 +65,10 @@ for phrase in \
   grep -Fq "$phrase" "$CONTRACT" || fail "missing contract: $phrase"
 done
 
+if grep -Fq 'in index order' "$CONTRACT"; then
+  fail 'guide-context spill contract still requires global index order'
+fi
+
 context_boundary=$(cat <<'RUNLET'
 context_attempt = boundary {
   result = shell({ command: "bash factory/scripts/inspect-guide-context.sh <slug>" })