[OriNachum]

Docs and skills refresh — no CLI behavior change. Delivery summary below is the review map (docs/deliveries/2026-09-04-coherent-public-face-and-fresh-ledgers.md); spec and plan are committed beside it.

Closes #100, closes #47.

Intent

devague's README now reads like agentculture.org/agents/devague — diagrams, real code examples, all eight skills in flow order — the eight skills tell one coherent story, and every ledger (claims, lapses, deviations, evidence, deltas) is CLI-managed and filed the moment it happens, so the record stays fresh

After: A newcomer reads README.md top to bottom and meets one eight-leg diagram, numbered moves with real captured output, the three human gates, and the ledgers the CLI keeps; the eight skills agree with each other and with the CLI; CLAUDE.md and docs describe the shipped surface with no statement the code contradicts

Planned Work

• t1 — Conventions source of truth in docs/skills.md: the shared hand-off section, the shared freshness rule, and the canonical eight-leg diagram block
• t2 — CLAUDE.md: shrink the Status section to the current release plus a CHANGELOG pointer and remove the two false statements
• t3 — docs/spec-contract.md: entity sections for Obligation, EvidenceRecord and DeltaRecord matching the shipped dataclasses
• t4 — README.md rewrite: what / why it works / how to use / impact, with the eight-leg mermaid diagram, numbered walkthrough, agent-driven statement above the fold, verified captures and the artifact table
• t5 — Skills cluster A (scope, think, challenge, spec-to-plan): fix think's after-export paths, add the shared hand-off section, freshness rule and next: hint mention
• t6 — Skills cluster B (assign-to-workforce, deviate, validate-delivery, summarize-delivery): redraw the six-leg diagrams as eight legs, add the shared hand-off section, freshness rule, next: hint and devague today mentions
• t7 — tests/test_readme_commands.py: pin README.md to the shipped CLI and to its own structural promises
• t8 — Release hygiene: patch version bump and a CHANGELOG entry that quotes the before state verbatim
• t9 — Verification sweep: boundaries untouched, no stale leg or verb text anywhere, lint and tests green, README answers the three reader questions

Actual Delivery

