diff --git a/skills/agent-runtime/curriculum-planner/SKILL.md b/skills/agent-runtime/curriculum-planner/SKILL.md index 7a5c7d0..7975dd3 100644 --- a/skills/agent-runtime/curriculum-planner/SKILL.md +++ b/skills/agent-runtime/curriculum-planner/SKILL.md @@ -181,17 +181,8 @@ or `list_folder_stages` instead of keeping it alive by repetition. ## When something fails -One bad page does not end a series. If a page or a whole stage will not -generate: - -- retry it once — every tool is idempotent, and an interrupted step just needs - re-issuing; -- if it still fails, note it, leave the rest of that stage intact, and move on - to the next one. Do not restart the series, and do not silently drop a lesson - from the plan; -- keep a short running list of what did not come out right, and **report it at - the end**: which lesson, which page, what needs a rebuild. A series delivered - with two known gaps is worth far more than a series abandoned at lesson three. +Page recovery follows `stage-design`; one failed page does not abort the rest of +the series. ## Finishing diff --git a/skills/agent-runtime/stage-design/SKILL.md b/skills/agent-runtime/stage-design/SKILL.md index aefeef0..d59c413 100644 --- a/skills/agent-runtime/stage-design/SKILL.md +++ b/skills/agent-runtime/stage-design/SKILL.md @@ -44,7 +44,7 @@ order: usable voice exists. Every page's content and narration is written for the roster that exists when the page is generated, so a roster settled late is a roster half the stage never saw. -4. **`generate_scene` once for EACH settled page, in ascending order** — one +4. **`generate_scene` for EACH settled page, in ascending order** — one page per call, never more. Pass the page's settled `title`, `type` and `brief` (plus `materialFacts` when the page's content comes from attached material); no planned outline is needed. A `pbl` page is generated the same @@ -59,6 +59,25 @@ landed, when `ask_user` is waiting on the user, or when the stage is done by the check below. Reporting what you have planned, imported or confirmed leaves the user holding an empty deck. +## When `generate_scene` fails + +Track generation attempts by `stageId + order`. Changing the title or brief, +or generating another page in between, does not reset the attempt. + +- For `prompt-unavailable` or another deterministic failure, do not repeat the + same call. +- For `invalid-model-output`, change the brief without changing the settled + teaching intent, then retry once. Retry once for a clearly transient provider + failure too. +- If that retry fails, do not call `generate_scene` again for that target during + this run. Leave the page unwritten, continue with later pages in the same + stage, and name the gap when wrapping up. Do not call `ask_user` after every + failed page or silently drop the page from the settled plan. + +Use `list_scenes` to reconcile persisted pages with the settled plan. A stage +with a missing page can be wrapped up after later pages are built, but it is not +done; name each gap and its latest failure instead of claiming completion. + ## Narration audio follows narration text When a page's narration is written or reworded with `patch_stage` on an diff --git a/tests/agent-runtime/stage-design-recovery-contract.test.ts b/tests/agent-runtime/stage-design-recovery-contract.test.ts new file mode 100644 index 0000000..00b949a --- /dev/null +++ b/tests/agent-runtime/stage-design-recovery-contract.test.ts @@ -0,0 +1,40 @@ +import { readFileSync } from 'node:fs'; +import { resolve } from 'node:path'; +import { describe, expect, it } from 'vitest'; + +const readSkill = (name: string) => + readFileSync(resolve(process.cwd(), `skills/agent-runtime/${name}/SKILL.md`), 'utf8').replace( + /\s+/g, + ' ', + ); + +describe('stage-design generation recovery contract', () => { + it('bounds retries per page without abandoning the stage', () => { + const skill = readSkill('stage-design'); + + for (const instruction of [ + '`stageId + order`', + 'does not reset the attempt', + '`prompt-unavailable`', + 'do not repeat the same call', + '`invalid-model-output`', + 'retry once', + 'continue with later pages in the same stage', + '`ask_user` after every failed page', + 'silently drop the page from the settled plan', + 'it is not done', + ]) { + expect(skill, instruction).toContain(instruction); + } + }); + + it('keeps the series layer delegated to stage-design', () => { + const skill = readSkill('curriculum-planner'); + + expect(skill).toContain( + 'Page recovery follows `stage-design`; one failed page does not abort the rest of the series.', + ); + expect(skill).not.toContain('`prompt-unavailable`'); + expect(skill).not.toContain('`invalid-model-output`'); + }); +});