park --resolve / plan risk --resolve: the close-out for parked vagueness (0.20.0, #45 #55 #57 #60)

[OriNachum]

What ships

The close-out for parked vagueness, on both engines (0.20.0):

• devague park --resolve <vN> --decision "<text>" [--claim <cN>] — a decided blocking park resolves through a CLI move: the item stays on the record with its resolution text (and optionally the deciding claim via the new resolution_claim_id), drops out of the convergence gate and parked_items, and renders under a ## Resolved vagueness section in exported specs. A bare --resolve without --decision is refused (evidence-bearing close-out); unknown and already-resolved ids are refused fail-closed.
• devague plan risk --resolve <rN> --decision "<text>" — the plan-side twin for blocking PlanRisks.
• Frame SCHEMA_VERSION and PLAN_SCHEMA_VERSION bump 2 → 3; older binaries fail closed on v3 artifacts with the existing upgrade hint, v2 artifacts load with defaults.
• The blocking-vagueness / blocking-risk convergence hints now name the executable resolve move — previously they recommended "re-park it as non-blocking", which only ever appended a second item while the first kept blocking (Add a move to reclassify/resolve a parked vagueness (unblocks /think convergence after a dependency is downgraded) #45's acceptance bar, confirmed live in Add a move to reclassify/resolve a parked vagueness (unblocks /think convergence after a dependency is downgraded) #45's lobes-cli comment).
• Teaching surfaces (devague learn, docs/llm-guidance.md, the /think skill, docs/spec-contract.md) teach the resolve close-out wherever park is taught.

Closes #45, closes #55, closes #57, closes #60 — four independent reports of the same gap in five weeks, across colleague, lobes-cli, league-of-agents, and devague's own dogfooding. (#60's task-text half was already shipped as plan amend in 0.18.0/#68; only its vagueness half was live.)

How it was built

Full seven-leg dogfood: /scope → /think → /challenge → /spec-to-plan → /assign-to-workforce (9 tasks fanned out to subagent worktrees across 3 waves, TDD-gated merges) → this PR. Artifacts: docs/specs/2026-07-17-resolve-parked-vagueness.md, docs/plans/2026-07-17-resolve-parked-vagueness.md (frame/plan state committed under .devague/).

The /challenge pass (rigorous — schema-migration + data-loss signals) caught the two secondary consumers of open vagueness (parked_items in both gates, plan deliverables open items) that the initial spec missed; they're covered here (c18).

Verification

• 689 tests pass (was 616 at baseline); coverage 98.1% (gate ≥ 95%); flake8 / black / isort / bandit / markdownlint clean.
• New e2e test drives issue no unpark/resolve move: a parked unknown_blocking blocks convergence forever #57's exact repro through the real CLI on both engines: park blocking → capture decision → resolve → converge passes → export renders the resolution. Zero .devague hand-edits anywhere.
• Boundary held: the package diff introduces no subprocess/network/LLM usage (git diff main...HEAD -- devague/ grep is empty).

Note for the reviewer

The pre-existing resolve-parked-vagueness branch (commit b5c9e7c, an earlier session) specs a different shape — a new flat resolve verb with --kind re-kinding, widened to scope entries. This session's frame decisions (q1: extend park --resolve, no new verb; q3: --decision required) supersede it; that branch was left untouched and can be deleted if you agree it's superseded.

• 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]

PR Summary by Qodo

Add resolve close-out for parked vagueness and plan risks (schema v3)

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

AI Description

• Add park --resolve and plan risk --resolve to close decided blocking items via CLI.
• Persist resolution state (schema v3) and stop resolved items blocking convergence.
• Render resolved items in exports and update docs/tests to teach/verify the workflow.

Diagram

graph TD
  U(["User"]) --> CLI["CLI resolve moves"] --> M[["Frame/Plan models"]] --> S[("JSON stores")]
  CLI --> G{"Converge gates"}
  CLI --> R["Render & export"] --> O["Specs/Plans MD"]
  S --> G
  S --> R

  subgraph Legend
    direction LR
    _u(["User"]) ~~~ _cli["CLI"] ~~~ _m[["Model"]] ~~~ _s[("Store")] ~~~ _g{"Gate"} ~~~ _r["Renderer"]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. New top-level `resolve` command

• ➕ Clear separation between creating vs resolving parked items
• ➕ Potentially extensible to other resolvable entities
• ➖ Adds a new verb to learn and document
• ➖ Diverges from the existing question --resolve/park mental model this PR leverages

2. Delete resolved items instead of marking resolved

• ➕ Simpler convergence logic (no filtering by resolved flag)
• ➕ Less state carried forward
• ➖ Loses provenance/evidence trail (explicitly a requirement here)
• ➖ Harder to render resolutions in exported specs/plans

3. Allow in-place reclassification (`--kind` update) instead of resolve+re-park

• ➕ Directly supports “reclassify” workflows without duplicating entries
• ➕ Reduces number of items in the record
• ➖ Mutates historical record (weaker provenance)
• ➖ Broader CLI surface area and additional validation rules

Recommendation: Keep the PR’s approach: extend existing verbs with --resolve and persist resolution state (fail-closed). It minimizes new CLI surface area, preserves provenance for exported specs, and fixes the convergence dead-end without requiring hand-edits. The alternatives either expand the command surface materially or compromise the evidence trail that motivated the change.

Files changed (35) +2541 / -58

Enhancement (7) +275 / -22

park.pyImplement 'park --resolve' with required decision and optional claim link +79/-6

Implement 'park --resolve' with required decision and optional claim link

• Splits park handling into create vs resolve paths, adds new flags ('--resolve', '--decision', '--claim'), validates fail-closed, and emits JSON/stdout results consistent with existing CLI conventions.

devague/cli/_commands/park.py

plan.pyImplement 'plan risk --resolve' with required decision +59/-4

Implement 'plan risk --resolve' with required decision

• Adds a resolve path to the plan risk subcommand, making create args optional at parse-time but enforced in-handler; persists resolution via 'Plan.resolve_risk' and provides JSON/stdout output with fail-closed validation.

devague/cli/_commands/plan.py

frame.pyAdd Vagueness resolution state and 'Frame.resolve_vagueness'; bump schema v3 +39/-1

Add Vagueness resolution state and 'Frame.resolve_vagueness'; bump schema v3

• Introduces 'resolved', 'resolution', and 'resolution_claim_id' fields on Vagueness, adds lookup + resolve mutators with fail-closed validation, and bumps 'SCHEMA_VERSION' to 3.

devague/frame.py

plan.pyAdd PlanRisk resolution state and 'Plan.resolve_risk'; bump plan schema v3 +34/-1

Add PlanRisk resolution state and 'Plan.resolve_risk'; bump plan schema v3

• Introduces 'resolved' and 'resolution' on PlanRisk, adds lookup + resolve mutators mirroring frame-side error semantics, and bumps 'PLAN_SCHEMA_VERSION' to 3.

devague/plan.py

deliverables_md.pyExclude resolved vagueness/risks from deliverables open-items section +11/-6

Exclude resolved vagueness/risks from deliverables open-items section

• Updates deliverables rendering to treat resolved items as closed and exclude them from the surviving open-items list.

devague/render/deliverables_md.py

frame_md.pyRender resolved vagueness bullets with resolution text +17/-2

Render resolved vagueness bullets with resolution text

• Adds formatting to show '— resolved: <text>' for resolved items (only when resolution is non-empty) while keeping the single Open vagueness section.

devague/render/frame_md.py

spec_md.pyAdd 'Resolved vagueness' section to exported spec markdown +36/-2

Add 'Resolved vagueness' section to exported spec markdown

• Filters resolved items out of open/follow-up lists and introduces a dedicated section rendering resolved vagueness (with URL autolinking) only when resolution text exists.

devague/render/spec_md.py

Bug fix (2) +48 / -9

convergence.pyExclude resolved vagueness from blockers and parked items; update hint +22/-5

Exclude resolved vagueness from blockers and parked items; update hint

• Stops counting resolved blocking vagueness as convergence blockers, removes resolved items from parked-item listings, and updates suggest_move to an executable 'devague park --resolve ...' hint.

devague/convergence.py

plan_convergence.pyExclude resolved risks from blockers and parked items; update hint +26/-4

Exclude resolved risks from blockers and parked items; update hint

• Stops counting resolved blocking risks as plan convergence blockers, removes resolved risks from parked-item listings, and updates suggest_move to executable 'devague plan risk --resolve ...' syntax.

devague/plan_convergence.py

Tests (15) +1036 / -9

resolved_vagueness_frame.mdAdd golden for frame-md rendering of resolved vagueness +13/-0

Add golden for frame-md rendering of resolved vagueness

• Introduces expected markdown output validating resolved vagueness formatting in frame renderings.

tests/goldens/resolved_vagueness_frame.md

resolved_vagueness_spec.mdAdd golden for spec-md 'Resolved vagueness' section +8/-0

Add golden for spec-md 'Resolved vagueness' section

• Introduces expected markdown output validating the new spec export section for resolved vagueness.

tests/goldens/resolved_vagueness_spec.md

test_cli_learn.pyAssert learn output names 'park --resolve' and 'risk --resolve' +24/-0

Assert learn output names 'park --resolve' and 'risk --resolve'

• Adds tests ensuring teaching surfaces include the new resolve commands and flags.

tests/test_cli_learn.py

test_cli_moves.pyAdd CLI tests for 'park --resolve' validation and persistence +123/-0

Add CLI tests for 'park --resolve' validation and persistence

• Covers happy path, JSON parity, required decision enforcement, unknown/already-resolved id refusals, and deciding-claim linking semantics.

tests/test_cli_moves.py

test_cli_plan.pyAdd CLI tests for 'plan risk --resolve' and create-path enforcement +69/-0

Add CLI tests for 'plan risk --resolve' and create-path enforcement

• Ensures risk creation still requires text+kind while resolve requires '--decision', and validates unknown/already-resolved refusals.

tests/test_cli_plan.py

test_convergence.pyTest convergence skips resolved vagueness and emits new hint +49/-1

Test convergence skips resolved vagueness and emits new hint

• Adds coverage for resolved items not blocking, parked_items excluding resolved, and suggest_move emitting executable 'park --resolve' syntax.

tests/test_convergence.py

test_e2e_resolve.pyAdd end-to-end tests for issue #57 lifecycle (frame + plan) +218/-0

Add end-to-end tests for issue #57 lifecycle (frame + plan)

• Drives the real CLI workflow: park blocking → decide → resolve → converge passes → export renders resolution; includes optional markdownlint-cli2 checks when available.

tests/test_e2e_resolve.py

test_frame.pyTest Vagueness resolution fields, resolver behavior, and legacy defaults +134/-0

Test Vagueness resolution fields, resolver behavior, and legacy defaults

• Validates schema version bump, default field values, resolve semantics, deciding-claim linking behavior, and compatibility with v2/v3 legacy persisted shapes.

tests/test_frame.py

test_frame_schema_v2.pyUpdate schema-version pin test for frame schema v3 +4/-1

Update schema-version pin test for frame schema v3

• Adjusts the previously pinned schema version assertion to match the new legitimate bump.

tests/test_frame_schema_v2.py

test_plan.pyTest PlanRisk resolution fields, resolver behavior, and legacy defaults +70/-4

Test PlanRisk resolution fields, resolver behavior, and legacy defaults

• Adds unit coverage for PlanRisk resolution defaults, resolve semantics, schema version bump to v3, and v2 plan compatibility defaults.

tests/test_plan.py

test_plan_convergence.pyTest plan convergence skips resolved risks and emits new hint +60/-1

Test plan convergence skips resolved risks and emits new hint

• Ensures unresolved risks still block, resolved risks no longer block or appear in required moves/parked items, and hints name the executable resolve syntax.

tests/test_plan_convergence.py

test_plan_deliverables.pyTest deliverables excludes resolved vagueness and risks from open items +47/-0

Test deliverables excludes resolved vagueness and risks from open items

• Validates that resolved items are removed from the Open items section while unresolved items remain visible.

tests/test_plan_deliverables.py

test_plan_store.pyTest plan store round-trips resolved risks and loads v2 defaults +34/-1

Test plan store round-trips resolved risks and loads v2 defaults

• Adds persistence tests for resolved risks and updates schema version upgrade assertions to match the new plan schema version.

tests/test_plan_store.py

test_render.pyTest rendering behavior for resolved vagueness and markdownlint cleanliness +151/-0

Test rendering behavior for resolved vagueness and markdownlint cleanliness

• Adds render tests (including goldens) for frame/spec output, URL autolinking in resolutions, and optional markdownlint-cli2 verification when present.

tests/test_render.py

test_store.pyTest frame store round-trips resolved vagueness and loads v2 defaults +32/-1

Test frame store round-trips resolved vagueness and loads v2 defaults

• Adds persistence tests for resolved vagueness and updates schema version upgrade assertions to follow the bumped frame schema version.

tests/test_store.py

Documentation (7) +321 / -16

SKILL.mdTeach 'park --resolve' in the /think skill move table and rules +7/-1

Teach 'park --resolve' in the /think skill move table and rules

• Adds the resolve close-out move to the documented workflow and reinforces that decided blocking parks should be resolved via CLI rather than hand-editing state.

.claude/skills/think/SKILL.md

CHANGELOG.mdDocument 0.20.0: resolve moves, schema bump, and updated hints +32/-0

Document 0.20.0: resolve moves, schema bump, and updated hints

• Adds a 0.20.0 entry describing new resolve commands, schema version changes, and updated learning surfaces.

CHANGELOG.md

learn.pyUpdate learn text to include resolve close-out for park +8/-2

Update learn text to include resolve close-out for park

• Extends command descriptions and operating rules to reference 'park --resolve ... --decision ...' as the supported close-out path.

devague/cli/_commands/learn.py

llm-guidance.mdTeach resolve close-out for parked items and plan risks +13/-3

Teach resolve close-out for parked items and plan risks

• Updates guidance to explicitly instruct resolving decided blocking parks/risks via the new CLI moves instead of leaving them parked or editing state.

docs/llm-guidance.md

2026-07-17-resolve-parked-vagueness.mdAdd build plan markdown for resolve-parked-vagueness +105/-0

Add build plan markdown for resolve-parked-vagueness

• Adds a human-readable plan document enumerating tasks, acceptance criteria, and risks for the work shipped in this PR.

docs/plans/2026-07-17-resolve-parked-vagueness.md

spec-contract.mdDocument schema v3 and new resolve moves in the contract +42/-10

Document schema v3 and new resolve moves in the contract

• Updates entity definitions, move tables, validation rules, and versioning sections for frame/plan schema v3 and the new resolve commands.

docs/spec-contract.md

2026-07-17-resolve-parked-vagueness.mdAdd feature spec markdown describing resolve close-out and constraints +114/-0

Add feature spec markdown describing resolve close-out and constraints

• Adds the spec artifact capturing motivations, requirements, decisions, and boundaries for resolving parked vagueness and plan risks.

docs/specs/2026-07-17-resolve-parked-vagueness.md

Other (4) +861 / -2

current_planPoint current devague plan at resolve-parked-vagueness +1/-1

Point current devague plan at resolve-parked-vagueness

• Updates the tracked plan slug used by the repo’s devague workflow state.

.devague/current_plan

resolve-parked-vagueness.jsonAdd exported frame artifact for resolve-parked-vagueness +490/-0

Add exported frame artifact for resolve-parked-vagueness

• Checks in the frame JSON capturing requirements/decisions and acceptance criteria for the feature work.

.devague/frames/resolve-parked-vagueness.json

resolve-parked-vagueness.jsonAdd exported plan artifact for resolve-parked-vagueness +369/-0

Add exported plan artifact for resolve-parked-vagueness

• Checks in the plan JSON (tasks, dependencies, risks) driving implementation and verification of the resolve feature.

.devague/plans/resolve-parked-vagueness.json

pyproject.tomlBump package version to 0.20.0 +1/-1

Bump package version to 0.20.0

• Updates project version to reflect the new CLI surface and schema changes.

pyproject.toml

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (1) 📎 Requirement gaps (0) 📜 Skill insights (0)

Context used

✅ Tickets: 🎫 Add a move to reclassify/resolve a parked vagueness (unblocks /think convergence after a dependency is downgraded) 🎫 No verb to resolve parked vagueness (or edit task text) — operators hand-edit .devague state JSON 🎫 No CLI verb to resolve parked vagueness (blocking vagueness can only be removed by editing frame state)

✅ Compliance rules (platform): 75 rules

✅ Skills: cicd, communicate

1. llm claims marked confirmed 📘 Rule violation ≡ Correctness

Description

The newly added frame and plan artifacts include LLM-originated Claim and Task entries marked
status: confirmed, which conflicts with the requirement that LLM-originated items must start in
proposed and not be auto-confirmed. This bypasses the intended human-review gate for
LLM-originated state.

Code

.devague/frames/resolve-parked-vagueness.json[R27-33]

+    {
+      "id": "c2",
+      "kind": "requirement",
+      "text": "the Vagueness dataclass (devague/frame.py:106) gains resolution state \u2014 e.g. a resolved flag plus resolution text \u2014 kept in frame state for the evidence trail rather than deleted; add_vagueness today only appends and set_status (frame.py:226) routes only claim and honesty ids, so v-ids are unaddressable by any move",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [

Relevance

⭐ Low

Similar suggestions to change origin:llm status confirmed→proposed in artifacts were repeatedly
rejected (PRs #15, #63).

PR-#15
PR-#63

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 738290 specifies that any LLM-originated claims/tasks must start in proposed and
must never be auto-confirmed. The added frame file contains a Claim with origin: llm and
status: confirmed, and the added plan file contains Task entries with origin: llm and `status:
confirmed`, directly demonstrating the non-compliant state in both artifacts.

Rule 738290: LLM-originated claims and tasks must start in proposed status and never be auto-confirmed
.devague/frames/resolve-parked-vagueness.json[27-33]
.devague/plans/resolve-parked-vagueness.json[151-156]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The committed frame and plan state contain LLM-originated `Claim` and `Task` records that are already marked `confirmed`, violating the requirement that LLM-originated items must begin as `proposed` and not be auto-confirmed.

## Issue Context
PR Compliance ID 738290 requires LLM-originated claims/tasks to start in `proposed` and never be auto-confirmed, preserving a human-review step before confirmation.

## Fix Focus Areas
- .devague/frames/resolve-parked-vagueness.json[27-33]
- .devague/plans/resolve-parked-vagueness.json[151-156]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Committed plan pointer file 🐞 Bug ⚙ Maintainability

Description

The PR modifies and commits .devague/current_plan, but this path is documented as an uncommitted
local pointer and is rewritten by plan_store.save(), so it will keep generating meaningless
diffs/merge conflicts. It can also make devague plan default to an unintended/stale plan slug on
other checkouts.

Code

.devague/current_plan[1]

+resolve-parked-vagueness

Relevance

⭐ Low

Same request to gitignore/untrack .devague/current_plan was rejected in PR #15 review history.

PR-#15

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The repo explicitly documents .devague/current_plan as a local (non-committed) pointer, but it is
tracked and changed in this PR; additionally, it is not ignored by .gitignore and is rewritten by
the plan persistence layer, guaranteeing recurring diffs.

README.md[66-74]
.gitignore[226-233]
devague/plan_store.py[18-47]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`.devague/current_plan` is a local pointer (not meant to be committed) but this PR changes it and keeps it tracked. Because the CLI writes this file on every plan save, it will constantly churn in git and can point other checkouts/branches at the wrong default plan.

### Issue Context
- README documents `.devague/current_plan` as **not committed**.
- `.gitignore` currently ignores `.devague/current` but **not** `.devague/current_plan`.
- `devague/plan_store.py` always writes `.devague/current_plan`.

### Fix
1. Remove `.devague/current_plan` from the PR / untrack it (`git rm --cached .devague/current_plan`) so it becomes local-only.
2. Add `.devague/current_plan` to `.gitignore` near the existing `.devague/current` ignore.
3. (Optional but aligns with README promise) Update `plan_store.save()` to ensure `.devague/current_plan` is added to the devague-managed `.gitignore` block (similar to how `devague.store.ensure_ignored()` is used for other working-state paths).

### Fix Focus Areas
- .devague/current_plan[1-1]
- .gitignore[226-233]
- devague/plan_store.py[18-47]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[OriNachum]

Triage of the latest Qodo review (1 bug, 1 rule violation) — both rejected as not-a-defect after verification, consistent with this repo's prior review history:

1. "LLM claims marked confirmed" (rule 738290) — rejected. (origin: llm, status: confirmed) is the post-confirmation state, not an auto-confirm: every such claim/task in the committed artifacts was explicitly confirmed by the human operator during the session (the devague confirm batches recorded in the frame's review flow). State and provenance are orthogonal by design — docs/spec-contract.md's provenance table maps user_confirmed to exactly (status=confirmed) after an explicit user confirm, regardless of origin. Rewriting the committed state to proposed would falsify a real human confirmation. Qodo's own relevance note records this same suggestion rejected on #15 and #63.

2. "Committed plan pointer file" (.devague/current_plan) — rejected. The claimed evidence ("the repo explicitly documents .devague/current_plan as a local non-committed pointer") does not exist: the only occurrence of current_plan outside state is the path constant in devague/plan_store.py. Repo convention is the opposite — the pointer has been committed in every recent feature PR (#63, #72, #76, and the standalone 0e47e9c chore: point current_plan at challenge-skill), and untracking it was already rejected in #15's review history. What devague deliberately keeps uncommitted is .devague/reviews/ and .devague/questions/ (#17), which this PR honors.

No code changes made for either finding.

• devague (Claude)