Plan task	Status	What actually landed
t1	delivered	docs/skills.md gains ### Shared conventions (hand-off heading + template, freshness sentence, canonical eight-leg block) and one pointer sentence per skill section — commit 6d349da, merged 114a290
t2	delivered	CLAUDE.md Status cut from 265 lines to one 0.24.0 paragraph plus a CHANGELOG pointer; both false statements gone; everything below Status byte-identical — commit 5350a54, merged c4bf2fe
t3	delivered	docs/spec-contract.md gains Obligation, CriterionObligation, RunReference, EvidenceRecord, DeltaRecord, SupersessionEvent sections; field-diff script reported zero differences — commit 3a1d0f7, merged 6119de5
t4	delivered	README.md rewritten to the four sections with one mermaid diagram, eight-item walkthrough, three version-stamped captures, impact table (227 lines) — commit 204a92f, merged 4d7023f; then re-edited by the main agent under d1 to 202 lines — commit c5ae504
t5	delivered	scope / think / challenge / spec-to-plan gain the hand-off section, freshness bullet and next: mention; think's after-export paths fixed (#47) — commit 112f28f, merged e4a36d6
t6	delivered	assign-to-workforce / deviate / validate-delivery / summarize-delivery gain the same; deviate and summarize-delivery diagrams redrawn to eight legs (#100); devague today named in the two closing skills — commit 189bf33, merged dbf0ef6
t7	delivered	tests/test_readme_commands.py (7 tests) pins README command lines to devague.cli._build_parser and its structure — commit ee8e5a1, merged f223030
t8	delivered	version 0.24.1, uv.lock, CHANGELOG entry quoting the three before-state lines — commit b94b685, merged 596a8e8; two misattributed bullets corrected by the main agent — commit 952fe6a (lapse l2)
t9	delivered	sweep ran every criterion; fixed a pre-existing MD038 in assign-to-workforce/SKILL.md — commit fa5a21c, merged 171589e; its two criterion-1 failures were false positives of the criterion, not violations (lapse l3)

Mid-work Decisions

• d1 — After t4's README lands and t7's pinning test merges, the main agent (not a workforce subagent) makes an additional editorial pass over README.md: validate it against the spec, make it welcoming, cut prose to light-or-none, keep it technical and clear; t7's test and t9's sweep must still pass afterwards — user request mid-run: the leading model owns the final README quality, beyond t4's acceptance criteria

• d2 — Post-run README restructure by the main agent: install and agent setup move to the top, the verb-level walkthrough and the three console captures are removed, tests/test_readme_commands.py is re-pinned to the new section list; supersedes the shape t4 and t7 delivered — user direction after gate 3 opened: devague is installed with uv tool install / uvx and the agent learns the skills via devague learn skills; specific commands do not matter to the human reader

• CHANGELOG bullets from t8 were corrected by the main agent after merge (think fix misdescribed; a CLAUDE.md quote misattributed to spec-contract.md) — no deviation record; recorded as lapse l2 and fixed in 952fe6a.

• t9's first acceptance criterion produced two false failures (untracked files in ../org dated July, and the .devague/ frame and plan JSON the spec and plan commits intentionally added); resolved by measurement (git -C ../org diff --stat empty), not by editing the criterion — recorded as lapse l3.

• t9 fixed a pre-existing MD038 lint error in assign-to-workforce/SKILL.md that the repo's .claude/skills/** lint ignore had hidden — within its instruction, no record needed.

Drift From Plan

Plan item	Reason for divergence	Classification
t4 (d1)	user request mid-run: the leading model owns the final README quality, beyond t4's acceptance criteria	acceptable
t4, t7 (d2)	user direction after gate 3 opened: devague is installed with uv tool install / uvx and the agent learns the skills via devague learn skills; specific commands do not matter to the human reader	acceptable
t8	CHANGELOG entry needed two factual corrections after merge (l2); the version bump and quotes were correct	acceptable
t9	criterion 1 as written flagged pre-existing untracked files and intended .devague/ state as violations (l3); the honesty conditions h4 and h9 behind it hold	acceptable

Evidence

• tests: tests/test_readme_commands.py — pass (7 passed)
• tests: tests/test_spec_to_plan_skill.py tests/test_teaching_surface_sweep.py tests/test_cli_learn.py tests/test_summary.py — pass (199 passed)
• tests: uv run pytest -n auto -q — pass (1651 passed; baseline before the run 1644)
• lint: uv run flake8 --config=.flake8 devague/ tests/ — clean
• lint: markdownlint-cli2 README.md CLAUDE.md CHANGELOG.md docs/*.md — 0 errors
• lint: the eight SKILL.md files copied beside a config without the .claude/skills/** ignore — 0 errors
• grep: six-leg|seven-leg|still unimplemented|ships separately|docs/reviews across README, CLAUDE.md, docs, skills — 0 hits
• render: readme_renderer on README.md — one pre lang=mermaid block, list items intact (PyPI fallback)
• boundary: git -C ../org diff --stat and --cached — empty; git -C ../guildmaster status --short — empty
• commits: 4e66665..171589e (spec, plan, split, nine task merges, two main-agent reconciliations)
• ledger: obligations o1–o12, evidence e1–e12 (all pass, run commit 171589e), deltas b1 b2, deviations d1 d2, lapses l1–l3 — all approved
• note: d2 removed the console captures after e2/e1 were filed; c3's capture half and h14 no longer hold on the final README and are superseded by decision c29, not claimed
• PRs / issues: this branch's PR (opened after this artifact; closes deviate and summarize-delivery SKILL.md still draw the six-leg flow — /challenge is missing #100 and think SKILL.md: After-export step documents stale frame/review paths (.devague/<slug>.json vs .devague/frames/, docs/reviews/ vs .devague/reviews/) #47)

Delivery Claims

Claim	Confidence	Evidence
c2 — README.md replaces its stale three-stage arrow (README.md lines 10-12: idea, spec, plan, build) with an eight-leg pipeline diagram as a mermaid fence, and adds a numbered move walkthrough (01 scope ... 08 summarize-delivery) modeled on the site page's pipeline stages and method sections	execution	tests/test_readme_commands.py (run 2026-09-04)
c3 — README.md gains real, verified code examples: every command block is checked against the shipped 'devague --help' / 'devague plan --help' output, and one short verbatim terminal capture per engine (frame, plan, delivery ledger) shows actual output including the 'next:' stderr hint	coverage	tests/test_readme_commands.py::test_readme_commands_parse (run 2026-09-04)
c4 — README.md does not copy the site page's leg count: agentculture.org/agents/devague still presents seven legs and seven operator skills (no validate-delivery, no lapse, no oblige/evidence/delta, no today); the README stays ahead and the site is updated separately in the org repo	fidelity	git -C ../org diff --stat and diff --cached --stat (run 2026-09-04)
c6 — The deviate and summarize-delivery skills redraw their literal flow diagrams (deviate/SKILL.md lines 20-25, summarize-delivery/SKILL.md lines 22-27) as the eight-leg flow, and think/SKILL.md's after-export step (lines 275-277) cites .devague/frames/ and .devague/reviews/ instead of .devague/ and docs/reviews/ (closes issues 100 and 47)	execution	grep -rn 'six-leg|seven-leg|docs/reviews' + md5sum of the three diagram blocks (run 2026-09-04)
c7 — Every skill that files a ledger record carries one explicit freshness rule in its hard rules: file the record at the moment the thing happens, never at closeout; today only challenge (line 178), deviate (lines 4-5, 44, 109) and summarize-delivery (lines 33, 308) say so, while scope, spec-to-plan, assign-to-workforce and validate-delivery do not	execution	tr newline + grep across the eight SKILL.md (run 2026-09-04)
c8 — The eight skills share one hand-off convention: each SKILL.md states the leg before it and after it in a same-named section, mentions devague today where the leg produces or consumes it (validate-delivery, summarize-delivery), and mentions the 'next:' stderr hint as the CLI's own next-move signal (issue 40 item 14 flags spec-to-plan's missing hand-off section)	execution	grep -l for the hand-off heading, 'next: ' and 'devague today' (run 2026-09-04)
c15 — CLAUDE.md's Status section shrinks to the current release plus a pointer to CHANGELOG.md, and its two false statements are removed (lines 49-50: 'the exact oblige / evidence / delta CLI surface ships separately'; lines 199-202: 'devague scope ... still unimplemented'); docs/spec-contract.md gains entity sections for Obligation, EvidenceRecord and DeltaRecord documenting the fields that exist today	execution	awk over CLAUDE.md Status + grep -c of six entity headings in docs/spec-contract.md (run 2026-09-04)
c18 — Humans meeting devague cold on GitHub or PyPI (a reader deciding whether to install it) first; operator agents driving the CLI second, via the skills and devague learn	execution	sed -n 1,12p README.md | grep for ids, capture, interrogate, converge (run 2026-09-04)
c19 — A reader who has only the README can name the eight legs in order, the three human gates, and what devague never does (call an LLM, run a test, orchestrate); markdownlint-cli2 passes on every touched file; every command block in README matches the shipped --help output	execution	markdownlint-cli2 on README.md CLAUDE.md CHANGELOG.md docs/*.md, and on the eight SKILL.md copied beside a config without the skills ignore (run 2026-09-04)
c23 — The numbered eight-leg walkthrough in README.md stands alone as the text fallback for the diagram: pyproject.toml line 6 makes README.md the PyPI long description, and a scratch probe with readme_renderer rendered a mermaid fence as a plain pre block (lang mermaid), so PyPI readers never see the diagram	execution	uv run --with readme-renderer[md] python -m readme_renderer README.md (run 2026-09-04)
c24 — The full pytest suite stays green after the skill edits: tests/test_spec_to_plan_skill.py (t19) pins spec-to-plan's moves table to the live CLI, tests/test_teaching_surface_sweep.py section 9 pins learn output against scope/SKILL.md, tests/test_cli_learn.py pins the SKILL.md paths, and tests/test_summary.py pins the delivery summary's eight sections to summarize-delivery/SKILL.md order	execution	uv run pytest -n auto -q (run 2026-09-04)
c25 — The PR bumps the version (patch, 0.24.x) and prepends a CHANGELOG.md entry: .github/workflows/tests.yml line 64 enforces the AgentCulture rule that every PR bumps the version, docs included	coverage	uv run devague --version + grep -n in CHANGELOG.md (run 2026-09-04)

Confidence tokens above are the evidence ledger's strength values. Three approved lapses cap what they touch: l1 (a hand-edited capture, caught and restored) bears on c3; l2 on the CHANGELOG half of c25; l3 on the boundary check behind c4. None was found by reading data afterwards — each was filed the moment it was reported.

Lapse ledger evidence:

Lapse	Code	What
l1	provenance-missing	t4 README agent shortened a captured 'devague plan task' line (dropped --instruction and two --covers flags) while claiming captures were verbatim; caught before commit, exact recorded line restored and a byte-identity differ added
l2	provenance-missing	t8 CHANGELOG entry misdescribed think's fix (said 'route through /challenge'; the fix was the .devague/frames and .devague/reviews paths, #47) and attributed the 'ships separately' sentence to docs/spec-contract.md when git show main proves it was in CLAUDE.md
l3	grader-unverified	t9's first acceptance criterion, which I authored, graded 'git status --short empty' in ../org and a path allow-list without .devague/; both conflated pre-existing untracked files and intended frame/plan state with violations, so the grader reported two false failures

Remaining Work / Follow-up

• agentculture.org/agents/devague still presents seven legs (park v1) — file an issue on the org repo to bring the page to eight legs with validate-delivery, lapse, evidence/delta and today; owner: the user.

• guildmaster skill-update brief (park v3, risk r2) — after this PR merges, send the communicate skill's skill-update-brief.md so mesh consumers re-vendor the eight skills; owner: devague agent.

• README captures embed 0.24.x output (risk r1) — refresh when a release changes any captured line; the version comment on each capture makes staleness visible.

• .claude/skills/** is ignored by the repo's markdownlint config, so skill files lint only by hand (found by t6, fixed by t9) — consider a CI step that lints them with the ignore lifted; owner: follow-up issue.

• Obligation id prefix o collides between frame and plan (Obligation ids collide across the frame and plan mints — a bare obligation_ref in a delivery ledger is ambiguous #108) — documented in spec-contract.md as a known ambiguity, not fixed here.

• After merge: close deviate and summarize-delivery SKILL.md still draw the six-leg flow — /challenge is missing #100 and think SKILL.md: After-export step documents stale frame/review paths (.devague/<slug>.json vs .devague/frames/, docs/reviews/ vs .devague/reviews/) #47; then /summarize-delivery's park v2 (mermaid syntax parity with the site pipeline) stays open until the README is ever republished there.

• devague (Claude)

🤖 Generated with Claude Code

https://claude.ai/code/session_01NBUnemNDpVK7dD63m9HQNK

[qodo-code-review]

PR Summary by Qodo

Align README and eight-skill documentation for 0.24.1

📝 Documentation 🐞 Bug fix 🧪 Tests ⚙️ Configuration changes 🕐 40+ Minutes

AI Description

• Reframes README around the eight-skill, three-gate workflow with verified CLI captures.
• Synchronizes skill hand-offs, freshness rules, paths, and shipped ledger contracts.
• Adds README drift tests and releases the documentation refresh as 0.24.1.

Diagram

graph TD
  CONV["Shared conventions"] --> SKILLS["Eight skills"] --> README["Public README"]
  PARSER["CLI parser"] --> TESTS["README tests"] --> README
  LEDGERS[("Ledger records")] --> CONTRACT["Spec contract"] --> README
  LEDGERS --> CURRENT["Current spec"] --> README

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Generate command examples and captures

• ➕ Eliminates manual drift between README examples and CLI output.
• ➕ Could refresh version-stamped captures automatically during releases.
• ➕ Reduces reliance on structural assertions over hand-authored Markdown.
• ➖ Introduces documentation-generation tooling beyond this behavior-preserving release.
• ➖ Generated content may reduce editorial clarity in the public README.
• ➖ Still requires explicit review of narrative, workflow order, and human gates.

Recommendation: Keep the PR's source-of-truth plus parser-backed validation approach for 0.24.1: it preserves the curated README while correcting cross-document inconsistencies without changing CLI behavior. Consider generation only as a follow-up for the version-stamped terminal captures, which remain the primary manually aging surface.

Files changed (25) +3056 / -398

Tests (1) +241 / -0

test_readme_commands.pyPin README commands and workflow structure +241/-0

Pin README commands and workflow structure

• Adds parser-backed validation for README bash commands and flags. Also asserts the Mermaid count, eight-leg ordering, version-stamped captures, capture count, and exact H2 structure.

tests/test_readme_commands.py

Documentation (7) +315 / -5

SKILL.mdAdd challenge hand-off and freshness conventions +13/-1

Add challenge hand-off and freshness conventions

• Documents CLI next-move hints, immediate record filing, and the transition from think to spec-to-plan.

.claude/skills/challenge/SKILL.md

SKILL.mdDocument scope workflow boundaries and freshness +14/-0

Document scope workflow boundaries and freshness

• Adds next-move hint guidance, the shared immediate-filing rule, and the opening-leg hand-off to think.

.claude/skills/scope/SKILL.md

SKILL.mdAdd planning hand-off and freshness guidance +14/-0

Add planning hand-off and freshness guidance

• Documents CLI progression hints, immediate ledger filing, and the challenge-to-workforce transition surrounding this leg.

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

SKILL.mdConnect validation to adjacent legs and current-spec projection +15/-0

Connect validation to adjacent legs and current-spec projection

• Adds the shared freshness rule, deviate-to-summary hand-off, next-move guidance, and documentation of how evidence feeds 'devague today'.

.claude/skills/validate-delivery/SKILL.md

current-spec.mdProject the new README behavior and test coverage +12/-2

Project the new README behavior and test coverage

• Updates the behavior-ledger coverage boundary for the new delivery. Adds the README pinning tests and final editorial rewrite as current behaviors with evidence and provenance.

docs/current-spec.md

skills.mdDefine shared conventions for all eight skills +66/-0

Define shared conventions for all eight skills

• Establishes one source of truth for hand-off sections, immediate-filing language, and the canonical eight-leg flow. Each skill section now points back to those conventions.

docs/skills.md

spec-contract.mdDocument shipped obligation and delivery entities +181/-2

Document shipped obligation and delivery entities

• Adds contract sections for frame and plan obligations, run references, evidence, behavior deltas, and supersession events. It also documents append-only semantics and the known frame/plan obligation ID ambiguity.

docs/spec-contract.md

Other (17) +2500 / -393

SKILL.mdRequire immediate lapse filing during workforce execution +25/-9

Require immediate lapse filing during workforce execution

• Clarifies that the main agent files reported lapses immediately rather than at closeout. Adds the shared freshness rule, adjacent-leg hand-off, next-move guidance, and a markdown lint correction.

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

SKILL.mdCorrect deviate to the eight-leg workflow +16/-2

Correct deviate to the eight-leg workflow

• Replaces the stale six-leg diagram with the canonical eight-leg sequence. Adds freshness, next-move, and adjacent-leg guidance.

.claude/skills/deviate/SKILL.md

SKILL.mdCorrect delivery closure to the eight-leg workflow +19/-2

Correct delivery closure to the eight-leg workflow

• Replaces the stale six-leg description and diagram with the canonical sequence. Adds terminal hand-off wording, freshness guidance, next-move hints, and the current-spec projection.

.claude/skills/summarize-delivery/SKILL.md

SKILL.mdFix exported frame and review artifact paths +16/-2

Fix exported frame and review artifact paths

• Corrects after-export paths to '.devague/frames/' and '.devague/reviews/'. Adds next-move, freshness, and scope-to-challenge hand-off guidance.

.claude/skills/think/SKILL.md

current_planSelect the coherent-public-face plan +1/-1

Select the coherent-public-face plan

• Updates the local plan pointer from the previous release effort to this documentation refresh.

.devague/current_plan

coherent-public-face-and-fresh-ledgers.jsonRecord delivery evidence and behavioral deltas +286/-0

Record delivery evidence and behavioral deltas

• Adds the committed delivery ledger containing the approved README deviation, twelve evidence records, and two behavior deltas. The records tie the delivered documentation and tests back to their obligations.

.devague/deliveries/coherent-public-face-and-fresh-ledgers.json

coherent-public-face-and-fresh-ledgers.jsonCapture the documentation refresh frame +883/-0

Capture the documentation refresh frame

• Adds the converged frame containing requirements, decisions, scope findings, parks, lapses, and validation obligations. It records why the work remains documentation-only and why its scope extends beyond README.

.devague/frames/coherent-public-face-and-fresh-ledgers.json

coherent-public-face-and-fresh-ledgers.jsonCapture the converged nine-task plan +492/-0

Capture the converged nine-task plan

• Adds the structured implementation plan, coverage targets, task dependencies, acceptance criteria, and follow-up risks for the documentation refresh.

.devague/plans/coherent-public-face-and-fresh-ledgers.json

CHANGELOG.mdDocument the 0.24.1 documentation release +55/-0

Document the 0.24.1 documentation release

• Adds the 0.24.1 release entry covering the README rewrite, skill synchronization, contract documentation, regression tests, and fixes for issues #100 and #47. It also records the former contradictory text verbatim.

CHANGELOG.md

CLAUDE.mdReplace duplicated release history with a changelog pointer +1/-247

Replace duplicated release history with a changelog pointer

• Removes twelve obsolete status paragraphs, including statements contradicted by shipped behavior. Retains the current release status and directs historical readers to CHANGELOG.md.

CLAUDE.md

README.mdRewrite the public guide around the eight-leg workflow +186/-128

Rewrite the public guide around the eight-leg workflow

• Reorganizes the README into what, why, usage, and impact sections. Adds an eight-leg Mermaid flow, three human gates, verified terminal captures, ledger explanations, and an artifact ownership table.

README.md

2026-09-04-coherent-public-face-and-fresh-ledgers.mdAdd the completed delivery accountability report +103/-0

Add the completed delivery accountability report

• Records planned versus actual work, deviations, validation evidence, delivery claims, lapses, and remaining follow-ups for the documentation release.

docs/deliveries/2026-09-04-coherent-public-face-and-fresh-ledgers.md

2026-09-04-coherent-public-face-and-fresh-ledgers-split.mdAdd the workforce split plan +158/-0

Add the workforce split plan

• Documents four dependency waves, task ownership, model assignments, detailed acceptance criteria, and the expected end state for the nine-task implementation.

docs/plans/2026-09-04-coherent-public-face-and-fresh-ledgers-split.md

2026-09-04-coherent-public-face-and-fresh-ledgers.mdAdd the exported build plan +111/-0

Add the exported build plan

• Defines the nine documentation, testing, and release tasks with dependencies, coverage targets, acceptance criteria, and known follow-up risks.

docs/plans/2026-09-04-coherent-public-face-and-fresh-ledgers.md

2026-09-04-coherent-public-face-and-fresh-ledgers.mdAdd the coherent-public-face specification +146/-0

Add the coherent-public-face specification

• Captures the audience, requirements, boundaries, decisions, honesty conditions, scope exploration, and follow-ups behind the documentation-only release.

docs/specs/2026-09-04-coherent-public-face-and-fresh-ledgers.md

pyproject.tomlBump the package version to 0.24.1 +1/-1

Bump the package version to 0.24.1

• Advances the project version from 0.24.0 to 0.24.1 for the documentation release.

pyproject.toml

uv.lockSynchronize the locked package version +1/-1

Synchronize the locked package version

• Updates the editable devague package entry from 0.24.0 to 0.24.1.

uv.lock

[qodo-code-review]

Code Review by Qodo

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

1. Evidence command omits contract ✓ Resolved 🐞 Bug ≡ Correctness

Description

The documented devague evidence invocation omits the required --contract argument, so copying it
produces a user error instead of filing evidence. The CLI explicitly rejects evidence filings with
no contract text.

Code

docs/spec-contract.md[R849-851]

+Filed via `devague evidence --obligation oN --test "<ref>" --behavior
+"<text>" --type K --strength K --basis "<text>" --outcome pass|fail
+[--run-commit <sha> --run-timestamp <ts>] [--origin]`. A user-authored

Relevance

●●● Strong

Documented evidence command omits the CLI-required contract argument.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The new contract presents a complete filing syntax without --contract, while the CLI adds that
option to its missing-required-fields list and prints it in the remediation syntax.

docs/spec-contract.md[849-851]
devague/cli/_commands/evidence.py[112-135]

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 `devague evidence` invocation omits the required `--contract` option, making the documented command non-runnable.

## Issue Context
The evidence command requires test, behavior, contract, type, strength, basis, and outcome. Keep the optional origin syntax accurate as well.

## Fix Focus Areas
- docs/spec-contract.md[849-851]
- devague/cli/_commands/evidence.py[112-135]

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

---

2. Agent capture auto-confirms 🐞 Bug ≡ Correctness

Description

The agent-driven walkthrough omits --origin llm from capture, so the CLI defaults the
agent-filed claim to user origin and immediately confirms it. Following this example bypasses the
README's stated invariant that agent proposals remain proposed until a human confirms them.

Code

README.md[R126-127]

+$ devague capture --kind after_state "The reader remembers the chosen theme" --instruction "Reload and assert the theme is unchanged"
+captured c3 (after_state, confirmed)

Relevance

●●● Strong

Example defaults agent capture to user origin, falsely showing immediate confirmation instead of a
proposal.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The README establishes that the agent calls the CLI at every step and says only the human may
confirm agent proposals. However, capture defaults --origin to user, and Frame.add_claim
maps every non-LLM origin directly to confirmed; the skill explicitly requires agent proposals to
use LLM origin and remain proposed.

README.md[3-8]
README.md[49-50]
devague/cli/_commands/capture.py[38-48]
devague/frame.py[342-354]
.claude/skills/think/SKILL.md[203-211]

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 agent-driven README walkthrough files a claim without `--origin llm`, causing it to auto-confirm as user-authored and bypass human review.

## Issue Context
`capture` defaults to user origin, while the README says the agent drives the commands and must not confirm its own proposals. Update the command and expected output to show a proposed claim, followed by explicit human adjudication where appropriate.

## Fix Focus Areas
- README.md[126-133]

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

---

3. Delivery evidence names nonexistent test ✓ Resolved 🐞 Bug ◔ Observability

Description

The delivery claim cites tests/test_readme_commands.py::test_readme_commands_parse, but the newly
added module has no test with that name. This leaves the delivery ledger's evidence link
unresolvable and falsely implies that specific verification ran.

Code

docs/deliveries/2026-09-04-coherent-public-face-and-fresh-ledgers.md[R73-74]

+| `c2` — README.md replaces its stale three-stage arrow (README.md lines 10-12: idea, spec, plan, build) with an eight-leg pipeline diagram as a mermaid fence, and adds a numbered move walkthrough (01 scope ... 08 summarize-delivery) modeled on the site page's pipeline stages and method sections | `execution` | `tests/test_readme_commands.py` (run 2026-09-04) |
+| `c3` — README.md gains real, verified code examples: every command block is checked against the shipped 'devague --help' / 'devague plan --help' output, and one short verbatim terminal capture per engine (frame, plan, delivery ledger) shows actual output including the 'next:' stderr hint | `coverage` | `tests/test_readme_commands.py::test_readme_commands_parse` (run 2026-09-04) |

Relevance

●●● Strong

Delivery evidence references a nonexistent test, making the verification link unresolvable.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The cited node ID does not exist in the new test file: its command test is named
test_every_readme_bash_devague_line_matches_the_shipped_cli, and its console coverage only checks
version-comment headers.

docs/deliveries/2026-09-04-coherent-public-face-and-fresh-ledgers.md[73-74]
tests/test_readme_commands.py[148-172]
tests/test_readme_commands.py[222-236]

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 delivery summary references a nonexistent pytest node ID as evidence for the README command/capture claim.

## Issue Context
Replace it with the actual relevant test node IDs, and narrow the delivery claim if the tests do not verify all stated command blocks.

## Fix Focus Areas
- docs/deliveries/2026-09-04-coherent-public-face-and-fresh-ledgers.md[73-74]
- tests/test_readme_commands.py[148-172]
- tests/test_readme_commands.py[222-236]

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

---

4. Evidence validation is overstated ✓ Resolved 🐞 Bug ≡ Correctness

Description

The contract says behavior_text, contract_text, and strength_basis validate in
EvidenceRecord.__post_init__, but that method validates only enum-like fields. This misstates the
persisted-record validation guarantees; those text values are checked only by the CLI filing path.

Code

docs/spec-contract.md[R854-856]

+`--reject <eN>`. `behavior_text`/`contract_text`/`evidence_type`/`strength`/
+`strength_basis`/`outcome` all validate in `__post_init__`, unlike
+`LapseRecord.code` — they are structural vocabularies that do not retire.

Relevance

●●● Strong

Documentation attributes text validation to post-init although validation occurs only in the CLI
path.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The dataclass declaration and post-init implementation contain no validation for the three textual
fields named in the documentation, whereas the command handler performs presence validation during
filing.

docs/spec-contract.md[854-856]
devague/delivery.py[161-187]
devague/cli/_commands/evidence.py[112-128]

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 EvidenceRecord documentation incorrectly attributes text-field and strength-basis validation to `__post_init__`.

## Issue Context
`EvidenceRecord.__post_init__` validates evidence type, strength, outcome, origin, and status. The CLI checks presence of behavior, contract, and basis before filing.

## Fix Focus Areas
- docs/spec-contract.md[854-856]
- devague/delivery.py[161-187]
- devague/cli/_commands/evidence.py[112-128]

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

---

5. Origin option missing value ✓ Resolved 🐞 Bug ≡ Correctness

Description

The documented devague evidence syntax shows bare [--origin], but argparse requires that option
to be followed by user or llm. Copying the documented form causes a parser error instead of
filing evidence.

Code

docs/spec-contract.md[R849-852]

+Filed via `devague evidence --obligation oN --test "<ref>" --behavior
+"<text>" --type K --strength K --basis "<text>" --outcome pass|fail
+[--run-commit <sha> --run-timestamp <ts>] [--origin]`. A user-authored
+record auto-approves; an `llm`-authored one (`--origin llm`) lands

Relevance

●●● Strong

Documented bare option is invalid because argparse requires an origin value.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The evidence parser registers --origin with choices=ORIGINS and no boolean action, so argparse
requires a following value. The allowed origin vocabulary is user and llm.

devague/cli/_commands/evidence.py[271-288]
devague/frame.py[342-352]

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 evidence filing syntax presents `--origin` as a boolean flag even though it requires a value.

## Issue Context
Update the syntax to show the accepted values, consistently with the surrounding prose and actual argparse definition.

## Fix Focus Areas
- docs/spec-contract.md[849-853]

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

---

View medium (3)

6. Delta lineage target omitted ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new caused_by contract limits provenance to confirmed claims or approved deviations, while the
filing path explicitly accepts prior bN delta records. Consumers relying on this contract can
reject or fail to emit valid delta-to-delta lineage.

Code

docs/spec-contract.md[R867-870]

+- `caused_by` — list of refs pointing backwards at the confirmed claim or
+  approved deviation that caused the change; required at the filing path — a
+  delta with no cause is precisely the fabricated-delivery shape gate 3
+  hunts for.

Relevance

●●● Strong

Contract omits valid prior-delta causes accepted by the filing and lineage implementation.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

_validate_caused_by builds the existing-delta ID set and explicitly validates bN references
against it. The command's own comment states that causes may name claims, approved deviations, or
prior deltas, and the current-state projection traverses these delta lineage links.

devague/cli/_commands/delta.py[87-99]
devague/cli/_commands/delta.py[119-129]
devague/today.py[475-480]

Agent prompt

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

## Issue description
`DeltaRecord.caused_by` documentation omits existing delta records as a supported backward-provenance target.

## Issue Context
The CLI validates bare `bN` references against the current delivery ledger, and current-behavior projection uses those links for delta lineage. Add prior deltas to the documented target families.

## Fix Focus Areas
- docs/spec-contract.md[867-870]

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

---

7. Human interaction promise false ✓ Resolved 🐞 Bug ≡ Correctness

Description

README says humans approve only the spec, plan, and final PR and that nothing else waits on them,
but frame convergence requires human adjudication of agent proposals and /deviate explicitly halts
execution for approval. This materially understates the human involvement required by the documented
workflow.

Code

README.md[R9-10]

+- You approve three things: the spec, the plan before a workforce of agents
+  builds it, and the final pull request. Nothing else waits on you.

Relevance

●●● Strong

README contradicts documented human adjudication gates and materially misstates workflow behavior.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Convergence reports proposed spec-affecting claims as blockers, and the think skill reserves their
confirmation for the user. The deviate skill additionally requires the fan-out to halt until a human
approves a specific departure, directly contradicting “Nothing else waits on you.”

devague/convergence.py[99-110]
.claude/skills/think/SKILL.md[203-219]
.claude/skills/deviate/SKILL.md[46-67]
README.md[25-39]

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 above-the-fold interaction promise says nothing beyond three artifact approvals waits on the human, while proposal confirmation and mid-run deviations require additional human decisions.

## Issue Context
Distinguish the three standing gates from the individual adjudications and deviation approvals that can block progress within those gates.

## Fix Focus Areas
- README.md[9-10]
- README.md[49-50]

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

---

8. Plan pointer is tracked ⊘ Outdated 🐞 Bug ≡ Correctness

Description

README labels .devague/current_plan as a gitignored local pointer, but .gitignore excludes only
.devague/current and this PR itself commits an updated current_plan. Users following the
artifact table can unintentionally commit mutable active-plan state or receive repository changes
after ordinary plan operations.

Code

README.md[189]

+| `.devague/current`, `.devague/current_plan` | every frame/plan move (the current-frame and current-plan pointers) | gitignored — local pointers |

Relevance

●●● Strong

Artifact table inaccurately labels a rewritten, tracked plan pointer as gitignored.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The ignore file contains a rule only for the current-frame pointer, while PlanStore.save rewrites
.devague/current_plan on every plan save. A prior delivery document already records this exact
tracked-versus-documented inconsistency, and the PR updates the tracked pointer from one plan slug
to another.

.gitignore[220-232]
devague/plan_store.py[19-20]
devague/plan_store.py[35-48]
docs/deliveries/2026-07-28-issue-backlog-sweep.md[170-175]
.devague/current_plan[1-1]

Agent prompt

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

## Issue description
README incorrectly says `.devague/current_plan` is gitignored even though it is tracked and absent from `.gitignore`.

## Issue Context
Either accurately document its current tracked behavior or add an ignore/migration change if the intended contract is genuinely local-only. Keep the artifact table consistent with repository behavior.

## Fix Focus Areas
- README.md[184-190]
- .gitignore[226-232]

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

---

9. Reported grep result is impossible ✗ Dismissed 🐞 Bug ◔ Observability

Description

The plan records that a grep including docs/*.md returns no six-leg matches, but this same newly
added plan contains six-leg diagrams, which that command matches. The delivery summary repeats the
false zero-hit verification result, making the recorded verification unreliable.

Code

docs/plans/2026-09-04-coherent-public-face-and-fresh-ledgers.md[R103-105]

+  - git -C ../org status --short and git -C ../guildmaster status --short are both empty; git status in this repo lists changes only under README.md, CLAUDE.md, CHANGELOG.md, pyproject.toml, uv.lock, devague/`__init__.py`, docs/, tests/ and .claude/skills/
+  - grep -rn 'six-leg\|seven-leg\|still unimplemented\|ships separately' README.md CLAUDE.md docs/\*.md .claude/skills/\*/SKILL.md returns nothing
+  - markdownlint-cli2 on README.md, CLAUDE.md, CHANGELOG.md, docs/\*.md and each of the eight SKILL.md files by explicit path exits 0; uv run pytest -n auto exits 0; uv run flake8 --config=.flake8 devague/ tests/ exits 0

Relevance

●●● Strong

The claimed zero-hit grep result conflicts with a matching phrase in the documented plan or delivery
files.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The planned command explicitly searches docs/*.md for six-leg, while the new delivery document
itself contains that phrase in its planned-work section and the delivery evidence nevertheless
claims zero hits.

docs/plans/2026-09-04-coherent-public-face-and-fresh-ledgers.md[103-105]
docs/deliveries/2026-09-04-coherent-public-face-and-fresh-ledgers.md[18-26]
docs/deliveries/2026-09-04-coherent-public-face-and-fresh-ledgers.md[56-63]

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 recorded stale-text grep command includes all `docs/*.md`, but newly added historical delivery/plan material contains the searched phrases, so the claimed zero-hit result cannot be true.

## Issue Context
Scope the check to intended live documentation or explicitly exclude archival delivery/spec/plan documents, then update the plan and delivery evidence with the real command/result.

## Fix Focus Areas
- docs/plans/2026-09-04-coherent-public-face-and-fresh-ledgers.md[103-105]
- docs/deliveries/2026-09-04-coherent-public-face-and-fresh-ledgers.md[56-63]
- docs/deliveries/2026-09-04-coherent-public-face-and-fresh-ledgers.md[18-26]

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

---

Context sources

✅ Compliance rules (platform): 105 rules

✅ Skills: cicd, communicate

Review mode: ⏭️ Skipped: The push only updates documentation and delivery/provenance ledger artifacts, with no runtime, configuration, schema, or test behavior changes.

Tip of the day

💡 Did you know, you can route each action level your way: inline, summary, both, or drop

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[OriNachum]

/agentic_review

[qodo-code-review]

Code review by qodo was updated up to the latest commit 8b6abf4

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[OriNachum]

/agentic_review

[qodo-code-review]

Code review by qodo was updated up to the latest commit 3c25322