feat: resumable phase state + artifact-by-reference for lfg/slfg

[stephschofield]

What & why

Brings two workflow-runtime capabilities into ATV's markdown-skill lfg/slfg orchestrators:

• (A) Resumability — re-invoking /lfg or /slfg skips already-completed phases instead of restarting the turn.
• (B) Artifact-by-reference — phases record their output paths, so downstream steps read references rather than carrying full content in the agent's context.

The consumer is an LLM (cost = tokens + tool round-trips, not disk speed), so this deliberately avoids SQLite/a runtime in favor of small JSON files mutated by a tiny Node helper — zero new dependencies (Node is already a hook dependency, mirroring observe.js).

How it works

State lives under .atv/runs/<run-id>/ (gitignored, local-only):

meta.json                 # written once at init; only the parent binds plan_path
phases/<phase>.done.json  # one atomic sentinel per completed phase (temp-write + rename)

Per-phase sentinels eliminate read-modify-write races (important for SLFG's parallel phase); each sentinel's artifact field is the by-reference pointer — one structure solves both (A) and (B).

Changes

• Helper .github/hooks/scripts/lfg-state.js (+ shipped template copy): init, bind-plan, done, is-done, status, run-id-from-plan. Pure functions exported for tests; CLI guarded by require.main.
• lfg/slfg (dogfood + template): Run State section — derive/resume run-id, skip done phases, mark done with artifact path, thread run:<RUN_ID>, parent-only writes in SLFG.
• ce-plan/ce-work/ce-review: recognize-and-strip run:<run-id>; ce-work adds mode:orchestrated (resume-safe — no PR/ship, reconciles existing git diff/checkboxes/todos).
• .gitignore: .atv/runs/.
• Regenerated plugins/ from templates (parity check clean).

Design refinements (from a rubber-duck critique pass)

1. Two-stage run identity fixes a plan-phase chicken-and-egg (provisional id → bind plan_path after planning).
2. mode:orchestrated so ce-work reconciles instead of blindly restarting.
3. run: parsed before threading so an unknown token is never mis-read as a PR/branch arg.
4. Parent-only SLFG writes to avoid state races.

Testing

node --test .github/hooks/scripts/tests/lfg-state.test.js .github/hooks/scripts/tests/skill-contract.test.js   # 40/40
go test ./pkg/scaffold/... ./pkg/plugingen/...
go run ./cmd/plugingen -check   # parity clean

• 18 helper unit tests (real temp-dir fs, no mocks, TDD-first) + 22 contract tests asserting the skills adopt the protocol and dogfood/template copies can't drift.
• End-to-end resume sim: interrupt after ce-plan+ce-work → status resumes at ce-review; re-init preserves meta.

Scope / non-goals

• No new runtime or DB engine; no new dependencies.
• Cross-machine/fresh-checkout resume is out of scope — state is local-only; recovery there falls back to plan checkboxes / branch / open PR (the skills state this).

Plan: docs/plans/2026-06-01-001-feat-lfg-slfg-resumability-plan.md

[Copilot]

Pull request overview

This PR adds resumable run-state tracking and artifact-by-reference wiring to the markdown-skill orchestrators (/lfg and /slfg) by introducing a tiny Node helper that persists phase completion sentinels under a gitignored .atv/runs/<run-id>/ directory, and threads run:<RUN_ID> through sub-skills.

Changes:

• Introduces lfg-state.js helper (dogfood + template) to init/bind runs and mark phases done with optional artifact paths.
• Updates lfg/slfg skills (dogfood + template + generated plugin/pack copies) to resume by skipping done phases and to pass artifacts by reference.
• Updates ce-plan/ce-work/ce-review skill docs to recognize/strip run:<run-id> and adds mode:orchestrated guidance for resume-safe ce-work.

Reviewed changes

Copilot reviewed 30 out of 31 changed files in this pull request and generated 19 comments.

Show a summary per file

File	Description
plugins/atv-skill-slfg/skills/slfg/SKILL.md	Documents resumable SLFG orchestration and run-state protocol in the plugin copy.
plugins/atv-skill-lfg/skills/lfg/SKILL.md	Documents resumable LFG orchestration and run-state protocol in the plugin copy.
plugins/atv-skill-ce-work/skills/ce-work/SKILL.md	Documents run:<id> + mode:orchestrated orchestration tokens for ce-work.
plugins/atv-skill-ce-review/skills/ce-review/SKILL.md	Documents run:<id> token recognition/stripping for ce-review.
plugins/atv-skill-ce-plan/skills/ce-plan/SKILL.md	Documents run:<id> token recognition/stripping for ce-plan.
plugins/atv-pack-shipping/skills/slfg/SKILL.md	Propagates SLFG resumability/artifact-by-reference docs into shipping pack copy.
plugins/atv-pack-shipping/skills/lfg/SKILL.md	Propagates LFG resumability/artifact-by-reference docs into shipping pack copy.
plugins/atv-pack-shipping/skills/ce-work/SKILL.md	Propagates ce-work orchestration token docs into shipping pack copy.
plugins/atv-pack-review/skills/ce-review/SKILL.md	Propagates ce-review run:<id> token docs into review pack copy.
plugins/atv-pack-planning/skills/ce-plan/SKILL.md	Propagates ce-plan run:<id> token docs into planning pack copy.
plugins/atv-everything/skills/slfg/SKILL.md	Propagates SLFG resumability/artifact-by-reference docs into “everything” bundle copy.
plugins/atv-everything/skills/lfg/SKILL.md	Propagates LFG resumability/artifact-by-reference docs into “everything” bundle copy.
plugins/atv-everything/skills/ce-work/SKILL.md	Propagates ce-work orchestration token docs into “everything” bundle copy.
plugins/atv-everything/skills/ce-review/SKILL.md	Propagates ce-review run:<id> token docs into “everything” bundle copy.
plugins/atv-everything/skills/ce-plan/SKILL.md	Propagates ce-plan run:<id> token docs into “everything” bundle copy.
pkg/scaffold/templates/skills/slfg/SKILL.md	Updates SLFG scaffold template to be resumable and pass artifacts by reference.
pkg/scaffold/templates/skills/lfg/SKILL.md	Updates LFG scaffold template to be resumable and pass artifacts by reference.
pkg/scaffold/templates/skills/ce-work/SKILL.md	Updates ce-work scaffold template docs for orchestration tokens.
pkg/scaffold/templates/skills/ce-review/SKILL.md	Updates ce-review scaffold template docs for run:<id> token.
pkg/scaffold/templates/skills/ce-plan/SKILL.md	Updates ce-plan scaffold template docs for run:<id> token.
pkg/scaffold/templates/hooks/scripts/lfg-state.js	Adds scaffolded Node helper implementing run-state persistence and CLI commands.
docs/plans/2026-06-01-001-feat-lfg-slfg-resumability-plan.md	Adds implementation plan documenting the design and delivered test scenarios.
.gitignore	Ignores .atv/runs/ run-state directory.
.github/skills/slfg/SKILL.md	Updates dogfood SLFG skill with resumability/artifact-by-reference protocol.
.github/skills/lfg/SKILL.md	Updates dogfood LFG skill with resumability/artifact-by-reference protocol.
.github/skills/ce-work/SKILL.md	Updates dogfood ce-work docs for orchestration tokens and orchestrated mode.
.github/skills/ce-review/SKILL.md	Updates dogfood ce-review docs to recognize/strip run:<id>.
.github/skills/ce-plan/SKILL.md	Updates dogfood ce-plan docs to recognize/strip run:<id>.
.github/hooks/scripts/tests/skill-contract.test.js	Adds contract tests ensuring dogfood/template skills adopt the new protocol.
.github/hooks/scripts/tests/lfg-state.test.js	Adds unit tests for the run-state helper’s pure and fs-backed behaviors.
.github/hooks/scripts/lfg-state.js	Adds dogfood Node helper implementing run-state persistence and CLI commands.