feat(templates): add missing escalation targets + concept-intake stage

fix-test-fixture-sonnet@1, review-spec-opus@1, replan-spec-opus@1 — the
dangling escalation refs from airouter-impl-*/spec-draft/feature-delivery-loop.
Sonnet-authored, Opus-reviewed; review HIGH fixes applied (explicit model: opus
on both opus nodes — node model: sets runtime model, composite name does not).
Known gap filed in work-items epic (E1-escalation-state-gap.md): escalation
edges from non-primary states 422 state_mismatch pending escalation_input_states.
concept-intake@1: optional idea-elaboration pre-stage (output state
idea-elaborated — not yet wired into spec-draft-opus input).
All four validate against controlplane WorkflowTemplate schema.
This commit is contained in:
Paul O'Reilly
2026-07-02 21:27:43 +12:00
parent f3d7b42db5
commit 97d98689be
4 changed files with 215 additions and 0 deletions

View File

@@ -0,0 +1,69 @@
# SCHEMA NOTE (see report): WorkflowOutput has only a `state` field — there is no
# way to express "same state, tag removed" or "same state, artifact attached" in the
# M27 typed-workflow schema (controlplane/typed_workflows/schema.py). This template
# therefore transitions the item to a new state `idea-elaborated` rather than leaving
# it at `idea` with `needs-elaboration` removed. If a same-state transition becomes
# expressible in a future schema revision, this template should be updated to use it
# instead, and `spec-draft-opus@1.yaml`'s `input.state` should gain `idea-elaborated`
# as an accepted state (currently only `idea`).
name: concept-intake
version: 1
description: Triage and elaborate a raw idea before spec-draft — restate, surface unknowns, scope
runtime: planning-opus-repo
input:
state: idea
tags_required: [needs-elaboration]
tags_forbidden: []
required_artifacts: []
output:
state: idea-elaborated
scope_budget:
files_modified_max: 1
lines_diff_max: 150
wall_clock_seconds_max: 1200
nodes:
- id: agent
kind: agent
template: planning-opus-repo
prompt: |
The agent-runtimes project repo is cloned at /workspace/project (if this
runtime provides agent-repo mode). Change to that directory before doing
any work.
You are triaging a raw, unrefined idea before it goes to the spec-draft
stage. Your job is elaboration, not implementation and not spec-writing —
do not draft a spec.
**Title**: ${item.title}
**Raw idea**:
${item.body}
Produce an elaboration covering exactly these sections, in order:
1. **Restatement** — restate the idea in one paragraph, in your own words,
to confirm what is actually being asked for.
2. **Open Questions** — list every unknown that would materially change the
design as a numbered question. Do not answer them; that is what
spec-draft and review stages are for. If there are none, write "None."
3. **Affected Subsystems** — list the subsystems/components this idea
touches (e.g. `controlplane/`, `dispatcher/`, a specific harness
context). Use the actual directory names from the repo, not guesses.
4. **Proposed Scope Boundaries** — one paragraph stating what is explicitly
IN scope and one stating what is explicitly OUT of scope for the first
spec draft. Be concrete — "out of scope: multi-tenant support" not
"out of scope: edge cases."
Steps:
1. cd /workspace/project (if present)
2. Create a slug from the title (lowercase, hyphens instead of spaces)
3. Write the elaboration to spec/ideas/<slug>-elaboration.md — this is the
artifact the spec-draft stage reads (it looks for a file matching the
concept's slug under spec/ideas/)
4. git add spec/ideas/<slug>-elaboration.md && git commit -m "elaborate: ${item.title}" && git push
5. Call task_complete with a one-sentence summary
Keep the whole document under 150 lines — this is triage, not a spec. Do
not write code, do not modify any file outside spec/ideas/.
escalation:
scope_exceeded: null

View File

@@ -0,0 +1,47 @@
name: fix-test-fixture-sonnet
version: 1
description: Repair broken test fixtures without weakening assertions, Sonnet in worktree (escalation from airouter-impl-narrow/-ready fixture_broken)
runtime: code-sonnet-tdd-repo
input:
state: test-validated
tags_forbidden: [security-sensitive]
required_artifacts: [test_file]
output:
state: test-write-pending
scope_budget:
files_modified_max: 2
lines_diff_max: 60
wall_clock_seconds_max: 900
nodes:
- id: agent
kind: agent
template: code-sonnet-tdd-repo
prompt: |
A test-validation or implementation attempt against ${artifacts.test_file} was
escalated as fixture_broken — the failure is in fixtures, imports, or pytest
collection, NOT in missing implementation logic.
Repair the fixture/collection problem WITHOUT weakening any test assertion:
- Every test in ${artifacts.test_file} MUST remain marked
@pytest.mark.xfail(strict=True, reason="<spec-id>: <description>") against the
unimplemented code it exercises. Do not remove, loosen, or convert xfail markers
to skip/pass, and do not delete or rewrite assertions to make them pass.
- Fix only fixture/conftest/import problems: missing conftest fixtures, broken
imports, malformed fixture YAML, incorrect path references.
- Check any fixture YAML against these known-bad patterns (the violation codes
enforced by scripts/workflow/preflight-fixture-lint in the agent-runtimes repo):
MISSING_ALLOW_UNAUTHENTICATED — auth fixture missing allow_unauthenticated: true
MISSING_V1_PREFIX — URL path does not start with /v1/
BODY_GET_TYPE — body.get("type") instead of RFC 9457 type field
SPACE_ID_PLACEHOLDER — space_id value is "s" or another placeholder
TOP_LEVEL_PARAMS — top-level params: key instead of nested under workflow:
TOP_LEVEL_NODES — top-level nodes: key instead of nested under workflow:
- Do NOT touch the implementation skeleton or any non-test, non-fixture file.
Verify the fix with:
python -m pytest --collect-only ${artifacts.test_file}
Collection MUST succeed and every test MUST still report xfail (not error, not pass).
Commit and push to the work branch.
escalation:
agent_bailed: fix-test-fixture-sonnet

View File

@@ -0,0 +1,52 @@
name: replan-spec-opus
version: 1
description: Re-draft a spec from the concept and review findings, Opus (escalation from spec-draft-opus scope_exceeded)
runtime: spec-writing-opus-repo
input:
state: idea
tags_required: []
tags_forbidden: [security-sensitive]
required_artifacts: []
output:
state: spec-draft
scope_budget:
files_modified_max: 5
lines_diff_max: 300
wall_clock_seconds_max: 3600
nodes:
- id: agent
kind: agent
template: spec-writing-opus-repo
model: opus
prompt: |
The agent-runtimes project repo is cloned at /workspace/project.
Change to that directory before doing any work.
The prior spec-drafting attempt for this concept (spec-draft-opus, an airouter
model) was rejected as unsalvageable or exceeded its scope budget. You are the
Opus escalation — re-draft the spec from the original concept, taking into account
any review findings already recorded for this item (check the item's workflow
history and any prior /workspace/.agent-output/review.md content on the work
branch for what was flagged).
**Title**: ${item.title}
${item.body}
Steps:
1. cd /workspace/project
2. Read existing specs in spec/ to understand the format
3. Read any prior review findings available for this item and address them
directly in the new draft
4. Create a slug from the title (lowercase, hyphens instead of spaces)
5. Write the spec to spec/<slug>.md following the project spec format
6. git add spec/<slug>.md && git commit -m "spec: opus re-draft ${item.title}" && git push
7. Call task_complete with a one-sentence summary
The spec should have numbered requirement IDs, clear acceptance criteria, and error
handling. Follow the format of existing specs in spec/.
Note: this is an escalation path guarded by the trigger engine's loop guards
(cooldown + max fires/hour per spec/workflow-triggers.md WT-LOOP) — do not assume
unlimited re-draft attempts. Produce your best draft on this pass; the normal
review loop (review-spec-arch-opus) re-runs against your output.

View File

@@ -0,0 +1,47 @@
name: review-spec-opus
version: 1
description: Architecture review of a spec draft, Opus (escalation from review-spec-arch-opus contract_ambiguous)
runtime: best-practices-opus-repo
input:
state: spec-draft
tags_forbidden: [security-sensitive]
required_artifacts: [spec_file]
output:
state: spec-reviewed-arch
scope_budget:
files_modified_max: 2
lines_diff_max: 150
wall_clock_seconds_max: 1800
nodes:
- id: agent
kind: agent
template: best-practices-opus-repo
model: opus
prompt: |
The agent-runtimes project repo is cloned at /workspace/project.
Change to that directory before doing any work.
The standard architecture review of this spec draft (review-spec-arch-opus, an
airouter model) reported the contract as ambiguous and could not reach a confident
PASS/REWORK verdict. You are the stronger-model escalation — review the spec draft
for the following concept and resolve the ambiguity.
**Title**: ${item.title}
**Original concept**:
${item.body}
Steps:
1. cd /workspace/project
2. Find the spec file: ls spec/ and look for a file matching the concept title slug
3. Read the spec file completely
4. Review it against architectural best practices:
- Are requirements testable and unambiguous?
- Are there security implications not addressed?
- Are interfaces and data contracts clearly and unambiguously defined (request/
response shapes, error codes, state transitions)?
- Are edge cases and failure modes covered?
5. Write your review findings to /workspace/.agent-output/review.md with a PASS or
REWORK verdict and specific findings. Explicitly resolve whatever made the
contract ambiguous on the first pass.
6. Call task_complete with "PASS" or "REWORK: <one-line reason>"