T-BLYF-orchestrator-tick-token-budget-fixture

Status: closed/superseded · Impact: medium · Complexity: small

Auto-generated from a /sdlc:task-work post-mortem. Review and promote to open/ready before picking up.

Goal

/sdlc:orchestrate AC-4 asserts “parent transcript per tick grows by <2k tokens excluding sub-agent return strings”, but that’s a measurement claim with no instrumentation — the orchestrator skill prose enforces the dispatch shape (Agent(general-purpose) not direct Skill), and we trust that to imply the token budget. Once /loop /sdlc:orchestrate runs against the live repo we need a way to actually count parent-transcript token growth per tick and fail loud if it drifts. Closing this gap turns AC-4 from a spec-only claim into a verified property of T-3OVF-add-orchestrate-skill.

Today

From the originating post-mortem:

AC-4’s “parent transcript per tick grows by <2k tokens excluding sub-agent return strings” is a measurement claim that can’t be verified without running a real tick end-to-end and measuring. Spec-only today; needs a token-counting fixture once /loop /sdlc:orchestrate runs against the live repo for a few ticks.

The skill body says the parent “reads only the verdict” line from each sub-agent, and the gate skill-prose contract pins Agent(general-purpose) dispatch from the parent body, but there is no counter, no log line, and no test that records parent token growth across a tick. If a future sub-agent change accidentally leaks output into the parent transcript (e.g. via a tool that returns verbose data), nothing trips.

Proposed

A tiny fixture (a digest-log field + a checker op) that:

1. Lets a tick measure its own parent-transcript token growth and write it to .sdlc/orchestrator-log.md as a structured field (e.g. parent-tokens=1834).
2. Provides a checker op that reads the log and flags any tick where parent-tokens exceeded a threshold (default 2000, matching AC-4).
3. Optionally surfaces over-budget ticks in the next tick’s digest so the human sees the drift.

Approach

1. Decide measurement source — either the harness exposes a per- tool-call token count we can read, or we approximate by hashing sub-agent return strings out of the transcript and counting the remainder via a tokenizer. Punt the decision until the first live tick reveals what’s actually observable. (Known open issue: whether parent-transcript growth is observable from within a skill at all.)
2. Extend sdlc orchestrate log-tick (apps/sdlc/lib/services/orchestrator/ops/log-tick.ts) to accept and emit a parent-tokens=<N> digest field — the op owns the digest grammar — and have the Step 5 digest call in apps/sdlc/skills/orchestrate/SKILL.md pass the value.
3. Add a registry op sdlc orchestrate check-token-budget that scans the digest log and exits non-zero if any tick exceeded the cap. Deterministic checks land as registry ops, not skill-side scripts (D-H7FS-op-substrate-surface).
4. Extend the orchestrate overlay in SKILL_PROSE_REGISTRY (apps/sdlc/lib/services/gate/ops/_skill_prose_contract.ts) to pin the digest-log token field once the prose lands.

Files to touch

Location	Kind	Change
apps/sdlc/skills/orchestrate/SKILL.md	modify	pass --parent-tokens in the Step 5 log-tick call.
apps/sdlc/lib/services/orchestrator/ops/log-tick.ts	modify	accept --parent-tokens and emit the field in the summary line.
apps/sdlc/lib/services/orchestrator/ops/check-token-budget.ts	new	checker op: exit non-zero when any tick exceeds the cap.
apps/sdlc/lib/services/gate/ops/_skill_prose_contract.ts	modify	pin the token field in the orchestrate overlay.
docs/planning/tasks/T-3OVF-add-orchestrate-skill.md	modify	mark AC-4 verified once the fixture lands.

Acceptance criteria

• AC-1: A tick run via /loop /sdlc:orchestrate writes a parent-tokens=<N> field to .sdlc/orchestrator-log.md.
• AC-2: sdlc orchestrate check-token-budget reads the log and exits non-zero when any tick’s parent-tokens exceeds 2000.
• AC-3: With the orchestrator running for at least 3 consecutive ticks against a representative repo, every tick’s parent-tokens field stays under the documented per-tick budget (currently 2000, as asserted by AC-2).

Out of scope

• Cross-session token accounting; one log = one session.
• Counting sub-agent internal token use — only parent-transcript growth is in scope.

Dependencies

• T-3OVF-add-orchestrate-skill (merged); the fixture instruments its digest-log format.

Discovery context

Spawned by /sdlc:task-work post-mortem of T-3OVF-add-orchestrate-skill on 2026-05-20.

---

← Back to Tasks