feat: the sharper end-to-end method — scope move, instructions, sharper exports, guided fanout (0.16.0, #53 t1-t14)

[OriNachum]

What

The sharper end-to-end method ships (0.16.0) — the full #53 build plan
(t1–t14), executed as a devague-orchestrated workforce fan-out: 5 dependency
waves from devague plan waves, one agent per task in an isolated worktree,
every merge TDD-gated (full suite green before and after), no human in the
per-task loop per the approved implementation split plan.

• devague scope — records explored surfaces as first-class ScopeEntry
  state (surface, finding, --seeds claim links; unknown ids refused);
  scope --list [--json] reads them back. (t1, t3)
• Per-item instructions — verbatim instruction text on claims, honesty
  conditions, and plan tasks (capture --instruction,
  interrogate <c*|h*> --instruction, plan task --instruction,
  new plan instruct <tN>); changing one on a confirmed item flips it back to
  proposed for re-confirmation. (t2, t4, t5)
• Sharper exports — instruction blocks + scope-provenance sections in
  spec/frame/plan markdown, golden-file tested; absent instructions render
  nothing. (t6, t9)
• Enriched waves --json — top-level tasks object
  (summary/instruction/acceptance_criteria/covers per id): a
  self-contained subagent brief; existing keys unchanged. The
  assign-to-workforce skill + split-plan script now brief verbatim from it —
  the operator-paraphrase step is gone. (t9, t13)
• Structural sharpness warnings (soft rollout, warnings-only, documented
  deterministic predicates): instruction-less spec-affecting claims,
  non-measurable success signals, instruction-less confirmed tasks. (t7, t8)
• Teaching: learn presents the optional scope stage; explain scope /
  explain question fixed; /think, /spec-to-plan, /scope SKILL.md teach the
  shipped surface (verified live by the doc agent). (t10, t11, t12)
• Dogfooded e2e + boundary audit as committed tests — a real idea (no unpark/resolve move: a parked unknown_blocking blocks convergence forever #57's
  unpark move) runs scope → frame → sharper spec → plan → fanout brief on the
  shipped surface; the audit pins no LLM imports / no process spawning in the
  package (Expose plan dependency waves as deterministic metadata, not orchestration #20). (t14)

Both schemas bump 1 → 2, fail-closed, with empty-default hydration of v1
files.

Evidence

• Tests: 290 (baseline) → 418 passed; every wave merge gated both sides.
• bandit -r devague/: no issues identified. flake8/black/isort: clean.
• markdownlint-cli2 clean on CHANGELOG + the three updated docs.
• Enriched-payload contract verified live against the documented shape.

Notes

• Merge order: independent of spec+plan: multi-repo efforts — hub-repo state, repo-tagged tasks, per-repo PRs (0.15.1) #56 (multi-repo spec+plan, 0.15.1); whichever
  merges second keeps the version monotonic (0.15.1 < 0.16.0).

• This unblocks the multi-repo plan's r1 precondition (spec+plan: multi-repo efforts — hub-repo state, repo-tagged tasks, per-repo PRs (0.15.1) #56): its t1/t3 ride
  the instruction fields + enriched waves payload shipped here.

• devague (Claude)

[OriNachum]

/agentic_review

[qodo-code-review]

Code Review by Qodo

New Review Started

This review has been superseded by a new analysis

[qodo-code-review]

Qodo is busy working

Check back in a few minutes. Qodo's code review agents are on it.

[qodo-code-review]

PR Summary by Qodo

Ship sharper end-to-end method: scope entries, per-item instructions, enriched waves

✨ Enhancement 🧪 Tests 📝 Documentation ⚙️ Configuration changes 🕐 40+ Minutes

AI Description

• Add first-class scope findings and verbatim per-item instructions across frame and plan.
• Render instructions + scope provenance in exports; enrich plan waves --json for fanout briefs.
• Introduce warning-only sharpness checks; expand teaching/docs; add full e2e + boundary audits.

Diagram

graph TD
  CLI["CLI moves"] --> FRAME[("Frame JSON")]
  CLI --> PLAN[("Plan JSON")]
  FRAME --> RENDER["Markdown renderers"] --> DOCS["docs/specs & docs/plans"]
  PLAN --> WAVES["plan waves --json"] --> ATW["assign-to-workforce.sh"]
  CLI --> TEACH["learn/skills docs"]
  TESTS["Test suite"] --> CLI
  TESTS --> RENDER
  TESTS --> WAVES

  subgraph Legend
    direction LR
    _cli["Command/Module"] ~~~ _db[("Persisted state")] ~~~ _doc["Artifact/Doc"]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep instructions external (sidecar file per frame/plan)

• ➕ Avoids schema bump and migrations
• ➕ Keeps persisted model smaller and more stable
• ➖ Breaks end-to-end provenance and export fidelity
• ➖ Harder to keep confirm/re-confirm semantics consistent
• ➖ More moving parts for tooling (review, renderers, workforce brief)

2. Separate scope into its own persisted object (not on Frame)

• ➕ Clear conceptual separation between exploration and framing
• ➕ Could be reused across multiple frames
• ➖ Adds cross-file references and lifecycle complexity
• ➖ Makes export provenance harder (need joins) and less portable
• ➖ More surface area for fail-closed schema/version handling

3. Add a new dedicated brief command instead of enriching `waves --json`

• ➕ Leaves existing waves payload unchanged
• ➕ Can tailor output strictly for workforce tooling
• ➖ Duplicates logic and increases CLI surface area
• ➖ More commands to document/test and more drift risk
• ➖ Still needs to fetch task details somewhere (likely the same fields)

Recommendation: The PR’s approach is the best fit for the stated method goals: embed scope + instruction in the core persisted state (fail-closed schemas), render them verbatim in exports, and enrich waves --json so downstream fanout tooling can brief without paraphrase. The main alternatives (sidecars, separate scope objects, or new brief commands) either weaken provenance, increase lifecycle complexity, or introduce redundant surfaces that are harder to keep consistent.

Files changed (43) +3126 / -154

Enhancement (15) +537 / -55

__init__.pyRegister new 'scope' CLI command +2/-0

Register new 'scope' CLI command

• Adds the scope command module import and registers it with the top-level CLI parser so 'devague scope' becomes available.

devague/cli/init.py

capture.pySupport 'capture --instruction' for new claims +10/-0

Support 'capture --instruction' for new claims

• Adds an optional '--instruction' flag that stores verbatim instruction text on the newly created claim. Extends JSON output to include the instruction field.

devague/cli/_commands/capture.py

interrogate.pyAdd 'interrogate --instruction' for claims and honesty conditions +54/-7

Add 'interrogate --instruction' for claims and honesty conditions

• Allows '--instruction' updates on a claim ('c*') or, when instruction-only, directly on an honesty condition ('h*'). Implements the re-confirm rule by demoting confirmed items back to proposed and emitting a diagnostic note; strengthens validation and JSON output consistency.

devague/cli/_commands/interrogate.py

plan.pyAdd task instructions, 'plan instruct', and enrich 'waves --json' +65/-3

Add task instructions, 'plan instruct', and enrich 'waves --json'

• Supports 'plan task --instruction' and introduces 'plan instruct <tN> <text>' with re-confirm demotion for confirmed tasks and diagnostics. Extends 'plan waves --json' to include a top-level per-task brief map ('summary', 'instruction', 'acceptance_criteria', 'covers') without changing existing keys.

devague/cli/_commands/plan.py

review.pyInclude instruction text in review JSON payloads +9/-2

Include instruction text in review JSON payloads

• Extends 'devague review --json' to include each proposed claim/honesty condition’s instruction field so human review sees verbatim working guidance alongside text.

devague/cli/_commands/review.py

scope.pyIntroduce 'devague scope' to record/list scope findings +94/-0

Introduce 'devague scope' to record/list scope findings

• Adds a deterministic scope verb to record explored surfaces and findings into 'Frame.scope_entries', with optional '--seeds' claim-id links and refusal of unknown ids. Supports listing in text or structured JSON.

devague/cli/_commands/scope.py

convergence.pyAdd warning-only structural sharpness signals (S1/S2) +65/-2

Add warning-only structural sharpness signals (S1/S2)

• Introduces deterministic, non-blocking sharpness warnings: missing instruction on confirmed spec-affecting claims, and non-measurable confirmed success signals via regex token checks. Documents predicates and known false-positive modes in the module docstring.

devague/convergence.py

frame.pyFrame schema v2: scope entries + per-claim/honesty instructions +62/-2

Frame schema v2: scope entries + per-claim/honesty instructions

• Bumps frame 'SCHEMA_VERSION' to 2, adds 'ScopeEntry' and 'Frame.scope_entries', and adds optional 'instruction' to 'Claim' and 'HonestyCondition' with empty-default hydration for v1. Adds validation that seeded claim ids must exist.

devague/frame.py

plan.pyPlan schema v2: per-task instruction field +6/-2

Plan schema v2: per-task instruction field

• Bumps 'PLAN_SCHEMA_VERSION' to 2 and adds optional 'Task.instruction' with empty-default hydration on load. Ensures v1 plans continue loading without modification.

devague/plan.py

plan_convergence.pyWarn on confirmed tasks missing instruction (non-blocking) +18/-4

Warn on confirmed tasks missing instruction (non-blocking)

• Extends plan convergence warnings with a new deterministic heuristic for confirmed tasks whose instruction is empty, while keeping readiness/blockers unchanged. Updates the warning docstring and ordering.

devague/plan_convergence.py

frame_md.pyRender instruction bullets and scope exploration section in frame markdown +27/-0

Render instruction bullets and scope exploration section in frame markdown

• Adds nested '- instruction:' bullets under claims and honesty conditions when present, and omits them when absent. Adds a '## Scope exploration' section rendering 'scope_entries' with optional seeds lines.

devague/render/frame_md.py

plan_md.pyRender per-task instruction bullet in exported plan markdown +6/-0

Render per-task instruction bullet in exported plan markdown

• Adds a task instruction bullet as the first body item beneath each task heading when instruction is present. Preserves prior byte-identical output when instruction is absent.

devague/render/plan_md.py

review_md.pyRender instructions in review markdown output +10/-2

Render instructions in review markdown output

• Extends the review artifact to include 'instruction:' lines under proposed claims and honesty conditions when present, rendering nothing when absent.

devague/render/review_md.py

spec_md.pyRender per-item instruction blocks and scope provenance in specs +91/-27

Render per-item instruction blocks and scope provenance in specs

• Refactors rendering to operate on claim objects so it can include nested 'instruction:' bullets for claims and honesty conditions. Adds a '## Scope exploration' section from 'Frame.scope_entries' and ensures empty instructions render nothing.

devague/render/spec_md.py

plan_convergence.pyAdd confirmed-task instruction warning to plan gate +18/-4

Add confirmed-task instruction warning to plan gate

• Introduces a new non-blocking warning for confirmed tasks lacking operator guidance, aligning plan sharpness with the frame’s instruction expectations while preserving readiness semantics.

devague/plan_convergence.py

Tests (17) +2071 / -4

sharper_frame.mdAdd golden fixture for frame export with instructions + scope section +43/-0

Add golden fixture for frame export with instructions + scope section

• Introduces a golden markdown file validating instruction bullets and scope exploration provenance rendering for frame exports.

tests/goldens/sharper_frame.md

sharper_plan.mdAdd golden fixture for plan export with per-task instruction +19/-0

Add golden fixture for plan export with per-task instruction

• Introduces a golden markdown file validating the task instruction bullet placement and omission behavior.

tests/goldens/sharper_plan.md

sharper_spec.mdAdd golden fixture for spec export with instructions + scope provenance +42/-0

Add golden fixture for spec export with instructions + scope provenance

• Introduces a golden markdown file validating nested instruction rendering (claims + honesty) and scope exploration provenance in spec exports.

tests/goldens/sharper_spec.md

test_boundary_audit.pyAdd boundary audit test (no LLM imports, no process spawning) +47/-0

Add boundary audit test (no LLM imports, no process spawning)

• Adds a committed audit that asserts 'devague/' does not import LLM SDKs or process-spawning modules, and does not call OS-level process spawning APIs. Protects the deterministic/non-orchestrating boundary.

tests/test_boundary_audit.py

test_cli_instructions.pyAdd CLI instruction contract tests (capture/interrogate/review) +292/-0

Add CLI instruction contract tests (capture/interrogate/review)

• Adds comprehensive tests for '--instruction' on capture/interrogate, including targeting honesty ids, validation rules, JSON shape, and re-confirm demotion with stderr diagnostics. Verifies 'review' lists instruction alongside proposed items.

tests/test_cli_instructions.py

test_cli_moves.pyHarden schema-version bump test to edit JSON structurally +3/-3

Harden schema-version bump test to edit JSON structurally

• Fixes a brittle test that assumed a hardcoded schema_version string by rewriting JSON structurally, keeping it resilient across future schema bumps.

tests/test_cli_moves.py

test_cli_scope.pyAdd 'devague scope' CLI tests (record, list, seeds validation) +154/-0

Add 'devague scope' CLI tests (record, list, seeds validation)

• Covers recording/listing scope entries, JSON shapes, frame targeting, missing-flag errors, and transactional refusal of unknown seed ids. Includes a guard asserting the command stays deterministic (no subprocess usage).

tests/test_cli_scope.py

test_convergence_sharper.pyAdd tests for frame sharpness warnings S1/S2 +225/-0

Add tests for frame sharpness warnings S1/S2

• Pins that new sharpness checks are warning-only and never affect readiness. Tests S1 (instruction required on confirmed spec-affecting claims) and S2 (measurable success signal heuristic), including documented false-positive edges.

tests/test_convergence_sharper.py

test_e2e_sharper_method.pyDogfood full method e2e: scope → frame → spec → plan → waves brief +209/-0

Dogfood full method e2e: scope → frame → spec → plan → waves brief

• Adds an end-to-end test that runs the shipped CLI surface for a real idea, validating instruction propagation, scope provenance in exports, warning-only sharpness signals, and enriched waves brief content.

tests/test_e2e_sharper_method.py

test_frame_schema_v2.pyAdd frame schema v2 tests (scope entries + instructions + v1 hydration) +149/-0

Add frame schema v2 tests (scope entries + instructions + v1 hydration)

• Verifies schema bump to v2, instruction defaults and round-trip behavior, scope entry id generation and seed validation, legacy v1 load defaults, and fail-closed rejection of newer schema versions.

tests/test_frame_schema_v2.py

test_plan.pyExtend plan unit tests for schema v2 task instructions +33/-0

Extend plan unit tests for schema v2 task instructions

• Pins 'PLAN_SCHEMA_VERSION == 2', validates task instruction defaults and verbatim round-trip, and asserts v1 task dicts hydrate instruction as empty. Extends nested-field roundtrip coverage to include instruction.

tests/test_plan.py

test_plan_cli_instructions.pyAdd plan CLI tests for '--instruction' and 'plan instruct' +177/-0

Add plan CLI tests for '--instruction' and 'plan instruct'

• Covers 'plan task --instruction', the new 'plan instruct' move, re-confirm demotion semantics with diagnostics, show JSON inclusion, and discoverability via learn/explain.

tests/test_plan_cli_instructions.py

test_plan_convergence.pyAdjust plan convergence helpers to avoid new instruction warnings +5/-1

Adjust plan convergence helpers to avoid new instruction warnings

• Updates existing convergence tests to set default instructions on confirmed tasks so new warning-only checks do not introduce noise into unrelated convergence assertions.

tests/test_plan_convergence.py

test_plan_convergence_sharper.pyAdd tests for plan instruction warning heuristic +190/-0

Add tests for plan instruction warning heuristic

• Adds coverage for the new warning emitted when confirmed tasks lack instructions, ensuring it does not impact readiness/blockers and excludes proposed/rejected tasks.

tests/test_plan_convergence_sharper.py

test_plan_render_sharper.pyAdd tests for plan-md instruction rendering and waves payload enrichment +214/-0

Add tests for plan-md instruction rendering and waves payload enrichment

• Pins byte-identical output for no-instruction plans, golden-tests instruction rendering ordering, and verifies 'plan waves --json' adds the 'tasks' map while preserving existing keys. Ensures 'waves' is read-only and excludes rejected tasks from the tasks payload.

tests/test_plan_render_sharper.py

test_plan_store.pyAdd plan store tests for v1 hydration and instruction persistence +29/-0

Add plan store tests for v1 hydration and instruction persistence

• Verifies schema_version 1 plans with tasks load with empty instruction defaults and that save/load round-trips verbatim instruction text for v2 plans.

tests/test_plan_store.py

test_render_sharper.pyAdd golden + baseline tests for spec/frame sharper rendering +240/-0

Add golden + baseline tests for spec/frame sharper rendering

• Pins byte-identical outputs when instructions/scope are absent, and golden-tests nested instruction bullets plus scope provenance sections when present. Ensures rendered markdown remains markdownlint-clean.

tests/test_render_sharper.py

Documentation (9) +489 / -82

SKILL.mdTeach enriched waves payload as the single briefing source +54/-18

Teach enriched waves payload as the single briefing source

• Updates the skill to rely on 'devague plan waves --json' as the canonical subagent brief source, including per-task instruction. Clarifies split-plan contents and explicitly forbids operator paraphrasing when composing briefs.

.claude/skills/assign-to-workforce/SKILL.md

SKILL.mdDocument shipped 'devague scope' move and provenance semantics +54/-21

Document shipped 'devague scope' move and provenance semantics

• Rewrites guidance to use the new deterministic 'devague scope' command (record/list) and explain '--seeds' validation. Updates examples to show ordering (capture claim, then scope with seeds) and export provenance.

.claude/skills/scope/SKILL.md

SKILL.mdTeach task instructions and enriched 'waves --json' brief payload +72/-21

Teach task instructions and enriched 'waves --json' brief payload

• Adds '--instruction' and 'plan instruct' to the method, explains re-confirm semantics, and documents the new 'waves --json' payload shape. Updates convergence guidance to mention warning-only instruction checks.

.claude/skills/spec-to-plan/SKILL.md

SKILL.mdTeach optional scope stage + per-item instruction semantics +58/-10

Teach optional scope stage + per-item instruction semantics

• Updates /think guidance to reflect that scope findings now land via 'devague scope'. Documents '--instruction' on capture/interrogate, re-confirm demotion on changes, and the new warning-only sharpness signals.

.claude/skills/think/SKILL.md

CHANGELOG.mdAdd 0.16.0 release notes for sharper end-to-end method +43/-0

Add 0.16.0 release notes for sharper end-to-end method

• Documents the new scope move, per-item instructions, sharper exports, enriched waves payload, warning-only sharpness checks, teaching updates, and added audits/e2e tests. Notes schema bumps for both frame and plan.

CHANGELOG.md

learn.pyTeach optional scope stage and instruction flags in 'learn' output +56/-0

Teach optional scope stage and instruction flags in 'learn' output

• Adds a scope lead-in stage description and a consolidated note describing instruction flags and their end-to-end intent. Extends 'learn --json' payload to include scope-stage and instruction guidance fields.

devague/cli/_commands/learn.py

llm-guidance.mdDocument optional scope leg and instruction semantics +35/-2

Document optional scope leg and instruction semantics

• Updates method guidance to include the optional scope stage and the new instruction field contract, including the re-confirm demotion rule and “never fabricate instructions” guidance.

docs/llm-guidance.md

skills.mdUpdate skills overview for instructions and shipped scope move +23/-6

Update skills overview for instructions and shipped scope move

• Documents that instructions flow verbatim end-to-end and that changing them demotes confirmed items. Updates scope/spec-to-plan/assign-to-workforce descriptions to match the shipped CLI surface and enriched waves payload.

docs/skills.md

spec-contract.mdSpec contract updates for schema v2, ScopeEntry, and instructions +94/-4

Spec contract updates for schema v2, ScopeEntry, and instructions

• Bumps documented schema versions, defines 'ScopeEntry', and specifies instruction fields for claims/honesty/tasks including default behavior and the re-confirm rule. Documents warning-only sharpness predicates and the plan-side symmetric warning.

docs/spec-contract.md

Other (2) +29 / -13

assign-to-workforce.shRender split-plan from enriched 'waves --json' tasks metadata +28/-12

Render split-plan from enriched 'waves --json' tasks metadata

• Switches split-plan output to read per-task 'summary', instruction presence, and acceptance-criteria count from the new top-level 'tasks' payload. Updates the printed fanout instructions to brief agents verbatim from the payload.

.claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh

pyproject.tomlBump project version to 0.16.0 +1/-1

Bump project version to 0.16.0

• Updates the package version to 0.16.0 to ship the sharper method surface and schema v2 changes.

pyproject.toml

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
99.1% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud