From c41800b4a59dd6400e103024e0f03f880314558b Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Thu, 9 Jul 2026 18:18:42 +0300 Subject: [PATCH 01/10] spec: summarize-delivery-skill (devague /think) Converged Announcement Frame + exported spec for the fifth origin skill: the delivery-side closure leg (planned vs actual, mid-work decisions, drift, evidence-backed delivery claims, remaining work). Co-Authored-By: Claude Fable 5 --- .devague/frames/summarize-delivery-skill.json | 399 ++++++++++++++++++ .../2026-07-09-summarize-delivery-skill.md | 100 +++++ 2 files changed, 499 insertions(+) create mode 100644 .devague/frames/summarize-delivery-skill.json create mode 100644 docs/specs/2026-07-09-summarize-delivery-skill.md diff --git a/.devague/frames/summarize-delivery-skill.json b/.devague/frames/summarize-delivery-skill.json new file mode 100644 index 0000000..1a62519 --- /dev/null +++ b/.devague/frames/summarize-delivery-skill.json @@ -0,0 +1,399 @@ +{ + "slug": "summarize-delivery-skill", + "title": "summarize-delivery skill", + "schema_version": 1, + "status": "exported", + "created": "2026-07-09T15:12:14Z", + "updated": "2026-07-09T15:17:54Z", + "claims": [ + { + "id": "c1", + "kind": "announcement", + "text": "devague closes the loop: after assign-to-workforce executes a plan, the new summarize-delivery skill turns the run into an accountability artifact - planned versus actual delivery, mid-work decisions, plan drift, evidence-backed delivery claims, and remaining work", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h1", + "text": "running the skill after a real workforce run yields an artifact a human can audit without reading the execution transcript", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "verify the shipped kit: .claude/skills/summarize-delivery/SKILL.md exists, docs/skill-sources.md lists it as the fifth origin skill, and the flow docs name the five-leg flow ending in summarize-delivery" + }, + { + "id": "c2", + "kind": "after_state", + "text": "after an assign-to-workforce run - complete, partial, or failed - the operator produces a delivery summary that separates planned work from actual delivery, records mid-work decisions and plan drift, and states delivery claims with evidence and confidence, plus remaining work", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h2", + "text": "the summary is producible from durable inputs (plan state, git history, PR links, test output) - it never depends on unrecorded memory of the run", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "dry-run the skill against a real workforce run (complete and partial): the artifact separates planned from actual, and lists decisions, drift, claims with evidence, and remaining work" + }, + { + "id": "c3", + "kind": "before_state", + "text": "what we plan is not always what we deliver: agents make mid-work decisions, discover constraints, cut scope, and make delivery claims that were never in the plan - and the flow has no wrap-up leg to record any of it", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h3", + "text": "the gap is real: no existing skill or doc in the kit defines a wrap-up step (verified against .claude/skills/ and docs/skills.md)", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "grep .claude/skills/ and docs/ for an existing wrap-up or delivery-summary step: none exists today" + }, + { + "id": "c4", + "kind": "why_it_matters", + "text": "the plan becomes a contract, not a fiction: the summary records where execution obeyed the contract, where it changed, and what is actually safe to claim as delivered", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h4", + "text": "every delivery claim in the artifact traces back to a plan task or an explicit drift entry - the plan-versus-actual comparison is mechanical", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "check the template keys drift and claims to plan task ids so the contract comparison is mechanical, not rhetorical" + }, + { + "id": "c5", + "kind": "non_goal", + "text": "not a polite progress report and not a restatement of the plan - it is an accountability artifact", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [], + "hard_questions": [], + "links": [], + "instruction": "" + }, + { + "id": "c6", + "kind": "requirement", + "text": "invocable after assigned work is completed or partially completed", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h5", + "text": "the skill has no completion precondition: a run that merged zero waves is still a valid input", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "check SKILL.md: partial and failed runs are named valid inputs; no step requires all waves merged" + }, + { + "id": "c7", + "kind": "requirement", + "text": "distinguishes planned work from actual delivery", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h6", + "text": "the Planned Work section quotes the plan verbatim (task ids and summaries), so drift is detected against the contract the user confirmed, not a paraphrase", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "check the template: Planned Work and Actual Delivery are separate mandatory sections, and Planned Work quotes the plan (task ids and summaries verbatim) rather than paraphrasing" + }, + { + "id": "c8", + "kind": "requirement", + "text": "explicitly captures mid-work decisions and plan drift, classifying each drift as acceptable, risky, or needs-follow-up", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h7", + "text": "drift entries are exhaustive relative to the plan: any plan task whose delivery differs appears as a drift entry, never silently normalized", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "check the template: each drift entry names the plan item it diverges from, the reason, and exactly one classification: acceptable, risky, or needs-follow-up" + }, + { + "id": "c9", + "kind": "requirement", + "text": "produces delivery claims with a confidence level (high/medium/low) and evidence pointers - commits, files, PRs, issues, tests, logs, docs - where available", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h8", + "text": "each evidence pointer resolves: the commit exists, the file is at the path, the PR or issue number is real, the test node ran", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "check the template: each delivery claim line carries confidence and evidence fields, and evidence pointers are resolvable (commit SHA, file path, PR or issue number, test node id)" + }, + { + "id": "c10", + "kind": "requirement", + "text": "avoids overclaiming: a delivery claim without evidence is marked unverified, never asserted as done", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h9", + "text": "the unverified marker survives into the committed artifact - no downstream step upgrades confidence without new evidence", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "check SKILL.md hard rules: no-overclaiming is a hard rule, and the template defaults missing evidence to unverified" + }, + { + "id": "c11", + "kind": "requirement", + "text": "usable when work is incomplete, failed, or partially delivered - failure is reported faithfully, not smoothed over", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h10", + "text": "a failed run produces a truthful artifact: the failure appears under drift and remaining work with its cause, and no delivery claim says done", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "dry-run the template against a failed run: no section becomes unwritable; Remaining Work and Drift absorb the failure" + }, + { + "id": "c12", + "kind": "assumption", + "text": "when the run was devague-driven, plan state (tasks, acceptance criteria, waves) and the exported plan-md are available as the planned-work baseline; when absent, the skill degrades to git and PR history and says so in the artifact", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [], + "hard_questions": [], + "links": [], + "instruction": "" + }, + { + "id": "c13", + "kind": "audience", + "text": "the operator (main agent) closing a workforce run, the human owner at the final PR gate, and any later reader who needs to know what actually shipped without replaying the execution transcript", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h11", + "text": "the artifact is committed and self-contained, so the final-PR reviewer can use it as the review map", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "check SKILL.md names all three readers, and that the artifact is committed (durable) and readable standalone" + }, + { + "id": "c14", + "kind": "boundary", + "text": "delivery-side closure only: the skill summarizes and cross-references after execution - it does not orchestrate work, gate merges (assign-to-workforce owns the TDD gate), mark plan tasks done, or mutate devague state; reads of plan and frame state are read-only (issue 20)", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h12", + "text": "a summarize-delivery run leaves .devague/ state byte-identical", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "grep the shipped SKILL.md: the only devague moves it documents are read-only (plan show, plan waves, scope --list, show, status)" + }, + { + "id": "c15", + "kind": "success_signal", + "text": "in an exported delivery summary, 100% of plan tasks are accounted for (delivered, partial, dropped, or blocked) and every delivery claim carries a confidence level plus at least 1 evidence pointer or an explicit unverified marker", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h13", + "text": "both counts are checkable by inspection of the artifact alone, with no hidden context", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "auditable from the artifact alone: count plan tasks versus accounted rows; scan every claim line for confidence plus evidence-or-unverified" + }, + { + "id": "c16", + "kind": "requirement", + "text": "the artifact follows the eight-section shape from the proposal: Intent, Planned Work, Actual Delivery, Mid-work Decisions, Drift From Plan, Evidence, Delivery Claims, and Remaining Work / Follow-up", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h14", + "text": "the shipped template carries all eight sections and stays writable for partial and failed runs", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "check the shipped template carries all eight sections; any rename or merge is recorded as drift from this spec in the PR description" + }, + { + "id": "c17", + "kind": "requirement", + "text": "summarize-delivery is registered as the fifth origin skill in docs/skill-sources.md (origin devague; guildmaster re-broadcasts to the mesh; never re-vendored back)", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h15", + "text": "the skill-sources.md row lands in the same PR as the skill, so provenance never lags the kit", + "status": "confirmed", + "instruction": "" + } + ], + "hard_questions": [], + "links": [], + "instruction": "check the docs/skill-sources.md origin-skills table gains a summarize-delivery row in the same PR that adds the skill" + }, + { + "id": "c18", + "kind": "decision", + "text": "the skill is named summarize-delivery: a verb-phrase name like assign-to-workforce; plan-to-delivery would misname the leg because assign-to-workforce is what takes the plan to delivery - this skill summarizes it", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [], + "hard_questions": [], + "links": [], + "instruction": "" + }, + { + "id": "c19", + "kind": "decision", + "text": "v1 is method-only like scope at birth: SKILL.md with the output template, no entry-point script, no new CLI verb; the deterministic CLI surface is unchanged (issue 20); a future delivery engine is parked as follow-up", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [], + "hard_questions": [], + "links": [], + "instruction": "" + }, + { + "id": "c20", + "kind": "decision", + "text": "the summary is a committed, durable artifact at `docs/deliveries/-.md` - the structural peer of docs/specs/ and docs/plans/; uncommitted .devague/ working state stays for non-authoritative drafts", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [], + "hard_questions": [], + "links": [], + "instruction": "" + }, + { + "id": "c21", + "kind": "decision", + "text": "the skill may run read-only verification (test suite, linters, git log) to substantiate a delivery claim before writing it; it never mutates code or state; a claim it cannot verify stays unverified", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [], + "hard_questions": [], + "links": [], + "instruction": "" + } + ], + "open_vagueness": [ + { + "id": "v1", + "text": "a future devague delivery engine - a third structural peer (delivery store, per-task accounting, deterministic no-overclaim gate) - deferred until dogfooding the method-only skill shows machine state is needed", + "kind": "follow_up", + "claim_id": null + } + ], + "scope_entries": [ + { + "id": "s1", + "surface": ".claude/skills/assign-to-workforce/SKILL.md", + "finding": "the upstream leg read end-to-end: three human gates, TDD-gated merges, per-task acceptance kept as uncommitted working state, final PR via cicd - the end state summarize-delivery must summarize; its verbatim-brief rule motivates quoting the plan verbatim in Planned Work", + "seeds": [ + "c2", + "c7", + "c14" + ] + }, + { + "id": "s2", + "surface": ".claude/skills/scope/SKILL.md", + "finding": "the chassis precedent: scope shipped method-only in 0.15.0 (no script, no CLI verb) with the CLI move landing later via the issue 53 build plan - summarize-delivery v1 copies that shape", + "seeds": [ + "c19" + ] + }, + { + "id": "s3", + "surface": "docs/skill-sources.md", + "finding": "origin-skills table: devague is upstream for scope, think, spec-to-plan, assign-to-workforce; a fifth origin row is where summarize-delivery registers; guildmaster re-broadcasts and never re-vendors back", + "seeds": [ + "c17" + ] + }, + { + "id": "s4", + "surface": "devague plan waves --json (as documented in assign-to-workforce SKILL.md)", + "finding": "the deterministic planned-work baseline: tasks keyed by id with verbatim summary, instruction, acceptance criteria, and covered targets - the contract actuals are compared against", + "seeds": [ + "c12", + "c7" + ] + }, + { + "id": "s5", + "surface": ".devague/ and docs/ layout", + "finding": "two artifact tiers observed: .devague reviews and questions are uncommitted non-authoritative working state; docs/specs and docs/plans are committed buildable artifacts - an accountability artifact belongs in the committed tier", + "seeds": [ + "c20" + ] + } + ] +} diff --git a/docs/specs/2026-07-09-summarize-delivery-skill.md b/docs/specs/2026-07-09-summarize-delivery-skill.md new file mode 100644 index 0000000..f0d5f20 --- /dev/null +++ b/docs/specs/2026-07-09-summarize-delivery-skill.md @@ -0,0 +1,100 @@ +# summarize-delivery skill + +> devague closes the loop: after assign-to-workforce executes a plan, the new summarize-delivery skill turns the run into an accountability artifact - planned versus actual delivery, mid-work decisions, plan drift, evidence-backed delivery claims, and remaining work +> instruction: verify the shipped kit: .claude/skills/summarize-delivery/SKILL.md exists, docs/skill-sources.md lists it as the fifth origin skill, and the flow docs name the five-leg flow ending in summarize-delivery + +## Audience + +- the operator (main agent) closing a workforce run, the human owner at the final PR gate, and any later reader who needs to know what actually shipped without replaying the execution transcript + - instruction: check SKILL.md names all three readers, and that the artifact is committed (durable) and readable standalone + +## Before → After + +- Before: what we plan is not always what we deliver: agents make mid-work decisions, discover constraints, cut scope, and make delivery claims that were never in the plan - and the flow has no wrap-up leg to record any of it + - instruction: grep .claude/skills/ and docs/ for an existing wrap-up or delivery-summary step: none exists today +- After: after an assign-to-workforce run - complete, partial, or failed - the operator produces a delivery summary that separates planned work from actual delivery, records mid-work decisions and plan drift, and states delivery claims with evidence and confidence, plus remaining work + - instruction: dry-run the skill against a real workforce run (complete and partial): the artifact separates planned from actual, and lists decisions, drift, claims with evidence, and remaining work + +## Why it matters + +- the plan becomes a contract, not a fiction: the summary records where execution obeyed the contract, where it changed, and what is actually safe to claim as delivered + - instruction: check the template keys drift and claims to plan task ids so the contract comparison is mechanical, not rhetorical + +## Requirements + +- invocable after assigned work is completed or partially completed + - instruction: check SKILL.md: partial and failed runs are named valid inputs; no step requires all waves merged + - honesty: the skill has no completion precondition: a run that merged zero waves is still a valid input +- distinguishes planned work from actual delivery + - instruction: check the template: Planned Work and Actual Delivery are separate mandatory sections, and Planned Work quotes the plan (task ids and summaries verbatim) rather than paraphrasing + - honesty: the Planned Work section quotes the plan verbatim (task ids and summaries), so drift is detected against the contract the user confirmed, not a paraphrase +- explicitly captures mid-work decisions and plan drift, classifying each drift as acceptable, risky, or needs-follow-up + - instruction: check the template: each drift entry names the plan item it diverges from, the reason, and exactly one classification: acceptable, risky, or needs-follow-up + - honesty: drift entries are exhaustive relative to the plan: any plan task whose delivery differs appears as a drift entry, never silently normalized +- produces delivery claims with a confidence level (high/medium/low) and evidence pointers - commits, files, PRs, issues, tests, logs, docs - where available + - instruction: check the template: each delivery claim line carries confidence and evidence fields, and evidence pointers are resolvable (commit SHA, file path, PR or issue number, test node id) + - honesty: each evidence pointer resolves: the commit exists, the file is at the path, the PR or issue number is real, the test node ran +- avoids overclaiming: a delivery claim without evidence is marked unverified, never asserted as done + - instruction: check SKILL.md hard rules: no-overclaiming is a hard rule, and the template defaults missing evidence to unverified + - honesty: the unverified marker survives into the committed artifact - no downstream step upgrades confidence without new evidence +- usable when work is incomplete, failed, or partially delivered - failure is reported faithfully, not smoothed over + - instruction: dry-run the template against a failed run: no section becomes unwritable; Remaining Work and Drift absorb the failure + - honesty: a failed run produces a truthful artifact: the failure appears under drift and remaining work with its cause, and no delivery claim says done +- the artifact follows the eight-section shape from the proposal: Intent, Planned Work, Actual Delivery, Mid-work Decisions, Drift From Plan, Evidence, Delivery Claims, and Remaining Work / Follow-up + - instruction: check the shipped template carries all eight sections; any rename or merge is recorded as drift from this spec in the PR description + - honesty: the shipped template carries all eight sections and stays writable for partial and failed runs +- summarize-delivery is registered as the fifth origin skill in docs/skill-sources.md (origin devague; guildmaster re-broadcasts to the mesh; never re-vendored back) + - instruction: check the docs/skill-sources.md origin-skills table gains a summarize-delivery row in the same PR that adds the skill + - honesty: the skill-sources.md row lands in the same PR as the skill, so provenance never lags the kit + +## Honesty conditions + +- running the skill after a real workforce run yields an artifact a human can audit without reading the execution transcript +- the summary is producible from durable inputs (plan state, git history, PR links, test output) - it never depends on unrecorded memory of the run +- the gap is real: no existing skill or doc in the kit defines a wrap-up step (verified against .claude/skills/ and docs/skills.md) +- every delivery claim in the artifact traces back to a plan task or an explicit drift entry - the plan-versus-actual comparison is mechanical +- the artifact is committed and self-contained, so the final-PR reviewer can use it as the review map +- a summarize-delivery run leaves .devague/ state byte-identical +- both counts are checkable by inspection of the artifact alone, with no hidden context + +## Success signals + +- in an exported delivery summary, 100% of plan tasks are accounted for (delivered, partial, dropped, or blocked) and every delivery claim carries a confidence level plus at least 1 evidence pointer or an explicit unverified marker + - instruction: auditable from the artifact alone: count plan tasks versus accounted rows; scan every claim line for confidence plus evidence-or-unverified + +## Scope / boundaries + +- delivery-side closure only: the skill summarizes and cross-references after execution - it does not orchestrate work, gate merges (assign-to-workforce owns the TDD gate), mark plan tasks done, or mutate devague state; reads of plan and frame state are read-only (issue 20) + - instruction: grep the shipped SKILL.md: the only devague moves it documents are read-only (plan show, plan waves, scope --list, show, status) + +## Non-goals + +- not a polite progress report and not a restatement of the plan - it is an accountability artifact + +## Assumptions + +- when the run was devague-driven, plan state (tasks, acceptance criteria, waves) and the exported plan-md are available as the planned-work baseline; when absent, the skill degrades to git and PR history and says so in the artifact + +## Scope exploration + +- `s1` — `.claude/skills/assign-to-workforce/SKILL.md`: the upstream leg read end-to-end: three human gates, TDD-gated merges, per-task acceptance kept as uncommitted working state, final PR via cicd - the end state summarize-delivery must summarize; its verbatim-brief rule motivates quoting the plan verbatim in Planned Work + - seeds: `c2`, `c7`, `c14` +- `s2` — `.claude/skills/scope/SKILL.md`: the chassis precedent: scope shipped method-only in 0.15.0 (no script, no CLI verb) with the CLI move landing later via the issue 53 build plan - summarize-delivery v1 copies that shape + - seeds: `c19` +- `s3` — `docs/skill-sources.md`: origin-skills table: devague is upstream for scope, think, spec-to-plan, assign-to-workforce; a fifth origin row is where summarize-delivery registers; guildmaster re-broadcasts and never re-vendors back + - seeds: `c17` +- `s4` — `devague plan waves --json (as documented in assign-to-workforce SKILL.md)`: the deterministic planned-work baseline: tasks keyed by id with verbatim summary, instruction, acceptance criteria, and covered targets - the contract actuals are compared against + - seeds: `c12`, `c7` +- `s5` — `.devague/ and docs/ layout`: two artifact tiers observed: .devague reviews and questions are uncommitted non-authoritative working state; docs/specs and docs/plans are committed buildable artifacts - an accountability artifact belongs in the committed tier + - seeds: `c20` + +## Decisions + +- the skill is named summarize-delivery: a verb-phrase name like assign-to-workforce; plan-to-delivery would misname the leg because assign-to-workforce is what takes the plan to delivery - this skill summarizes it +- v1 is method-only like scope at birth: SKILL.md with the output template, no entry-point script, no new CLI verb; the deterministic CLI surface is unchanged (issue 20); a future delivery engine is parked as follow-up +- the summary is a committed, durable artifact at `docs/deliveries/-.md` - the structural peer of docs/specs/ and docs/plans/; uncommitted .devague/ working state stays for non-authoritative drafts +- the skill may run read-only verification (test suite, linters, git log) to substantiate a delivery claim before writing it; it never mutates code or state; a claim it cannot verify stays unverified + +## Open / follow-up + +- a future devague delivery engine - a third structural peer (delivery store, per-task accounting, deterministic no-overclaim gate) - deferred until dogfooding the method-only skill shows machine state is needed From 9166f73a4abea6e1c6c6b87f3addea9c856c0553 Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Thu, 9 Jul 2026 18:23:44 +0300 Subject: [PATCH 02/10] plan: summarize-delivery-skill (devague /spec-to-plan) Converged build plan for the fifth origin skill: t1 SKILL.md + template, t2 skill-sources registration, t3 flow docs + workforce handoff, t4 dogfood delivery summary for the sharper-method run, t5 release hygiene. Waves: [t1 t2 t3] -> [t4] -> [t5]. Co-Authored-By: Claude Fable 5 --- .devague/plans/summarize-delivery-skill.json | 298 ++++++++++++++++++ .../2026-07-09-summarize-delivery-skill.md | 61 ++++ 2 files changed, 359 insertions(+) create mode 100644 .devague/plans/summarize-delivery-skill.json create mode 100644 docs/plans/2026-07-09-summarize-delivery-skill.md diff --git a/.devague/plans/summarize-delivery-skill.json b/.devague/plans/summarize-delivery-skill.json new file mode 100644 index 0000000..bb64ae3 --- /dev/null +++ b/.devague/plans/summarize-delivery-skill.json @@ -0,0 +1,298 @@ +{ + "slug": "summarize-delivery-skill", + "title": "summarize-delivery skill", + "frame_slug": "summarize-delivery-skill", + "schema_version": 2, + "status": "exported", + "created": "2026-07-09T15:20:30Z", + "updated": "2026-07-09T15:23:34Z", + "targets": [ + { + "id": "c1", + "kind": "announcement", + "text": "devague closes the loop: after assign-to-workforce executes a plan, the new summarize-delivery skill turns the run into an accountability artifact - planned versus actual delivery, mid-work decisions, plan drift, evidence-backed delivery claims, and remaining work" + }, + { + "id": "h1", + "kind": "honesty", + "text": "running the skill after a real workforce run yields an artifact a human can audit without reading the execution transcript" + }, + { + "id": "c2", + "kind": "after_state", + "text": "after an assign-to-workforce run - complete, partial, or failed - the operator produces a delivery summary that separates planned work from actual delivery, records mid-work decisions and plan drift, and states delivery claims with evidence and confidence, plus remaining work" + }, + { + "id": "h2", + "kind": "honesty", + "text": "the summary is producible from durable inputs (plan state, git history, PR links, test output) - it never depends on unrecorded memory of the run" + }, + { + "id": "c3", + "kind": "before_state", + "text": "what we plan is not always what we deliver: agents make mid-work decisions, discover constraints, cut scope, and make delivery claims that were never in the plan - and the flow has no wrap-up leg to record any of it" + }, + { + "id": "h3", + "kind": "honesty", + "text": "the gap is real: no existing skill or doc in the kit defines a wrap-up step (verified against .claude/skills/ and docs/skills.md)" + }, + { + "id": "c4", + "kind": "why_it_matters", + "text": "the plan becomes a contract, not a fiction: the summary records where execution obeyed the contract, where it changed, and what is actually safe to claim as delivered" + }, + { + "id": "h4", + "kind": "honesty", + "text": "every delivery claim in the artifact traces back to a plan task or an explicit drift entry - the plan-versus-actual comparison is mechanical" + }, + { + "id": "c6", + "kind": "requirement", + "text": "invocable after assigned work is completed or partially completed" + }, + { + "id": "h5", + "kind": "honesty", + "text": "the skill has no completion precondition: a run that merged zero waves is still a valid input" + }, + { + "id": "c7", + "kind": "requirement", + "text": "distinguishes planned work from actual delivery" + }, + { + "id": "h6", + "kind": "honesty", + "text": "the Planned Work section quotes the plan verbatim (task ids and summaries), so drift is detected against the contract the user confirmed, not a paraphrase" + }, + { + "id": "c8", + "kind": "requirement", + "text": "explicitly captures mid-work decisions and plan drift, classifying each drift as acceptable, risky, or needs-follow-up" + }, + { + "id": "h7", + "kind": "honesty", + "text": "drift entries are exhaustive relative to the plan: any plan task whose delivery differs appears as a drift entry, never silently normalized" + }, + { + "id": "c9", + "kind": "requirement", + "text": "produces delivery claims with a confidence level (high/medium/low) and evidence pointers - commits, files, PRs, issues, tests, logs, docs - where available" + }, + { + "id": "h8", + "kind": "honesty", + "text": "each evidence pointer resolves: the commit exists, the file is at the path, the PR or issue number is real, the test node ran" + }, + { + "id": "c10", + "kind": "requirement", + "text": "avoids overclaiming: a delivery claim without evidence is marked unverified, never asserted as done" + }, + { + "id": "h9", + "kind": "honesty", + "text": "the unverified marker survives into the committed artifact - no downstream step upgrades confidence without new evidence" + }, + { + "id": "c11", + "kind": "requirement", + "text": "usable when work is incomplete, failed, or partially delivered - failure is reported faithfully, not smoothed over" + }, + { + "id": "h10", + "kind": "honesty", + "text": "a failed run produces a truthful artifact: the failure appears under drift and remaining work with its cause, and no delivery claim says done" + }, + { + "id": "c13", + "kind": "audience", + "text": "the operator (main agent) closing a workforce run, the human owner at the final PR gate, and any later reader who needs to know what actually shipped without replaying the execution transcript" + }, + { + "id": "h11", + "kind": "honesty", + "text": "the artifact is committed and self-contained, so the final-PR reviewer can use it as the review map" + }, + { + "id": "c14", + "kind": "boundary", + "text": "delivery-side closure only: the skill summarizes and cross-references after execution - it does not orchestrate work, gate merges (assign-to-workforce owns the TDD gate), mark plan tasks done, or mutate devague state; reads of plan and frame state are read-only (issue 20)" + }, + { + "id": "h12", + "kind": "honesty", + "text": "a summarize-delivery run leaves .devague/ state byte-identical" + }, + { + "id": "c15", + "kind": "success_signal", + "text": "in an exported delivery summary, 100% of plan tasks are accounted for (delivered, partial, dropped, or blocked) and every delivery claim carries a confidence level plus at least 1 evidence pointer or an explicit unverified marker" + }, + { + "id": "h13", + "kind": "honesty", + "text": "both counts are checkable by inspection of the artifact alone, with no hidden context" + }, + { + "id": "c16", + "kind": "requirement", + "text": "the artifact follows the eight-section shape from the proposal: Intent, Planned Work, Actual Delivery, Mid-work Decisions, Drift From Plan, Evidence, Delivery Claims, and Remaining Work / Follow-up" + }, + { + "id": "h14", + "kind": "honesty", + "text": "the shipped template carries all eight sections and stays writable for partial and failed runs" + }, + { + "id": "c17", + "kind": "requirement", + "text": "summarize-delivery is registered as the fifth origin skill in docs/skill-sources.md (origin devague; guildmaster re-broadcasts to the mesh; never re-vendored back)" + }, + { + "id": "h15", + "kind": "honesty", + "text": "the skill-sources.md row lands in the same PR as the skill, so provenance never lags the kit" + } + ], + "tasks": [ + { + "id": "t1", + "summary": "author .claude/skills/summarize-delivery/SKILL.md - the method-only skill with the eight-section delivery-summary template and the no-overclaiming hard rules", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "SKILL.md exists at .claude/skills/summarize-delivery/SKILL.md with frontmatter name summarize-delivery, a trigger-phrase description, and type: command", + "the template carries all eight sections in order: Intent, Planned Work, Actual Delivery, Mid-work Decisions, Drift From Plan, Evidence, Delivery Claims, Remaining Work / Follow-up - and a worked example shows a partial or failed run with every section still writable", + "hard rules state: a claim without evidence is marked unverified (never done); partial and failed runs are valid inputs; verification is read-only (tests, lint, git log); no devague state mutation - the only devague moves documented are the read-only plan show, plan waves, scope --list, show, status", + "each delivery-claim template row carries claim, confidence (high, medium, low, or unverified), and evidence fields with resolvable pointers (commit SHA, file path, PR or issue number, test node id); each drift entry names the plan item, the reason, and exactly one of acceptable, risky, needs-follow-up", + "SKILL.md names the three readers (operator, final-PR human, later reader), documents the committed artifact path `docs/deliveries/-.md`, and documents degrading to git and PR history when no devague plan state exists" + ], + "deps": [], + "covers": [ + "c1", + "c2", + "c3", + "c4", + "c6", + "c7", + "c8", + "c9", + "c10", + "c11", + "c13", + "c14", + "c15", + "c16", + "h3", + "h4", + "h5", + "h6", + "h7", + "h9", + "h10", + "h11", + "h12", + "h14" + ], + "instruction": "model the file on .claude/skills/scope/SKILL.md (method-only precedent: no scripts dir, type: command, provenance section naming devague as origin and guildmaster as re-broadcaster) with the hard-rules voice of think/SKILL.md; source every section and rule from docs/specs/2026-07-09-summarize-delivery-skill.md; the Planned Work section must quote plan task ids and summaries verbatim from devague plan waves --json, mirroring the verbatim-brief rule in assign-to-workforce" + }, + { + "id": "t2", + "summary": "register summarize-delivery as the fifth origin skill in docs/skill-sources.md", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "the origin-skills table gains a summarize-delivery row: origin devague, downstream guildmaster then the mesh, re-vendor path, method-only note, new-in version", + "the surrounding prose is updated: the origin-skills intro and the vendoring-policy bullet enumerate all five origin skills including summarize-delivery", + "markdownlint-cli2 passes on docs/skill-sources.md" + ], + "deps": [], + "covers": [ + "c17", + "h15" + ], + "instruction": "mirror the scope row added in 0.15.0 (same table columns); update both enumerations (scope, think, spec-to-plan, assign-to-workforce) to include summarize-delivery" + }, + { + "id": "t3", + "summary": "update the flow docs: five-leg flow in CLAUDE.md, the assign-to-workforce handoff, and the README and docs/skills.md family mentions", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "CLAUDE.md project intent names the five-leg flow ending in summarize-delivery", + ".claude/skills/assign-to-workforce/SKILL.md gains an after-the-final-PR handoff section pointing to /summarize-delivery, mirroring how think hands off to /spec-to-plan", + "every other repo doc that enumerates the origin-skill family (README.md, docs/skills.md if they do) is updated consistently, and markdownlint-cli2 passes on every changed docs file" + ], + "deps": [], + "covers": [ + "c1" + ], + "instruction": "grep -rn assign-to-workforce across CLAUDE.md README.md docs/ .claude/skills/ to find every family enumeration; verify the on-disk CLAUDE.md status narrative first - it may already reflect 0.16.0 (issue 53 t1-t14 shipped in PR 58) - and only touch flow wording, not the release narrative" + }, + { + "id": "t4", + "summary": "dogfood: produce the first real delivery summary at docs/deliveries/ for the sharper-end-to-end-method run (issue 53, PRs 53, 54, 58)", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "docs/deliveries/2026-07-09-sharper-end-to-end-method.md exists, produced with the shipped template, all eight sections present", + "100% of the 2026-07-01 plan tasks (t1-t14) are accounted for as delivered, partial, dropped, or blocked, keyed by task id", + "every delivery claim row carries a confidence level plus at least 1 resolvable evidence pointer (commit SHA, file path, PR number, test node) or an explicit unverified marker", + "at least one drift entry with its classification, or an explicit no-drift statement backed by the task-by-task accounting", + "git status shows .devague/ untouched by producing the artifact, and markdownlint-cli2 passes on the artifact" + ], + "deps": [ + "t1" + ], + "covers": [ + "c2", + "c15", + "h1", + "h2", + "h6", + "h8", + "h9", + "h11", + "h12", + "h13" + ], + "instruction": "the planned-work baseline is docs/plans/2026-07-01-devague-ships-a-sharper-end-to-end-method-a-guided.md plus devague plan show --json and plan waves --json (read-only) for that plan; evidence sources: git log for commits 67a3eca (spec+plan, 0.14.1), 51669f7 (skills carry, 0.15.0), 92c60ca (t1-t14 implementation, 0.16.0), plus gh pr view 53 54 58; the 0.14.1 docs-only versus 0.16.0 implementation split is candidate drift material - verify before claiming" + }, + { + "id": "t5", + "summary": "release hygiene: minor version bump with changelog, full test suite, and repo-wide markdown lint", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "pyproject.toml version is bumped minor over main and CHANGELOG.md gains a Keep-a-Changelog entry naming the summarize-delivery skill, the skill-sources registration, the flow-doc updates, and the dogfood delivery artifact", + "uv run pytest -n auto passes and markdownlint-cli2 repo-wide passes" + ], + "deps": [ + "t1", + "t2", + "t3", + "t4" + ], + "covers": [], + "instruction": "use the vendored version-bump skill (scripts/bump.py minor); follow the 0.15.0 entry shape for a skills-only release - no CLI change means no new CLI docs" + } + ], + "risks": [ + { + "id": "r1", + "text": "the on-disk CLAUDE.md status narrative may lag the 0.16.0 (issue 53 t1-t14) implementation - t3 verifies on disk before editing and corrects only flow wording", + "kind": "unknown_nonblocking", + "task_id": null + }, + { + "id": "r2", + "text": "guildmaster re-vendoring cadence for the new origin skill is outside this repo - the mesh copy lands whenever guildmaster next pulls", + "kind": "out_of_scope", + "task_id": null + } + ] +} diff --git a/docs/plans/2026-07-09-summarize-delivery-skill.md b/docs/plans/2026-07-09-summarize-delivery-skill.md new file mode 100644 index 0000000..e0ae4d7 --- /dev/null +++ b/docs/plans/2026-07-09-summarize-delivery-skill.md @@ -0,0 +1,61 @@ +# Build Plan — summarize-delivery skill + +slug: `summarize-delivery-skill` · status: `exported` · from frame: `summarize-delivery-skill` + +> devague closes the loop: after assign-to-workforce executes a plan, the new summarize-delivery skill turns the run into an accountability artifact - planned versus actual delivery, mid-work decisions, plan drift, evidence-backed delivery claims, and remaining work + +## Tasks + +### t1 — author .claude/skills/summarize-delivery/SKILL.md - the method-only skill with the eight-section delivery-summary template and the no-overclaiming hard rules + +- instruction: model the file on .claude/skills/scope/SKILL.md (method-only precedent: no scripts dir, type: command, provenance section naming devague as origin and guildmaster as re-broadcaster) with the hard-rules voice of think/SKILL.md; source every section and rule from docs/specs/2026-07-09-summarize-delivery-skill.md; the Planned Work section must quote plan task ids and summaries verbatim from devague plan waves --json, mirroring the verbatim-brief rule in assign-to-workforce +- covers: c1, c2, c3, c4, c6, c7, c8, c9, c10, c11, c13, c14, c15, c16, h3, h4, h5, h6, h7, h9, h10, h11, h12, h14 +- acceptance: + - SKILL.md exists at .claude/skills/summarize-delivery/SKILL.md with frontmatter name summarize-delivery, a trigger-phrase description, and type: command + - the template carries all eight sections in order: Intent, Planned Work, Actual Delivery, Mid-work Decisions, Drift From Plan, Evidence, Delivery Claims, Remaining Work / Follow-up - and a worked example shows a partial or failed run with every section still writable + - hard rules state: a claim without evidence is marked unverified (never done); partial and failed runs are valid inputs; verification is read-only (tests, lint, git log); no devague state mutation - the only devague moves documented are the read-only plan show, plan waves, scope --list, show, status + - each delivery-claim template row carries claim, confidence (high, medium, low, or unverified), and evidence fields with resolvable pointers (commit SHA, file path, PR or issue number, test node id); each drift entry names the plan item, the reason, and exactly one of acceptable, risky, needs-follow-up + - SKILL.md names the three readers (operator, final-PR human, later reader), documents the committed artifact path `docs/deliveries/-.md`, and documents degrading to git and PR history when no devague plan state exists + +### t2 — register summarize-delivery as the fifth origin skill in docs/skill-sources.md + +- instruction: mirror the scope row added in 0.15.0 (same table columns); update both enumerations (scope, think, spec-to-plan, assign-to-workforce) to include summarize-delivery +- covers: c17, h15 +- acceptance: + - the origin-skills table gains a summarize-delivery row: origin devague, downstream guildmaster then the mesh, re-vendor path, method-only note, new-in version + - the surrounding prose is updated: the origin-skills intro and the vendoring-policy bullet enumerate all five origin skills including summarize-delivery + - markdownlint-cli2 passes on docs/skill-sources.md + +### t3 — update the flow docs: five-leg flow in CLAUDE.md, the assign-to-workforce handoff, and the README and docs/skills.md family mentions + +- instruction: grep -rn assign-to-workforce across CLAUDE.md README.md docs/ .claude/skills/ to find every family enumeration; verify the on-disk CLAUDE.md status narrative first - it may already reflect 0.16.0 (issue 53 t1-t14 shipped in PR 58) - and only touch flow wording, not the release narrative +- covers: c1 +- acceptance: + - CLAUDE.md project intent names the five-leg flow ending in summarize-delivery + - .claude/skills/assign-to-workforce/SKILL.md gains an after-the-final-PR handoff section pointing to /summarize-delivery, mirroring how think hands off to /spec-to-plan + - every other repo doc that enumerates the origin-skill family (README.md, docs/skills.md if they do) is updated consistently, and markdownlint-cli2 passes on every changed docs file + +### t4 — dogfood: produce the first real delivery summary at docs/deliveries/ for the sharper-end-to-end-method run (issue 53, PRs 53, 54, 58) + +- instruction: the planned-work baseline is docs/plans/2026-07-01-devague-ships-a-sharper-end-to-end-method-a-guided.md plus devague plan show --json and plan waves --json (read-only) for that plan; evidence sources: git log for commits 67a3eca (spec+plan, 0.14.1), 51669f7 (skills carry, 0.15.0), 92c60ca (t1-t14 implementation, 0.16.0), plus gh pr view 53 54 58; the 0.14.1 docs-only versus 0.16.0 implementation split is candidate drift material - verify before claiming +- depends on: t1 +- covers: c2, c15, h1, h2, h6, h8, h9, h11, h12, h13 +- acceptance: + - docs/deliveries/2026-07-09-sharper-end-to-end-method.md exists, produced with the shipped template, all eight sections present + - 100% of the 2026-07-01 plan tasks (t1-t14) are accounted for as delivered, partial, dropped, or blocked, keyed by task id + - every delivery claim row carries a confidence level plus at least 1 resolvable evidence pointer (commit SHA, file path, PR number, test node) or an explicit unverified marker + - at least one drift entry with its classification, or an explicit no-drift statement backed by the task-by-task accounting + - git status shows .devague/ untouched by producing the artifact, and markdownlint-cli2 passes on the artifact + +### t5 — release hygiene: minor version bump with changelog, full test suite, and repo-wide markdown lint + +- instruction: use the vendored version-bump skill (scripts/bump.py minor); follow the 0.15.0 entry shape for a skills-only release - no CLI change means no new CLI docs +- depends on: t1, t2, t3, t4 +- acceptance: + - pyproject.toml version is bumped minor over main and CHANGELOG.md gains a Keep-a-Changelog entry naming the summarize-delivery skill, the skill-sources registration, the flow-doc updates, and the dogfood delivery artifact + - uv run pytest -n auto passes and markdownlint-cli2 repo-wide passes + +## Risks + +- [unknown_nonblocking] the on-disk CLAUDE.md status narrative may lag the 0.16.0 (issue 53 t1-t14) implementation - t3 verifies on disk before editing and corrects only flow wording +- [out_of_scope] guildmaster re-vendoring cadence for the new origin skill is outside this repo - the mesh copy lands whenever guildmaster next pulls From ae22bbd14d59daf2a3a541128820a0bc097cf78f Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Thu, 9 Jul 2026 18:34:13 +0300 Subject: [PATCH 03/10] register summarize-delivery as fifth origin skill in skill-sources.md Add summarize-delivery row to the origin-skills table and update all surrounding prose enumerations (intro, think/scope note, vendoring-policy bullet) to include the new skill alongside scope, think, spec-to-plan, and assign-to-workforce. --- docs/skill-sources.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/skill-sources.md b/docs/skill-sources.md index d4cb717..527c1b1 100644 --- a/docs/skill-sources.md +++ b/docs/skill-sources.md @@ -35,13 +35,13 @@ upstream repo are shared across all rows. ## Origin skills (outbound) -Not every skill here is inbound. The `scope`, `think`, `spec-to-plan`, and -`assign-to-workforce` skills are **authored and maintained in this repo** — +Not every skill here is inbound. The `scope`, `think`, `spec-to-plan`, `assign-to-workforce`, +and `summarize-delivery` skills are **authored and maintained in this repo** — devague is their origin/upstream, not a downstream consumer. The devague agent dogfoods them to operate the devague CLI while improving the tool. The flow runs the *opposite* direction of the table above: `guildmaster` re-vendors them from here and re-broadcasts them to the mesh. (The skill names are `scope` / `think` / -`spec-to-plan` / `assign-to-workforce`; the product/CLI they drive is `devague`. +`spec-to-plan` / `assign-to-workforce` / `summarize-delivery`; the product/CLI they drive is `devague`. `think` was renamed from `devague` in 0.4.0 — when guildmaster re-vendors, it must relearn the new name.) Because devague is upstream, these are **not** re-vendored back from guildmaster's re-broadcast copies — doing so would be circular (see the @@ -58,6 +58,7 @@ culture/agex backend) match the source and need no patch. `scope` (new in | `think` | **devague** (here: `.claude/skills/think/`) | `guildmaster`, then the AgentCulture mesh | Operator for the **idea→spec** leg of the deterministic devague CLI: portable resolution, driving the flat `devague ` verbs (`status` is now a first-class CLI verb, not embedded Python). Renamed from `devague` in 0.4.0. `guildmaster` re-vendors it from `../devague/.claude/skills/think/` and broadcasts it to the mesh. | | `spec-to-plan` | **devague** (here: `.claude/skills/spec-to-plan/`) | `guildmaster`, then the AgentCulture mesh | Operator for the **spec→plan** leg (`devague plan ...`): portable resolution over the plan convergence gate. New in 0.4.0. Re-vendor from `../devague/.claude/skills/spec-to-plan/`. | | `assign-to-workforce` | **devague** (here: `.claude/skills/assign-to-workforce/`) | `guildmaster`, then the AgentCulture mesh | Operator for the **implementation** leg (fan out `devague plan waves` to parallel agents in isolated git worktrees, with TDD-gated merges by the main agent). Three human gates only: spec / implementation split plan / final PR. The devague CLI remains non-orchestrating (#20) — this skill is the convention + helper, not new CLI behavior. New in 0.7.0. Re-vendor from `../devague/.claude/skills/assign-to-workforce/`. | +| `summarize-delivery` | **devague** (here: `.claude/skills/summarize-delivery/`) | `guildmaster`, then the AgentCulture mesh | Operator for the **delivery-side closure** leg (runs after `/assign-to-workforce`). Method-only in v1 — `SKILL.md` + template; no entry-point script, no new CLI verb. New in 0.17.0. Re-vendor from `../devague/.claude/skills/summarize-delivery/`. | `cite, don't import` applies to both — downstream copies them, no symlink/dependency. Written portable-first so they pass guildmaster's @@ -72,5 +73,5 @@ symlink/dependency. Written portable-first so they pass guildmaster's - **Diverge intentionally.** Record any divergence in the table above and in the downstream `SKILL.md` frontmatter `description`. - **Don't re-vendor devague-origin skills.** `scope` / `think` / `spec-to-plan` / - `assign-to-workforce` are authored here; pull fixes forward into this repo, not + `assign-to-workforce` / `summarize-delivery` are authored here; pull fixes forward into this repo, not back from guildmaster's re-broadcast copies. From a5ea5e04077c016f53fc8da9911b5b87db96fbcf Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Thu, 9 Jul 2026 18:37:33 +0300 Subject: [PATCH 04/10] =?UTF-8?q?feat(skills):=20summarize-delivery=20?= =?UTF-8?q?=E2=80=94=20the=20delivery-side=20closure=20leg=20[t1]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/skills/summarize-delivery/SKILL.md | 379 +++++++++++++++++++++ 1 file changed, 379 insertions(+) create mode 100644 .claude/skills/summarize-delivery/SKILL.md diff --git a/.claude/skills/summarize-delivery/SKILL.md b/.claude/skills/summarize-delivery/SKILL.md new file mode 100644 index 0000000..fc63a6c --- /dev/null +++ b/.claude/skills/summarize-delivery/SKILL.md @@ -0,0 +1,379 @@ +--- +name: summarize-delivery +description: > + Close the loop after an assign-to-workforce run by turning what actually + happened into an accountability artifact — planned versus actual delivery, + mid-work decisions, plan drift, evidence-backed delivery claims, and remaining + work. The plan the user confirmed is the contract; this skill records where + execution obeyed it, where it changed, and what is genuinely safe to claim as + delivered. Runs on complete, partial, AND failed runs — failure is reported + faithfully, never smoothed over. Use when the user says "summarize delivery", + "delivery summary", "wrap up", "close the loop", "what did we actually ship", + or "plan versus actual", or after assign-to-workforce merges (or fails to + merge) a plan's waves. Authored and maintained in agentculture/devague + (origin = devague); guildmaster pulls this skill from here and broadcasts it + to the AgentCulture mesh — it is NOT vendored from guildmaster like the + inbound skills here. +type: command +--- + +# summarize-delivery — turn a workforce run into an accountability artifact + +The skill is named **`summarize-delivery`**; it is the **delivery-side closure +leg** of the devague method — the *fifth* leg, run *after* the sibling +**`/assign-to-workforce`** skill has executed (or attempted to execute) a +converged plan. Where `/assign-to-workforce` takes the plan to delivery, this +skill *summarizes* that delivery: it separates what was **planned** from what +was **actually delivered**, records the **mid-work decisions** and **plan +drift** the execution produced, states **delivery claims** with evidence and +confidence, and names the **remaining work**. + +The plan the user confirmed is a **contract, not a fiction**. Agents make +mid-work decisions, hit constraints, cut scope, and produce delivery claims +that were never in the plan. Until now the flow had no wrap-up leg to record +any of it. This skill is that leg: the summary records where execution obeyed +the contract, where it changed, and what is actually safe to claim as +delivered. + +It is **not** a polite progress report and **not** a restatement of the plan. +It is an accountability artifact — auditable by a human who never watched the +run. + +## The three readers + +Write for exactly these three, and no one who was present for the execution: + +1. **The operator (main agent)** closing a workforce run — assembling the + ground truth of what merged, what failed, and what still needs doing. +2. **The human owner at the final PR gate** — who uses the artifact as the + review map: every delivery claim traces to a plan task or an explicit drift + entry, so the plan-versus-actual comparison is mechanical, not rhetorical. +3. **Any later reader** who needs to know what actually shipped without + replaying the execution transcript. The artifact is committed and + self-contained; nothing in it depends on unrecorded memory of the run. + +## Method-only — no script, no CLI verb + +This is a **method-only** skill (v1), modelled on `/scope` at its birth: a +`SKILL.md` with an output template and no entry-point script, no new CLI verb. +The deterministic devague CLI surface is **unchanged** — Devague never spawns +agents, marks tasks done, gates merges (`/assign-to-workforce` owns the TDD +gate), or mutates delivery state. The CLI stays deterministic and +non-orchestrating (issue +[#20](https://github.com/agentculture/devague/issues/20)); the summary is +agent-side work. A future devague *delivery engine* — a third structural peer +with a delivery store and a deterministic no-overclaim gate — is parked as +follow-up, deferred until dogfooding the method shows machine state is needed. + +Because there is no script, this skill invokes the read-only devague moves +directly (if `devague` isn't on your PATH: `uv tool install devague`). + +## The method + +1. **Establish the planned-work baseline — verbatim.** Read the plan the run + executed. When the run was devague-driven, the baseline is the plan's tasks, + acceptance criteria, and waves, available read-only via + `` `devague plan show [--json]` `` and `` `devague plan waves --json` `` — + the same enriched payload `/assign-to-workforce` fans out, keyed by task id + with each task's `summary`, `instruction`, `acceptance_criteria`, and + `covers`. Quote task ids and summaries **verbatim** into the Planned Work + section — mirroring the verbatim-brief rule in `/assign-to-workforce`. Drift + is then measured against the contract the user confirmed, never against a + paraphrase. +2. **Establish actual delivery.** Reconcile the baseline against what merged: + the merged branches, commits, and PRs of the run. **Every** plan task must + be accounted for as **delivered / partial / dropped / blocked**, keyed by + task id — 100 %, no silent omissions. +3. **Record mid-work decisions.** Every constraint discovered, scope cut, or + choice made during execution that was *not* in the plan. +4. **Classify drift against the plan.** Any plan task whose delivery differs + from its contract becomes a drift entry — exhaustive relative to the plan, + never silently normalized. Each entry names the plan item it diverges from, + the reason, and **exactly one** classification: `acceptable` / `risky` / + `needs-follow-up`. +5. **Gather evidence, read-only.** You may run read-only verification — the + test suite, the linters, `git log` — to substantiate a claim *before* you + write it. Verification never mutates code or state. A claim you cannot + verify stays `unverified`. +6. **State delivery claims with confidence + evidence.** Each claim carries a + confidence level (`high` / `medium` / `low` / `unverified`) and at least one + **resolvable** evidence pointer, or an explicit `unverified` marker. A claim + without evidence is `unverified` — never asserted as done. +7. **Name the remaining work.** What is incomplete, deferred, or newly + discovered — including any failure and its cause. +8. **Write the artifact and commit it.** Fill the eight-section template into a + committed, durable file at `docs/deliveries/-.md` — the + structural peer of `docs/specs/` and `docs/plans/`. Reads of plan and frame + state stay read-only; producing the artifact leaves `.devague/` byte- + identical. + +## The eight-section template + +Fill this in verbatim — all eight sections, in this order. Every section stays +writable for a **partial or failed** run; nothing here requires all waves +merged, and there is no completion precondition (a run that merged zero waves +is still a valid input). + +```markdown +# Delivery Summary — + +plan: `` · run: `` · date: `` +baseline: `` + +## Intent + + + +## Planned Work + + + +- `t1` — +- `t2` — +- ... + +## Actual Delivery + + + +| Plan task | Status | What actually landed | +|-----------|--------|----------------------| +| `t1` | delivered | | +| `t2` | partial | | +| `t3` | blocked | | + +## Mid-work Decisions + + + +- — + +## Drift From Plan + + + +| Plan item | Reason for divergence | Classification | +|-----------|-----------------------|----------------| +| `t2` | | needs-follow-up | +| `t3` | | risky | + +## Evidence + + + +- tests: `` — +- lint: `` — +- commits: `..` +- PRs / issues: <#NN, ...> + +## Delivery Claims + + + +| Claim | Confidence | Evidence | +|-------|------------|----------| +| | high | commit `` / file `` | +| | medium | PR `#` · test `` | +| | unverified | (no evidence — not claimed done) | + +## Remaining Work / Follow-up + + + +- — +``` + +### Delivery Claims — the row contract + +Every Delivery Claims row carries three fields: + +- **Claim** — the specific thing asserted as delivered. +- **Confidence** — exactly one of `high` / `medium` / `low` / `unverified`. +- **Evidence** — at least one **resolvable** pointer, or the explicit + `unverified` marker. A resolvable pointer is one a reader can follow: a + **commit SHA** that exists, a **file path** that is present, a **PR or issue + number** that is real, or a **test node id** that ran. "It works" is not + evidence. + +### Drift From Plan — the entry contract + +Every Drift From Plan entry names three things: + +- **The plan item** it diverges from (by task id, quoted from the plan). +- **The reason** for the divergence. +- **Exactly one** classification: `acceptable` (a defensible deviation), + `risky` (may cause a problem; flag it), or `needs-follow-up` (leaves work + the plan assumed done). + +## Degrading when there is no plan state + +The summary is producible from **durable** inputs — plan state, git history, PR +links, test output — and never depends on unrecorded memory of the run. When +the run was devague-driven, the plan (tasks, acceptance criteria, waves) and +the exported plan-md are the planned-work baseline. + +**When no devague plan state exists, degrade to git history and PR history as +the planned-work baseline — and SAY SO in the artifact** (in the `baseline:` +line and the Planned Work section). The delivery summary is still a valid +accountability artifact; it just names its baseline honestly instead of +pretending a plan existed. + +## The only devague moves this skill uses — all read-only + +This skill **never mutates devague state**. The complete set of devague moves +it documents is read-only: + +| Move | What it reads | +|------|---------------| +| `devague plan show [--json]` | The plan's tasks, acceptance criteria, dependencies. | +| `devague plan waves --json` | The wave batches + per-task `summary` / `instruction` / `acceptance_criteria` / `covers`, keyed by id — the verbatim planned-work baseline. | +| `devague scope --list [--json]` | Recorded scope-exploration findings, if the frame carried any. | +| `devague show [--json]` | A frame / plan rendered for reading. | +| `devague status [--json]` | Where a frame stands (read-only next-move helper). | + +No other devague command appears in this method. Producing a delivery summary +leaves `.devague/` byte-identical (issue +[#20](https://github.com/agentculture/devague/issues/20)). + +## Hard rules (do not violate) + +These are the point of the method — a delivery summary must be trustworthy. + +- **No overclaiming.** A delivery claim without evidence is marked `unverified`, + never asserted as done. The `unverified` marker survives into the committed + artifact; no downstream step upgrades a claim's confidence without new + evidence. +- **Partial and failed runs are valid inputs.** There is no completion + precondition — a run that merged zero waves is still a valid input. Failure + is reported faithfully: it appears under Drift and Remaining Work with its + cause, and no delivery claim says "done". No section ever becomes unwritable. +- **Verification is read-only.** You may run the test suite, the linters, and + `git log` to substantiate a claim before writing it. Verification **never** + mutates code or state. A claim you cannot verify stays `unverified`. +- **No devague state mutation.** The only devague moves this skill uses are the + read-only `plan show`, `plan waves`, `scope --list`, `show`, and `status` + (see the table above). Never run a mutating devague command, and never run + `devague plan` inside a task worktree to "mark a task done" — that is + `/assign-to-workforce`'s boundary too (#20). +- **Account for 100 % of plan tasks.** Every plan task appears in Actual + Delivery as delivered / partial / dropped / blocked — no silent omissions. + Both the task count and the claim-evidence coverage are checkable by + inspecting the artifact alone, with no hidden context. +- **Quote the plan verbatim.** Planned Work quotes task ids and summaries + verbatim from `devague plan waves --json`. Drift is measured against the + confirmed contract, not a reworded version of it. + +## Worked example + +A **partial** run: three tasks were planned, two merged cleanly, and the third +failed its post-merge TDD gate and was reverted. Every section is still +writable — nothing about the failure makes the artifact unproducible. + +```bash +# 1. Establish the planned-work baseline — read-only, quoted verbatim. +devague plan waves --json # -> {"plan": "widget-export", "waves": [...], + # "tasks": {"t1": {...}, "t2": {...}, "t3": {...}}} +devague plan show # human-readable plan for the Intent paragraph + +# 2. Establish actual delivery — read-only reconciliation. +git log --oneline main~4..main # what merged +gh pr view 71 # the run's PR (evidence pointers) +uv run pytest tests/test_export.py::test_widget_round_trips -q # verify a claim +``` + +The resulting `docs/deliveries/2026-07-09-widget-export.md`: + +```markdown +# Delivery Summary — widget export + +plan: `widget-export` · run: `partial` · date: `2026-07-09` +baseline: `devague plan (widget-export)` + +## Intent + +Ship the `widget export` command as three independent tasks fanned out by +/assign-to-workforce. + +## Planned Work + +Quoted verbatim from `devague plan waves --json`: + +- `t1` — add the `export` verb to the CLI chassis +- `t2` — implement the widget-md renderer +- `t3` — wire the convergence gate into `export` + +## Actual Delivery + +| Plan task | Status | What actually landed | +|-----------|--------|----------------------| +| `t1` | delivered | `export` verb registered; merged in PR `#71` | +| `t2` | delivered | renderer added at `devague/render/widget_md.py` | +| `t3` | blocked | post-merge tests failed; merge reverted | + +## Mid-work Decisions + +- t2 renders an absent field as an empty line rather than filler — matches the + no-fabrication rule the plan assumed but did not spell out. + +## Drift From Plan + +| Plan item | Reason for divergence | Classification | +|-----------|-----------------------|----------------| +| `t3` | gate raised on an unconverged plan; reverted, not delivered | needs-follow-up | + +## Evidence + +- tests: `tests/test_export.py::test_widget_round_trips` — pass +- tests: `tests/test_export.py::test_gate_blocks_unconverged` — fail +- commits: `main~4..main` +- PRs: `#71` + +## Delivery Claims + +| Claim | Confidence | Evidence | +|-------|------------|----------| +| the `export` verb ships and round-trips | high | test `tests/test_export.py::test_widget_round_trips` · PR `#71` | +| the widget-md renderer exists | high | file `devague/render/widget_md.py` | +| the convergence gate blocks unconverged exports | unverified | t3 reverted — not claimed done | + +## Remaining Work / Follow-up + +- `t3` — fix the gate wiring so `test_gate_blocks_unconverged` passes, then + re-run the TDD merge gate. Blocking for the feature's completeness. +``` + +Note what the failure did: it flowed into Actual Delivery (`blocked`), Drift +(`needs-follow-up`), Delivery Claims (`unverified`), and Remaining Work — and +no claim overstated it. That is the whole point. + +## After the summary — the final PR gate + +The delivery summary is the review map for `/assign-to-workforce`'s third human +gate (the final PR). Commit `docs/deliveries/-.md` alongside +the run's work so the reviewer can audit planned-versus-actual without replaying +the transcript. This skill does not open the PR or mutate any state — it +produces the artifact the human reviews. + +## Provenance + +This is a **first-party** skill — its origin is `agentculture/devague`, the +*fifth* in the outbound family after `/scope`, `/think`, `/spec-to-plan`, and +`/assign-to-workforce`, covering the delivery-side closure leg after a plan is +executed. guildmaster pulls it from here and broadcasts it to the AgentCulture +mesh; because devague is upstream, it is **never re-vendored back** from +guildmaster's re-broadcast copy. The `cite, don't import` policy still holds: +downstream repos copy it, they don't symlink or depend on it. See +`docs/skill-sources.md`. From 91dfc9979aeff1a6c0d04a51da70d0cf7feb19da Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Thu, 9 Jul 2026 18:40:11 +0300 Subject: [PATCH 05/10] docs: five-leg flow ends in summarize-delivery; workforce handoff [t3] --- .claude/skills/assign-to-workforce/SKILL.md | 23 +++++++++++++++++++++ CLAUDE.md | 9 ++++---- README.md | 14 ++++++++----- docs/skills.md | 17 +++++++++++++++ 4 files changed, 54 insertions(+), 9 deletions(-) diff --git a/.claude/skills/assign-to-workforce/SKILL.md b/.claude/skills/assign-to-workforce/SKILL.md index 11adfaa..4ccbd49 100644 --- a/.claude/skills/assign-to-workforce/SKILL.md +++ b/.claude/skills/assign-to-workforce/SKILL.md @@ -199,6 +199,29 @@ Once all waves are merged and the full test suite passes, the main agent opens a PR via the `cicd` skill (`agex pr open`). The human reviews and merges. This is the last and only remaining human gate. +## After the final PR — summarize the delivery + +Once the final PR is **merged**, close the execution loop cleanly instead of +stopping at a green merge: + +1. **Summarize the delivery.** Run the sibling **`/summarize-delivery`** skill — + the delivery-side closure leg. It turns the run into a committed + accountability artifact (`docs/deliveries/-.md`) that + records planned-versus-actual delivery, the mid-work decisions the workforce + made, where execution drifted from the plan, evidence-backed delivery claims + (a claim without evidence stays `unverified`, never asserted as done), and + any remaining work. The `devague plan waves --json` payload you fanned out is + the planned-work baseline it compares actuals against. +2. **It closes partial and failed runs too.** `/summarize-delivery` does not + require every wave to have merged — a run that shipped only some tasks, or + none, still produces a truthful artifact: the failure lands under drift and + remaining work, and no claim says done without evidence. + +This is the accountability wrap-up after the three gates, not a fourth gate — +`/summarize-delivery` is method-only and read-only (#20): it summarizes the run, +it does not orchestrate, gate merges, or mutate devague state. Don't stop at +"PR merged" — the standing flow is **merge, then `/summarize-delivery`**. + ## Hard rules (do not violate) These protect the human-gate contract and the TDD guarantee. diff --git a/CLAUDE.md b/CLAUDE.md index fa2685e..60c641c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -210,8 +210,9 @@ plan method: seed a plan from that converged frame and converge it on coverage, acceptance criteria, and an acyclic dependency order before exporting a plan. The operator skills cover the legs in flow order: **`/scope`** (idea→explored scope, the optional opening leg), **`/think`** (idea→spec), **`/spec-to-plan`** -(spec→plan), and **`/assign-to-workforce`** (plan→parallel implementation); the -product/CLI they drive is **`devague`**. +(spec→plan), **`/assign-to-workforce`** (plan→parallel implementation), and +**`/summarize-delivery`** (execution→a committed accountability artifact, the +delivery-side closure leg); the product/CLI they drive is **`devague`**. This is a **state machine over claims, honesty conditions, open vagueness, and convergence** driven by LLM-chosen moves — not a linear wizard. The CLI is @@ -237,8 +238,8 @@ steward→guildmaster cutover; `steward` is still a sibling but no longer broadcasts). Vendored skills are cited, not imported (cite-don't-import): copy from `../guildmaster/.claude/skills//` and track provenance in `docs/skill-sources.md`. The exception is devague's own `scope` / `think` / -`spec-to-plan` / `assign-to-workforce` — devague is their origin, so guildmaster -re-broadcasts them *from* here; never re-vendor them back. +`spec-to-plan` / `assign-to-workforce` / `summarize-delivery` — devague is their +origin, so guildmaster re-broadcasts them *from* here; never re-vendor them back. ## Stack expectations (when code lands) diff --git a/README.md b/README.md index c434de2..e4a10d7 100644 --- a/README.md +++ b/README.md @@ -78,8 +78,12 @@ committed. ## Driving it from an agent -Inside AgentCulture, an assistant drives this CLI through two operator skills — -**`/think`** (idea→spec) and **`/spec-to-plan`** (spec→plan) — which add a -portable wrapper and a `status` next-move helper over the convergence gate. The -CLI is the deterministic affordance; the agent decides the next move. See -`CLAUDE.md` for that workflow and `docs/superpowers/specs/` for the design docs. +Inside AgentCulture, an assistant drives this CLI through a family of operator +skills that cover the flow end to end, in order: **`/scope`** (idea→explored +scope, the optional opening leg), **`/think`** (idea→spec), **`/spec-to-plan`** +(spec→plan), **`/assign-to-workforce`** (plan→parallel implementation), and +**`/summarize-delivery`** (execution→a committed accountability artifact). The +CLI-driving pair — `/think` and `/spec-to-plan` — add a portable wrapper and a +`status` next-move helper over the convergence gate; the CLI is the +deterministic affordance and the agent decides the next move. See `CLAUDE.md` +for that workflow and `docs/superpowers/specs/` for the design docs. diff --git a/docs/skills.md b/docs/skills.md index dbc976e..6421847 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -143,6 +143,7 @@ A skill drives the deterministic CLI and adds no business logic of its own: | `think` | idea → spec (working backwards) | the flat `devague ` verbs | | `spec-to-plan` | spec → plan (working forwards) | the `devague plan ` group | | `assign-to-workforce` | plan → parallel implementation | reads `devague plan waves` (read-only) | +| `summarize-delivery` | execution → accountability artifact (the delivery-side closure leg) | method-only; reads plan / git / PR / test evidence (read-only) | ### `scope` — idea → explored scope (method-only) @@ -205,6 +206,22 @@ from `plan show --json` / the exported plan-md — including the per-task [`.claude/skills/assign-to-workforce/`](https://github.com/agentculture/devague/blob/main/.claude/skills/assign-to-workforce/SKILL.md) (`SKILL.md` + `scripts/assign-to-workforce.sh`). +### `summarize-delivery` — execution run → accountability artifact + +The delivery-side closure leg: after `/assign-to-workforce` executes a plan — +complete, partial, or **failed** — record what actually shipped as a committed +accountability artifact at `docs/deliveries/-.md`. It +separates planned work from actual delivery, captures mid-work decisions and +plan drift, and states every delivery claim with a confidence level and evidence +pointers — a claim without evidence is marked `unverified`, never asserted as +done. Method-only in v1 (a `SKILL.md` + an eight-section template; no +entry-point script and no new CLI verb — the deterministic CLI surface is +unchanged, #20). New in 0.17.0. + +- Source: + [`.claude/skills/summarize-delivery/`](https://github.com/agentculture/devague/blob/main/.claude/skills/summarize-delivery/SKILL.md) + (`SKILL.md` + an eight-section delivery-summary template). + ## See also - `devague learn skills` / `devague learn skills:all` / `devague learn From e69bcea877c199bd8e77d5e7822a975b210f96a5 Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Thu, 9 Jul 2026 18:48:38 +0300 Subject: [PATCH 06/10] =?UTF-8?q?docs(deliveries):=20first=20delivery=20su?= =?UTF-8?q?mmary=20=E2=80=94=20sharper=20end-to-end=20method=20[t4]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2026-07-09-sharper-end-to-end-method.md | 140 ++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 docs/deliveries/2026-07-09-sharper-end-to-end-method.md diff --git a/docs/deliveries/2026-07-09-sharper-end-to-end-method.md b/docs/deliveries/2026-07-09-sharper-end-to-end-method.md new file mode 100644 index 0000000..c5039c9 --- /dev/null +++ b/docs/deliveries/2026-07-09-sharper-end-to-end-method.md @@ -0,0 +1,140 @@ +# Delivery Summary — devague ships a sharper end-to-end method + +plan: `devague-ships-a-sharper-end-to-end-method-a-guided` · run: `complete` · date: `2026-07-09` +baseline: `devague plan (devague-ships-a-sharper-end-to-end-method-a-guided)` + +## Intent + +This run set out to deliver the **sharper end-to-end method** for devague +(issue [#53](https://github.com/agentculture/devague/issues/53)): a guided +scope-exploration stage before the announcement frame, per-item verbatim +instructions on every claim and task, sharper spec/plan/frame exports, a +tightened structural convergence gate, and a guided plan-to-fanout leg that +carries those instructions to the workforce. It executed the converged plan +`devague-ships-a-sharper-end-to-end-method-a-guided` — 14 tasks over 5 +file-disjoint waves — read back read-only from `devague plan waves --json`. +This summary is itself the first real use of the `summarize-delivery` skill it +reports against being available (that skill shipped in a later run). + +## Planned Work + +Quoted verbatim from `devague plan waves --json` (task id and summary, keyed by +id). The plan's waves are `[t1, t2]` · `[t3, t4, t5, t6, t7, t8, t12]` · +`[t9, t10, t11]` · `[t13]` · `[t14]`. + +- `t1` — Frame schema: scope entries + per-item instruction fields (frame.py, store.py) +- `t2` — Plan schema: per-task instruction field (plan.py, plan_store.py) +- `t3` — New CLI move: devague scope (cli/_commands/scope.py + registration) +- `t4` — Instruction flags on frame moves: capture/interrogate --instruction (capture.py, interrogate.py) +- `t5` — Instruction flags on plan moves: plan task --instruction + `instruct ` (cli/_commands/plan.py) +- `t6` — Sharper frame renderers: instruction blocks + scope provenance (render/spec_md.py, render/frame_md.py) +- `t7` — Frame gate tightening: deterministic structural sharpness checks (convergence.py) +- `t8` — Plan gate tightening: instruction warnings (plan_convergence.py) +- `t9` — Sharper plan renderer + enriched waves payload (render/plan_md.py, waves output) +- `t10` — Teaching surface: learn/explain/status know the scope stage (learn.py, explain.py, cli/_status.py) +- `t11` — Operator skills teach the new surface (/think and /spec-to-plan SKILL.md) +- `t12` — Docs: spec-contract, llm-guidance, skills.md cover scope entity + instruction fields +- `t13` — assign-to-workforce consumes the enriched waves payload as the subagent brief +- `t14` — Dogfooded end-to-end run + boundary audit + +## Actual Delivery + +Every one of the 14 plan tasks is accounted for. All 14 landed in a single +implementation increment — commit `92c60ca` (release 0.16.0, PR +[#58](https://github.com/agentculture/devague/pull/58)) — verified against the +live CLI and the present source/test files, not the commit message. Status +breakdown: **14 delivered, 0 partial, 0 dropped, 0 blocked.** + +| Plan task | Status | What actually landed | +|-----------|--------|----------------------| +| `t1` | delivered | Frame schema v2: `ScopeEntry` state + per-item instruction fields on claims/honesty conditions; `frame.py` `SCHEMA_VERSION = 2` (fail-closed, empty defaults for v1 files). | +| `t2` | delivered | Plan schema v2: `Task.instruction`; `plan.py` `PLAN_SCHEMA_VERSION = 2`; round-trips verbatim through save/load. | +| `t3` | delivered | `devague scope` CLI move present live (`surface` arg, `--finding`, `--seeds ` with unknown-id refusal, `--list`, `--json`). | +| `t4` | delivered | `capture --instruction` and `interrogate --instruction` present live; instruction stored verbatim; changing it re-flips a confirmed item to `proposed`. | +| `t5` | delivered | `plan task --instruction` flag and the new `plan instruct ` verb both present live in the plan subcommand group. | +| `t6` | delivered | Sharper frame/spec renderers: `render/spec_md.py` + `render/frame_md.py` render instruction blocks + a scope-provenance section (golden-file tested). | +| `t7` | delivered | Frame gate tightening in `convergence.py`: deterministic structural sharpness warnings (soft rollout, warnings-only). | +| `t8` | delivered | Plan gate tightening in `plan_convergence.py`: instruction-less-confirmed-task warnings. | +| `t9` | delivered | Sharper plan renderer + enriched `waves --json`: top-level `tasks` object carrying `{summary, instruction, acceptance_criteria, covers}` per id (confirmed present in the live payload). | +| `t10` | delivered | `devague learn` presents the scope stage as optional-but-recommended; `explain scope` and `explain question` both work (exit 0). See Drift — the summary also named `cli/_status.py`, which was not made scope-aware; the binding acceptance criteria (learn + explain only) are met. | +| `t11` | delivered | `.claude/skills/think/SKILL.md` and `.claude/skills/spec-to-plan/SKILL.md` document the scope stage, `--instruction` flags, and the enriched waves payload. | +| `t12` | delivered | `docs/spec-contract.md`, `docs/llm-guidance.md`, `docs/skills.md` all cover the scope entity + instruction fields + schema bumps. | +| `t13` | delivered | `.claude/skills/assign-to-workforce/SKILL.md` quotes the task instruction + acceptance criteria verbatim from `waves --json`; the operator-paraphrase step is gone. | +| `t14` | delivered | Dogfooded `scope → frame → spec → plan → fanout` e2e test (`tests/test_e2e_sharper_method.py`) + boundary audit (`tests/test_boundary_audit.py`, no LLM imports / no process spawning in the package). | + +## Mid-work Decisions + +Constraints and choices surfaced during execution that were not spelled out in +the plan (drawn from the run's commits, the CHANGELOG, and this verification). + +- The plan was executed as a **devague-orchestrated workforce fan-out** (5 waves, + one agent per task, TDD-gated merges) — the dogfooded application of + `/assign-to-workforce` on the plan itself. +- The structural sharpness gate (`t7`/`t8`) shipped as **warnings-only (soft + rollout)** rather than a hard blocker, so existing frames/plans still converge + while the new checks bed in. +- Schema evolution was handled **fail-closed**: both `SCHEMA_VERSION` and + `PLAN_SCHEMA_VERSION` bumped `1 → 2`; v1 files load with empty defaults, newer + versions refuse to load. +- A post-merge `refactor(interrogate)` extracted helpers to clear a SonarCloud + cognitive-complexity finding (S3776) inside PR `#58` — a quality fix made + during the run, not a planned task. + +## Drift From Plan + +Exhaustive relative to the plan. Tasks `t1`–`t9`, `t12`, and `t14` landed exactly +per their acceptance criteria and are not drift entries. The entries below are +the only divergences. + +| Plan item | Reason for divergence | Classification | +|-----------|-----------------------|----------------| +| release cadence (whole plan) | The single 14-task plan shipped across **three** versions: `0.14.1` (PR `#53`, `67a3eca`) exported the spec+plan artifacts and state only — no CLI; `0.15.0` (PR `#54`, `51669f7`) carried the method into the operator skills ahead of the CLI; `0.16.0` (PR `#58`, `92c60ca`) implemented all of `t1`–`t14`. The plan reads as a single increment and did not prescribe a version cadence. Every task landed; each CHANGELOG entry scopes its version honestly. `0.14.1` is the plan's own creation (the baseline), not execution. | acceptable | +| `t11` / `t13` (skill-teaching) | The operator-skill method text partly shipped early in `0.15.0` (`/scope` added; think / spec-to-plan / assign-to-workforce SKILL.md updated) **before** the `devague scope` / `--instruction` CLI surface existed — a transient "skills describe a CLI that does not exist yet" state, explicitly flagged in the `0.15.0` CLAUDE.md status. Both tasks were finalized against the shipped CLI in `0.16.0`. | acceptable | +| `t10` (teaching surface) | The task **summary** names `cli/_status.py` as a file that would "know the scope stage," but `cli/_status.py` has **zero** scope references and the status next-move helper was not made scope-aware. The task's binding **acceptance criteria** require only that `learn` present the scope stage and that `explain scope` / `explain question` work — both are met. The `_status.py` mention was descriptive, not contractual; leaving an optional pre-frame leg out of the next-move helper is defensible. | acceptable | + +## Evidence + +Read-only checks run to substantiate the claims below. Every pointer is +resolvable: a commit that exists, a file present in the tree, a merged PR, or a +test node that ran. + +- tests: `uv run pytest -n auto -q` — **418 passed** (2.12s). +- tests (sharper-method subset): `tests/test_cli_scope.py tests/test_cli_instructions.py tests/test_plan_cli_instructions.py tests/test_convergence_sharper.py tests/test_plan_convergence_sharper.py tests/test_render_sharper.py tests/test_plan_render_sharper.py tests/test_frame_schema_v2.py tests/test_plan_store.py tests/test_teaching_scope.py tests/test_e2e_sharper_method.py tests/test_boundary_audit.py` — **135 passed**. +- live CLI: `devague scope --help`, `devague capture --help`, `devague interrogate --help`, `devague plan task --help`, `devague plan --help` (shows the `instruct` verb), `devague explain scope`, `devague explain question` — all present / exit 0. +- enriched waves: `devague plan waves --plan devague-ships-a-sharper-end-to-end-method-a-guided --json` — top-level `tasks` object with per-id `{summary, instruction, acceptance_criteria, covers}` confirmed. +- schema: `devague/frame.py` `SCHEMA_VERSION = 2` (line 15); `devague/plan.py` `PLAN_SCHEMA_VERSION = 2` (line 30). +- commits: `67a3eca` (0.14.1, spec+plan artifacts) · `51669f7` (0.15.0, skills carry) · `92c60ca` (0.16.0, `t1`–`t14` implementation). +- PRs: `#53` (MERGED, merge commit `67a3eca`) · `#54` (MERGED, `51669f7`) · `#58` (MERGED, `92c60ca`). +- CHANGELOG: `0.16.0` attributes all of `t1`–`t14` to the workforce fan-out; `0.15.0` and `0.14.1` scope their partial/preparatory releases honestly. + +## Delivery Claims + +Each claim carries a confidence level and at least one resolvable evidence +pointer. Nothing is asserted as done without evidence. + +| Claim | Confidence | Evidence | +|-------|------------|----------| +| The `devague scope` CLI move ships (surface/finding/`--seeds`/`--list`/`--json`) | high | file `devague/cli/_commands/scope.py` · test `tests/test_cli_scope.py` · live `devague scope --help` | +| Per-item instructions ship on frame moves (`capture`/`interrogate --instruction`) | high | files `devague/cli/_commands/capture.py`, `interrogate.py` · test `tests/test_cli_instructions.py` | +| Per-item instructions ship on plan moves (`plan task --instruction` + `plan instruct `) | high | file `devague/cli/_commands/plan.py` · test `tests/test_plan_cli_instructions.py` · live `devague plan --help` | +| Frame + plan schemas bumped to v2, fail-closed | high | `devague/frame.py:15` · `devague/plan.py:30` · test `tests/test_frame_schema_v2.py`, `tests/test_plan_store.py` | +| Sharper exports render instruction blocks + scope provenance | high | files `devague/render/spec_md.py`, `render/frame_md.py`, `render/plan_md.py` · goldens `tests/goldens/sharper_frame.md`, `sharper_spec.md`, `sharper_plan.md` · test `tests/test_render_sharper.py`, `tests/test_plan_render_sharper.py` | +| Structural sharpness gate lands as warnings-only | high | files `devague/convergence.py`, `plan_convergence.py` · test `tests/test_convergence_sharper.py`, `tests/test_plan_convergence_sharper.py` | +| Enriched `waves --json` carries a per-task subagent-brief payload | high | live `devague plan waves --json` (`tasks` object) · test `tests/test_plan_render_sharper.py` | +| Teaching surface knows the scope stage (`learn`, `explain`) | high | file `devague/cli/_commands/learn.py` · live `devague explain scope` / `devague explain question` (exit 0) · test `tests/test_teaching_scope.py` | +| The status next-move helper was made scope-aware | unverified | `cli/_status.py` has no scope reference — not claimed done (see Drift `t10`; not a binding acceptance criterion) | +| Operator skills + docs teach the shipped surface | high | files `.claude/skills/think/SKILL.md`, `spec-to-plan/SKILL.md`, `assign-to-workforce/SKILL.md`, `docs/spec-contract.md`, `docs/llm-guidance.md`, `docs/skills.md` | +| Dogfooded e2e + boundary audit committed as tests | high | files `tests/test_e2e_sharper_method.py`, `tests/test_boundary_audit.py` (both in the 418-pass run) | +| The full `t1`–`t14` plan shipped (all 14 tasks) | high | commit `92c60ca` · PR `#58` (MERGED) · CHANGELOG `0.16.0` · per-task verification above | + +## Remaining Work / Follow-up + +- Status next-move helper (`cli/_status.py`) scope-awareness — the `t10` summary + named it but the acceptance criteria did not, and it was not implemented. + Decide whether the optional pre-frame scope leg should surface in `devague + status` output; if yes, it is unstarted follow-up. Owner: devague maintainer. +- No blocked, dropped, or partial tasks from this run carry over — all 14 plan + tasks were delivered, so there is no incomplete plan work to re-run. +- Method maturity follow-up (from the plan's own framing, not this run): the + structural sharpness gate ships warnings-only; hardening it into a blocking + gate is a deliberate future step once the soft rollout has bedded in. From 39d102a5f032dd43a622125f4ee376f7706f8a44 Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Thu, 9 Jul 2026 18:55:12 +0300 Subject: [PATCH 07/10] =?UTF-8?q?chore(release):=200.17.0=20=E2=80=94=20su?= =?UTF-8?q?mmarize-delivery,=20the=20delivery-side=20closure=20leg=20[t5]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 33 +++++++++++++++++++++++++++++++++ pyproject.toml | 2 +- uv.lock | 2 +- 3 files changed, 35 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fef905b..cc1a8fd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file. Format follows [Keep a Changelog](https://keepachangelog.com/). This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.17.0] - 2026-07-09 + +Skills-only release. The devague CLI is unchanged — no new verbs, no new CLI +docs. + +### Added + +- **New fifth origin skill `summarize-delivery`** — the delivery-side closure + leg that runs after `/assign-to-workforce`. It turns an execution run into a + committed accountability artifact: planned vs actual delivery, mid-work + decisions, plan drift, evidence-backed delivery claims with confidence + levels, and remaining work. Method-only in v1 — `SKILL.md` plus an + eight-section template; no entry-point script and no new CLI verb. Runs on + complete, partial, and failed runs; never overclaims (a delivery claim + without evidence is marked `unverified`). +- **Registered as the fifth origin skill** in `docs/skill-sources.md` + (alongside `scope` / `think` / `spec-to-plan` / `assign-to-workforce`) — + authored here, re-broadcast by `guildmaster`, never re-vendored back. +- **First dogfood delivery artifact**: + `docs/deliveries/2026-07-09-sharper-end-to-end-method.md` — the first real + delivery summary, produced with the shipped template, covering the #53 + sharper-end-to-end-method run (all 14 plan tasks accounted for, three + classified plan-drift entries, one delivery claim honestly marked + `unverified`). + +### Changed + +- Flow docs now name the five-leg flow — `scope` → `think` → `spec-to-plan` → + `assign-to-workforce` → `summarize-delivery` — in `CLAUDE.md`, `README.md`, + and `docs/skills.md`, plus a new "after the final PR" handoff section in + `.claude/skills/assign-to-workforce/SKILL.md` that points to + `/summarize-delivery`. + ## [0.16.0] - 2026-07-07 ### Added diff --git a/pyproject.toml b/pyproject.toml index 3b963b9..d31d6eb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "devague" -version = "0.16.0" +version = "0.17.0" description = "devague — turns a vague feature idea into a buildable spec, then a buildable plan." readme = "README.md" license = "MIT" diff --git a/uv.lock b/uv.lock index 0b370fe..338dd10 100644 --- a/uv.lock +++ b/uv.lock @@ -183,7 +183,7 @@ wheels = [ [[package]] name = "devague" -version = "0.16.0" +version = "0.17.0" source = { editable = "." } [package.dev-dependencies] From abbeebb6660452c4d23992cc472005f9834c3102 Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Thu, 9 Jul 2026 18:59:04 +0300 Subject: [PATCH 08/10] =?UTF-8?q?docs(deliveries):=20self-application=20?= =?UTF-8?q?=E2=80=94=20summarize-delivery=20reports=20its=20own=20run?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The skill's second use and first self-application: the run that shipped summarize-delivery, reported by summarize-delivery. 5/5 plan tasks accounted for; 5 classified drift entries (2 model reassignments after colleague's silent failures, 1 scope-limit overrun, this unplanned artifact, and the branch-namespace deviation); 3 claims held at unverified/low rather than asserted. Unplanned deliverable — recorded as drift (acceptable) in the artifact. Co-Authored-By: Claude Fable 5 --- .devague/current_plan | 2 +- .../2026-07-09-summarize-delivery-skill.md | 186 ++++++++++++++++++ 2 files changed, 187 insertions(+), 1 deletion(-) create mode 100644 docs/deliveries/2026-07-09-summarize-delivery-skill.md diff --git a/.devague/current_plan b/.devague/current_plan index 0c0cfea..5387c7c 100644 --- a/.devague/current_plan +++ b/.devague/current_plan @@ -1 +1 @@ -devague-ships-a-sharper-end-to-end-method-a-guided +summarize-delivery-skill diff --git a/docs/deliveries/2026-07-09-summarize-delivery-skill.md b/docs/deliveries/2026-07-09-summarize-delivery-skill.md new file mode 100644 index 0000000..07842f9 --- /dev/null +++ b/docs/deliveries/2026-07-09-summarize-delivery-skill.md @@ -0,0 +1,186 @@ +# Delivery Summary — summarize-delivery skill + +plan: `summarize-delivery-skill` · run: `complete` · date: `2026-07-09` +baseline: `devague plan (summarize-delivery-skill)` + +## Intent + +This run set out to close the devague method's open end. The flow ran +`scope` → `think` → `spec-to-plan` → `assign-to-workforce` and then stopped: +nothing recorded what execution actually produced. Agents make mid-work +decisions, hit constraints, cut scope, and assert delivery claims that were +never in the plan, and none of it was captured. The run delivers the fifth +origin skill, **`summarize-delivery`** — the delivery-side closure leg that +turns an execution run into a committed accountability artifact — by executing +the converged plan `summarize-delivery-skill`: 5 tasks over 3 waves, fanned out +by `/assign-to-workforce` to a **mixed-backend workforce** and merged behind a +TDD gate. + +This summary is the skill's second use and its first **self-application**: the +run that shipped `summarize-delivery` is reported by `summarize-delivery`. + +## Planned Work + +Quoted verbatim from `devague plan waves --json` (task id and summary, keyed by +id). The plan's waves are `[t1, t2, t3]` · `[t4]` · `[t5]`. + +- `t1` — author .claude/skills/summarize-delivery/SKILL.md - the method-only + skill with the eight-section delivery-summary template and the + no-overclaiming hard rules +- `t2` — register summarize-delivery as the fifth origin skill in + docs/skill-sources.md +- `t3` — update the flow docs: five-leg flow in CLAUDE.md, the + assign-to-workforce handoff, and the README and docs/skills.md family mentions +- `t4` — dogfood: produce the first real delivery summary at docs/deliveries/ + for the sharper-end-to-end-method run (issue 53, PRs 53, 54, 58) +- `t5` — release hygiene: minor version bump with changelog, full test suite, + and repo-wide markdown lint + +## Actual Delivery + +Every one of the 5 plan tasks is accounted for. Status breakdown: +**5 delivered, 0 partial, 0 dropped, 0 blocked.** Each merged behind the +`/assign-to-workforce` TDD gate (tests and tracked-markdown lint green before +*and* after every merge). + +| Plan task | Status | What actually landed | +|-----------|--------|----------------------| +| `t1` | delivered | `.claude/skills/summarize-delivery/SKILL.md` (379 lines): eight-section template, delivery-claim row contract, drift entry contract, hard rules, a partial-run worked example. Executed by **opus**. | +| `t2` | delivered | `docs/skill-sources.md` gains the fifth origin-skill row plus both prose enumerations and the vendoring-policy bullet. Executed by **colleague** (vLLM Qwen3.6-27B). | +| `t3` | delivered | Five-leg flow named in `CLAUDE.md`, `README.md`, `docs/skills.md`; new "after the final PR" handoff section in `.claude/skills/assign-to-workforce/SKILL.md`. Executed by **opus** after colleague failed twice — see Drift. | +| `t4` | delivered | `docs/deliveries/2026-07-09-sharper-end-to-end-method.md` — the first real delivery summary, covering the `#53` run: 14/14 tasks accounted for, 3 classified drift entries, 1 claim honestly marked `unverified`. Executed by **opus**. | +| `t5` | delivered | Version `0.16.0` → `0.17.0`, `CHANGELOG.md` `## [0.17.0]` entry, `uv.lock` self-pin. Executed by **opus** after colleague failed twice — see Drift. | + +## Mid-work Decisions + +Constraints discovered and choices made during execution that the plan did not +prescribe. + +- **The workforce was made mixed-backend mid-gate.** The approved split plan + assigned `t2`/`t3`/`t5` to a cheaper Claude model; the user amended it to the + `colleague` CLI (a different backend — local vLLM Qwen3.6-27B) for the value + of a genuinely independent mind. Accepted and applied. +- **`colleague work` exits `0` whether it succeeds or does nothing.** On failure + it writes `status: incomplete`, `steps: 0`, `changed files: (none)` — and + still returns exit code `0`. Its own prose summary is likewise not evidence. + Detected only by parsing the `status:` line and reading the diff. The + operator's TDD merge gate is what caught it. +- **Escalation policy adopted after repeated silent failure.** Two failures on a + task were treated as sufficient evidence to reassign it to a stronger model + rather than stall the wave. Applied to `t3` and `t5`. +- **A brief-length hypothesis was formed and then falsified.** `t2` (short + brief) succeeded and `t3` (longer) failed, suggesting brief size was the + cause. A deliberately trimmed `t5` brief then failed identically, so the + hypothesis was wrong: the failure is nondeterministic tool-call formatting + (the model emits `` `list_dir(...)` `` or + `` `{...}` `` as literal prose at step 0). Recorded because the + first explanation was stated before it was tested. +- **The installed `devague` had to be upgraded before the run could start.** + `assign-to-workforce`'s wrapper resolves an installed `devague` on `PATH` + ahead of the checkout's `uv run devague`; the installed binary was `0.14.1` + and refused the schema-v2 plan (`uses schema_version 2, but this devague + supports up to 1`). Resolved with `uv tool install -U devague` → `0.17.0` + published on PyPI. +- **Branch namespace changed to avoid clobbering unmerged work.** The + `/assign-to-workforce` worked example prescribes `agent/`, but task + ids restart at `t1` for every plan, and unmerged `agent/t1`–`agent/t5` from + the `#53` run already existed. This run used `agent/sd-`. No + pre-existing branch was reused or deleted. +- **"Repo-wide markdown lint" was scoped to tracked files.** The operator's + local tree carries gitignored `.devague/reviews/` artifacts with a + pre-existing `MD026` violation. `t5` then established that a clean worktree + has no such directory, so the raw `markdownlint-cli2 "**/*.md"` passes there + too — the caveat was about the operator's working tree, not the repo. + +## Drift From Plan + +Exhaustive relative to the plan. Tasks `t1`, `t2`, and `t4` landed exactly per +their acceptance criteria and are not drift entries. The entries below are the +only divergences; all are classified `acceptable` except where noted. + +| Plan item | Reason for divergence | Classification | +|-----------|-----------------------|----------------| +| `t3` (execution) | The approved split plan assigned this task to `colleague`. It failed twice — `status: incomplete`, `steps: 0`, zero files changed, exit `0` both times (flight ids `e8251d046733`, `fdac321b7780`). Reassigned to **opus** by the operator without returning to the human. The task's contract, acceptance criteria, and brief were unchanged; only the executing model differs. | acceptable | +| `t5` (execution) | Same failure mode, twice (flight ids `8171f73f3a2e`, `2b43baffea88`), including once with a deliberately shortened brief. Reassigned to **opus**. Contract unchanged. | acceptable | +| `t5` (scope limit) | The task brief limited edits to `pyproject.toml` / `CHANGELOG.md` / `devague/__init__.py`. The executing agent also committed `uv.lock` — a single-line devague self-version pin (`0.16.0` → `0.17.0`) regenerated by `uv`. Committing it is correct release hygiene; leaving it stale would re-dirty the tree on the next `uv sync`. The agent flagged it rather than hiding it. | acceptable | +| whole plan (deliverables) | This artifact — `docs/deliveries/2026-07-09-summarize-delivery-skill.md` — was **not** a plan task. The plan's only delivery-summary task was `t4` (the `#53` run). The operator added a self-application of the skill as a sixth, unplanned deliverable. It is additive, changes no confirmed task, and is the strongest available evidence that the skill works. | acceptable | +| run procedure (branch names) | The `/assign-to-workforce` worked example prescribes `agent/`; this run used `agent/sd-` because plan-local task ids collide in the repo-global branch namespace. The skill's own example would have failed here. The deviation was forced, and the skill's worked example is now known-wrong. | needs-follow-up | + +## Evidence + +Read-only checks run to substantiate the claims below. Every pointer is +resolvable: a commit that exists, a file present in the tree, or a test run +that happened. + +- tests: `uv run pytest -n auto -q` — **418 passed**, run before and after each + of the five merges (the TDD gate). +- lint: `git ls-files '*.md' | grep -v '^docs/superpowers/' | grep -v + '^.claude/skills/' | xargs markdownlint-cli2` — **23 files, 0 errors**. +- task commits: `a5ea5e0` (`t1`) · `ae22bbd` (`t2`) · `91dfc99` (`t3`) · + `e69bcea` (`t4`) · `39d102a` (`t5`). +- merge commits: `dc03e63` (`t1`) · `ea395d6` (`t2`) · `b138a48` (`t3`) · + `63665fe` (`t4`) · `b259ba6` (`t5`). +- provenance commits: `c41800b` (converged spec, `/think`) · `9166f73` + (converged plan, `/spec-to-plan`). +- colleague failure artifacts: branches `colleague/e8251d046733-*`, + `colleague/fdac321b7780-*` (`t3`), `colleague/8171f73f3a2e-*`, + `colleague/2b43baffea88-*` (`t5`) — each with `status: incomplete`, zero + changed files. Success artifact: `colleague/d2d145ec48bd-*` (`t2`), + `status: ok`, 5 `edit_file` steps. +- version: `pyproject.toml` `version = "0.17.0"` (`main` is `0.16.0`). +- frame provenance: `devague scope --list` records 5 scope entries (`s1`–`s5`), + each citing the surface explored and the claim ids it seeded. +- gate arithmetic: the plan's 30 coverage targets (`c*`/`h*`) are each covered + by a confirmed task; `devague plan converge` reported `converged ✓`. + +## Delivery Claims + +Each claim carries a confidence level and at least one resolvable evidence +pointer. Nothing is asserted as done without evidence. + +| Claim | Confidence | Evidence | +|-------|------------|----------| +| The `summarize-delivery` skill ships, method-only (no script, no CLI verb) | high | file `.claude/skills/summarize-delivery/SKILL.md` · commit `a5ea5e0` · the directory contains no `scripts/` | +| Its template carries all eight sections in order, and a partial-run worked example | high | file `.claude/skills/summarize-delivery/SKILL.md` (template block lines 123–197, `## Intent` → `## Remaining Work / Follow-up`; partial-run worked example lines 305–356) | +| Delivery-claim rows require confidence + resolvable evidence; drift entries require exactly one classification | high | `SKILL.md` "the row contract" / "the entry contract" sections | +| It is registered as the fifth origin skill | high | file `docs/skill-sources.md` · commit `ae22bbd` | +| The five-leg flow is named across the flow docs, with a workforce handoff | high | files `CLAUDE.md`, `README.md`, `docs/skills.md`, `.claude/skills/assign-to-workforce/SKILL.md` · commit `91dfc99` | +| The first dogfood artifact accounts for 100 % of the `#53` plan's 14 tasks and marks one claim `unverified` | high | file `docs/deliveries/2026-07-09-sharper-end-to-end-method.md` · commit `e69bcea` · independently re-verified: `grep -ci scope devague/cli/_status.py` → `0` | +| The `#53` artifact's evidence pointers resolve | high | operator re-check: all cited files/tests exist; `frame.py:15` and `plan.py:30` read `SCHEMA_VERSION = 2`; PRs `#53`/`#54`/`#58` MERGED with merge commits `67a3eca`/`51669f7`/`92c60ca`; sharper-method subset = exactly **135 passed** | +| Release `0.17.0` with a Keep-a-Changelog entry naming all four deliverables | high | `pyproject.toml` · `CHANGELOG.md` `## [0.17.0]` · commit `39d102a` | +| The devague CLI is unchanged by this release | high | commits `a5ea5e0`..`39d102a` touch no file under `devague/` | +| The full suite passes and tracked markdown lints clean | high | `uv run pytest -n auto` → 418 passed · markdownlint → 23 files, 0 errors | +| Producing *this* summary left `.devague/` unmutated | high | only read-only moves used (`plan waves --json`, `scope --list`); the sole `.devague/` change on this branch is `current_plan`, written earlier by `devague plan new` during the `/spec-to-plan` leg | +| `colleague work` returns exit `0` on silent failure | high | 4 of 5 attempts: `status: incomplete`, `steps: 0`, `changed files: (none)`, exit `0` — flight ids above | +| The final PR gate (human gate 3) has passed | unverified | the PR is not yet opened at the time of writing — not claimed | +| guildmaster will re-broadcast `summarize-delivery` to the AgentCulture mesh | unverified | outside this repo; no observation available here | +| The skill produces good summaries for runs it did not itself execute | low | one instance only (`t4`, the `#53` run) — a single successful application is weak evidence of generality | + +## Remaining Work / Follow-up + +- **Open the final PR (human gate 3).** The last remaining gate; the human + reviews and merges. This artifact is the review map. Owner: operator, then + the human. +- **Fix `/assign-to-workforce`'s worked example — branch namespace.** It + prescribes `agent/`, which collides across plans because task ids + restart at `t1`. Recommend namespacing per plan (`agent/-`) + and checking `git merge-base --is-ancestor` before reusing any branch. This + run hit the collision immediately. Owner: devague maintainer. +- **Reap or merge the stale `agent/t1`–`agent/t5` branches** left unmerged by + the `#53` run. They were deliberately not touched here. Owner: devague + maintainer. +- **Report `colleague work`'s exit-code behavior upstream.** Exiting `0` on + `status: incomplete` makes silent failure indistinguishable from success to + any caller that checks `$?`. Owner: colleague maintainer. +- **Delivery engine remains parked** (frame vagueness `v1`, kind `follow_up`): + a third structural peer with a delivery store, per-task accounting, and a + deterministic no-overclaim gate. Deferred until dogfooding the method-only + skill shows machine state is needed. One self-application is not yet that + evidence. +- **Inherited from the `#53` run, unresolved:** whether + `devague status` should surface the optional pre-frame scope leg + (`cli/_status.py` has no scope reference). Recorded in + `docs/deliveries/2026-07-09-sharper-end-to-end-method.md`; still a decision + the maintainer owes. Owner: devague maintainer. +- **No blocked, dropped, or partial tasks** carry over from this run — all 5 + plan tasks were delivered, so there is no incomplete plan work to re-run. From 833ab781b3c6ad889fe03c20a597c0edfe0563a5 Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Thu, 9 Jul 2026 19:15:43 +0300 Subject: [PATCH 09/10] fix(store): stamp current schema_version on save (upgrade-on-write) Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_013gVnMHmeZiw2EcjSnJDGZq --- .devague/frames/summarize-delivery-skill.json | 2 +- devague/plan_store.py | 5 +++++ devague/store.py | 5 +++++ tests/test_plan_store.py | 14 ++++++++++++++ tests/test_store.py | 14 ++++++++++++++ 5 files changed, 39 insertions(+), 1 deletion(-) diff --git a/.devague/frames/summarize-delivery-skill.json b/.devague/frames/summarize-delivery-skill.json index 1a62519..ab20a10 100644 --- a/.devague/frames/summarize-delivery-skill.json +++ b/.devague/frames/summarize-delivery-skill.json @@ -1,7 +1,7 @@ { "slug": "summarize-delivery-skill", "title": "summarize-delivery skill", - "schema_version": 1, + "schema_version": 2, "status": "exported", "created": "2026-07-09T15:12:14Z", "updated": "2026-07-09T15:17:54Z", diff --git a/devague/plan_store.py b/devague/plan_store.py index 1e2894e..2f6a7a3 100644 --- a/devague/plan_store.py +++ b/devague/plan_store.py @@ -33,6 +33,11 @@ def path_for(slug: str) -> Path: def save(plan: Plan) -> Path: PLANS_DIR.mkdir(parents=True, exist_ok=True) + # Stamp the version this binary actually writes: a plan loaded under an older + # label then mutated with newer fields must not be rewritten under that older + # label, or the fail-closed load gate (schema_version > PLAN_SCHEMA_VERSION) + # is defeated and an old binary silently drops the newer payload (data loss). + plan.schema_version = PLAN_SCHEMA_VERSION plan.updated = _now() if not plan.created: plan.created = plan.updated diff --git a/devague/store.py b/devague/store.py index 29a382b..936b39b 100644 --- a/devague/store.py +++ b/devague/store.py @@ -115,6 +115,11 @@ def unique_slug(base: str) -> str: def save(frame: Frame) -> Path: FRAMES_DIR.mkdir(parents=True, exist_ok=True) + # Stamp the version this binary actually writes: a frame loaded under an older + # label then mutated with newer fields must not be rewritten under that older + # label, or the fail-closed load gate (schema_version > SCHEMA_VERSION) is + # defeated and an old binary silently drops the newer payload (data loss). + frame.schema_version = SCHEMA_VERSION frame.updated = _now() if not frame.created: frame.created = frame.updated diff --git a/tests/test_plan_store.py b/tests/test_plan_store.py index fcae769..033a9ca 100644 --- a/tests/test_plan_store.py +++ b/tests/test_plan_store.py @@ -136,3 +136,17 @@ def test_load_rejects_slug_mismatch(tmp_path, monkeypatch) -> None: p.write_text(json.dumps(raw), encoding="utf-8") with pytest.raises(ValueError, match="slug mismatch"): plan_store.load("demo") + + +def test_save_upgrades_stale_schema_version_on_write(tmp_path, monkeypatch) -> None: + # A plan loaded under an older label then mutated must be rewritten under the + # version this binary writes, or the fail-closed load gate is defeated and an + # old binary silently drops the newer payload (data loss). save() stamps the + # current PLAN_SCHEMA_VERSION rather than re-emitting the loaded one. + monkeypatch.chdir(tmp_path) + p = _plan() + p.schema_version = 1 + plan_store.save(p) + assert plan_store.load("demo").schema_version == PLAN_SCHEMA_VERSION + raw = json.loads(plan_store.path_for("demo").read_text(encoding="utf-8")) + assert raw["schema_version"] == 2 diff --git a/tests/test_store.py b/tests/test_store.py index fc25225..a229ae4 100644 --- a/tests/test_store.py +++ b/tests/test_store.py @@ -119,3 +119,17 @@ def test_load_rejects_slug_mismatch(tmp_path, monkeypatch) -> None: p.write_text(json.dumps(raw), encoding="utf-8") with pytest.raises(ValueError, match="slug mismatch"): store.load("demo") + + +def test_save_upgrades_stale_schema_version_on_write(tmp_path, monkeypatch) -> None: + # A frame loaded under an older label then mutated must be rewritten under the + # version this binary writes, or the fail-closed load gate is defeated and an + # old binary silently drops the newer payload (data loss). save() stamps the + # current SCHEMA_VERSION rather than re-emitting the loaded one. + monkeypatch.chdir(tmp_path) + f = Frame(slug="demo", title="Demo") + f.schema_version = 1 + store.save(f) + assert store.load("demo").schema_version == SCHEMA_VERSION + raw = json.loads(store.path_for("demo").read_text(encoding="utf-8")) + assert raw["schema_version"] == 2 From a55df5a1a130f1e4ccae72d243be1467c4fa9766 Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Thu, 9 Jul 2026 19:17:42 +0300 Subject: [PATCH 10/10] docs: record the schema-fix drift; correct the skills-only claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Qodo (PR #63) surfaced a real data-loss bug in store.py/plan_store.py. Fixing it makes 0.17.0 "skills + one correctness fix", not skills-only — CHANGELOG gains a Fixed section, and the delivery summary gains the release-scope drift entry, the corrected claims (420 tests; CLI gains no verb but does change), and the retraction of the operator's wrong "Qodo found no bugs" reading. Addresses review comment 3553078018. Co-Authored-By: Claude Fable 5 --- CHANGELOG.md | 17 ++++++++- .../2026-07-09-summarize-delivery-skill.md | 37 +++++++++++++++++-- 2 files changed, 48 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cc1a8fd..142eca3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,8 +7,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [0.17.0] - 2026-07-09 -Skills-only release. The devague CLI is unchanged — no new verbs, no new CLI -docs. +Skills release plus one correctness fix. No new CLI verbs and no new CLI docs; +the only code change is a data-loss fix in the frame/plan stores (see *Fixed*). ### Added @@ -38,6 +38,19 @@ docs. `.claude/skills/assign-to-workforce/SKILL.md` that points to `/summarize-delivery`. +### Fixed + +- **`save()` now stamps the current `schema_version` (upgrade-on-write)** — + `devague/store.py` and `devague/plan_store.py` re-emitted the + `schema_version` loaded from disk instead of the one the running binary + writes. A frame created under schema v1 and later mutated by a v2 binary was + saved still labelled v1 while carrying v2-only payload (`scope_entries`, + per-item `instruction`). An older binary then passed the fail-closed load gate + (`schema_version > SCHEMA_VERSION`), loaded the file, silently dropped the + unknown fields, and rewrote it — data loss. Both stores now stamp the current + version on write, so an older binary correctly *refuses* the file instead. + Found by Qodo on PR #63; regression tests added for both stores. + ## [0.16.0] - 2026-07-07 ### Added diff --git a/docs/deliveries/2026-07-09-summarize-delivery-skill.md b/docs/deliveries/2026-07-09-summarize-delivery-skill.md index 07842f9..16bd920 100644 --- a/docs/deliveries/2026-07-09-summarize-delivery-skill.md +++ b/docs/deliveries/2026-07-09-summarize-delivery-skill.md @@ -91,6 +91,21 @@ prescribe. pre-existing `MD026` violation. `t5` then established that a clean worktree has no such directory, so the raw `markdownlint-cli2 "**/*.md"` passes there too — the caveat was about the operator's working tree, not the repo. +- **PR review re-opened the CLI.** The plan converged on a skills-only release. + Qodo's review of PR `#63` surfaced a real data-loss bug — this run's *own* + frame had been committed as `schema_version: 1` while carrying v2 payload, + because `think.sh` had resolved the stale installed `devague` 0.14.1 at + `devague new` time and `save()` re-emitted the loaded version thereafter. The + operator chose to fix the stores rather than only relabel the artifact: + relabeling would have left the defect armed for the next frame edited across + a version boundary. Release scope grew; `CHANGELOG.md`, the PR body, and this + artifact were corrected to say so. +- **The operator misread its own review tooling, twice.** A hand-rolled regex + over Qodo's comment scraped only `` tags and reported "no bug + findings"; both findings sit in the collapsed `
` bodies — the exact + failure mode already recorded in the operator's notes. `agex pr read` + surfaced them on the first call. The earlier "no bugs" statement was wrong + and is retracted here rather than quietly dropped. ## Drift From Plan @@ -105,6 +120,7 @@ only divergences; all are classified `acceptable` except where noted. | `t5` (scope limit) | The task brief limited edits to `pyproject.toml` / `CHANGELOG.md` / `devague/__init__.py`. The executing agent also committed `uv.lock` — a single-line devague self-version pin (`0.16.0` → `0.17.0`) regenerated by `uv`. Committing it is correct release hygiene; leaving it stale would re-dirty the tree on the next `uv sync`. The agent flagged it rather than hiding it. | acceptable | | whole plan (deliverables) | This artifact — `docs/deliveries/2026-07-09-summarize-delivery-skill.md` — was **not** a plan task. The plan's only delivery-summary task was `t4` (the `#53` run). The operator added a self-application of the skill as a sixth, unplanned deliverable. It is additive, changes no confirmed task, and is the strongest available evidence that the skill works. | acceptable | | run procedure (branch names) | The `/assign-to-workforce` worked example prescribes `agent/`; this run used `agent/sd-` because plan-local task ids collide in the repo-global branch namespace. The skill's own example would have failed here. The deviation was forced, and the skill's worked example is now known-wrong. | needs-follow-up | +| whole plan (release scope) | The plan and its `t5` acceptance criteria assumed a **skills-only** release with the CLI unchanged. PR review (Qodo, `#63`) surfaced a real data-loss bug in `devague/store.py` and `devague/plan_store.py`: `save()` re-emitted the `schema_version` loaded from disk rather than the one the running binary writes, so this run's own frame was committed as v1 while carrying v2 payload. Fixed in-branch (upgrade-on-write + 2 regression tests, `833ab78`), which makes the release **skills + one correctness fix**. `CHANGELOG.md` and the PR body were corrected to say so. Scope grew after convergence; the alternative — shipping a known data-loss bug — was worse. | acceptable | ## Evidence @@ -148,11 +164,13 @@ pointer. Nothing is asserted as done without evidence. | The first dogfood artifact accounts for 100 % of the `#53` plan's 14 tasks and marks one claim `unverified` | high | file `docs/deliveries/2026-07-09-sharper-end-to-end-method.md` · commit `e69bcea` · independently re-verified: `grep -ci scope devague/cli/_status.py` → `0` | | The `#53` artifact's evidence pointers resolve | high | operator re-check: all cited files/tests exist; `frame.py:15` and `plan.py:30` read `SCHEMA_VERSION = 2`; PRs `#53`/`#54`/`#58` MERGED with merge commits `67a3eca`/`51669f7`/`92c60ca`; sharper-method subset = exactly **135 passed** | | Release `0.17.0` with a Keep-a-Changelog entry naming all four deliverables | high | `pyproject.toml` · `CHANGELOG.md` `## [0.17.0]` · commit `39d102a` | -| The devague CLI is unchanged by this release | high | commits `a5ea5e0`..`39d102a` touch no file under `devague/` | -| The full suite passes and tracked markdown lints clean | high | `uv run pytest -n auto` → 418 passed · markdownlint → 23 files, 0 errors | +| The devague CLI gains no new verbs; its only code change is the schema-stamp fix | high | commits `a5ea5e0`..`39d102a` touch no file under `devague/`; `833ab78` touches only `store.py` / `plan_store.py` (no verb added) | +| The full suite passes and tracked markdown lints clean | high | `uv run pytest -n auto` → **420 passed** (418 + 2 regression tests) · markdownlint → 0 errors · `flake8` / `isort` clean | | Producing *this* summary left `.devague/` unmutated | high | only read-only moves used (`plan waves --json`, `scope --list`); the sole `.devague/` change on this branch is `current_plan`, written earlier by `devague plan new` during the `/spec-to-plan` leg | -| `colleague work` returns exit `0` on silent failure | high | 4 of 5 attempts: `status: incomplete`, `steps: 0`, `changed files: (none)`, exit `0` — flight ids above | -| The final PR gate (human gate 3) has passed | unverified | the PR is not yet opened at the time of writing — not claimed | +| `colleague work` returns exit `0` on silent failure | high | **6 of 7 attempts** (incl. 2 on the post-review schema fix): `status: incomplete`, `steps: 0`, `changed files: (none)`, exit `0` | +| A real data-loss bug (stale `schema_version` on save) is fixed, with tests that fail without the fix | high | commit `833ab78` · `tests/test_store.py::test_save_upgrades_stale_schema_version_on_write` and the `test_plan_store.py` peer — both verified to FAIL against the pre-fix source, then pass | +| Qodo finding 2 ("LLM tasks stored as confirmed") is a false positive | high | `devague/plan.py:109` — `status = "proposed" if origin == "llm" else "confirmed"`; the tasks were confirmed by the user at the review gate, and `confirm` leaves `origin` as immutable provenance | +| The final PR gate (human gate 3) has passed | unverified | PR `#63` is open and awaiting human review — not claimed | | guildmaster will re-broadcast `summarize-delivery` to the AgentCulture mesh | unverified | outside this repo; no observation available here | | The skill produces good summaries for runs it did not itself execute | low | one instance only (`t4`, the `#53` run) — a single successful application is weak evidence of generality | @@ -182,5 +200,16 @@ pointer. Nothing is asserted as done without evidence. (`cli/_status.py` has no scope reference). Recorded in `docs/deliveries/2026-07-09-sharper-end-to-end-method.md`; still a decision the maintainer owes. Owner: devague maintainer. +- **Confirmation provenance is not persisted.** Qodo's finding 2 was a false + positive, but it gestures at something real: the stored state records a + task's `origin` and its terminal `status`, not *who* confirmed it or *when*. + A static reader cannot distinguish a user-confirmed item from an + auto-confirmed one; only the CLI's behavior guarantees the gate. Consider + recording confirmation provenance. Owner: devague maintainer. +- **The `think.sh` wrapper resolves a stale `PATH` binary ahead of the + checkout**, which is how this run's frame was stamped v1 in the first place. + The schema fix stops the silent data loss, but the wrapper still prefers an + installed `devague` over the local `uv run devague`. Owner: devague + maintainer. - **No blocked, dropped, or partial tasks** carry over from this run — all 5 plan tasks were delivered, so there is no incomplete plan work to re-run.