Skip to content

fix(han-planning): close the six gaps feedback issue #193 reported - #208

Merged
mxriverlynn merged 3 commits into
v5.5.0-betafrom
gh-193-plan-implementation
Sep 9, 2026
Merged

fix(han-planning): close the six gaps feedback issue #193 reported#208
mxriverlynn merged 3 commits into
v5.5.0-betafrom
gh-193-plan-implementation

Conversation

@mxriverlynn

Copy link
Copy Markdown
Collaborator

Closes #193.

Feedback issue #193 reported six problems from a real plan-implementation run. Four were the same shape: a mechanic
written in one file that the file which must honor it never read back. Each now has a named reader, and the one whose
failure is mechanical has a script.

The plan behind this change is in docs/plans/plan-implementation-feedback-issue-193/, with the discovery findings and
the decision log beside it.

One premise in the issue turned out to be wrong

The issue says the orchestrating thread "does have execution tools." It does not. All three planning skills grant
find, git, mkdir, cp, and one config script, with no general shell. So the measurement step works inside that
grant and records what the grant cannot reach, rather than passing a specification's assertion through as fact. The
permission grant is unchanged, and widening it is deferred with a trigger.

What changed

The synthesis boundary is guarded on both sides. The plan is written first, so both companion files write backward
into a file that exists and a mid-run termination leaves the primary artifact rather than losing it. A new
check-plan-cross-references.sh resolves the links in both directions, and a shared synthesis-failure-rule.md stops
either file-writing caller from running the readability pass against a plan that was never written.

A citation names the field, not the entry. A decision entry carries the committed option and the declined ones as
sibling fields, and a bare identifier does not say which one a figure came from. Alongside it, two findings citing the
same identifier with different figures no longer merge, because a genuine disagreement usually cites different
evidence.

The readability editor reports what it wrote. It names each sentence it inserted with the source span it drew from,
and its ledger stops asserting that everything survived — an unfalsifiable claim that had already reported a figure the
source never held.

All four consuming skills had their branches rewritten, not only extended. Each tested for the exact sentence the
narrowed ledger removes, so adding a fourth branch and leaving the first three would have sent every clean run down the
path meaning "no usable report came back." The review round caught this; it is the defect the change exists to fix,
reproduced inside the fix.

The deferral list got two readers, one during the run and one at build time, where the reported run's deferred flag
actually got built.

Four in-area defects the discovery round found

Two instruction sentences split across a file boundary, ten link labels a directory too shallow, a stale round cap
contradicting the two files that own it, and a section required by an invariant but missing from the write order beside
it. Both split sentences came from commits that moved body text under the 500-line ceiling, so the rule that would have
prevented them now sits beside that ceiling.

Verification

  • 23 new Bats tests for the script; 118 tests pass repo-wide; lint clean.
  • Run against the fourteen existing plan folders under docs/plans/, the new check found the reported defect class in
    six of them. Two were spot-verified as real: one plan cites [D10] against a log that stops at D-8, and another
    references a "Phase 2" section that does not exist.
  • All four SKILL.md files remain under the 500-line ceiling.

Open, and deliberately not in this change

Five dispatch points still consume a returned report with no failure branch. The Step 4 specialist fan-out is the one
worth attention: a dead agent's absence is indistinguishable from a clean report with no findings, and a round that
silently lost one of three specialists produces a plan that reads complete and is missing a domain.

Units 7 and 8 change a report shape across a plugin boundary and must ship together, so the version bump is a release
decision rather than a code one.

Issue #193 reported six problems from a real plan-implementation run. Four
are the same shape: a mechanic is written in one file and the file that must
honor it never reads it back.

One premise in the work item is wrong and it changed the fix. The issue says
the orchestrating thread has execution tools; all three planning skills grant
only find, git, mkdir, cp, and one config script. The measurement step works
inside that grant and records what the grant cannot reach.

Discovery ran structural and behavioral analysis over the area, then a review
round of three specialists over the draft. That round found a critical defect
in the plan itself: narrowing the editor's ledger while leaving four skills
testing for the removed sentence would have sent every clean run down the
degraded branch. Nine findings changed the plan.
Four of the six were the same shape: a mechanic written in one file that the
file which must honor it never read back. Each now has a named reader, and the
one whose failure is mechanical has a script.

Synthesis writes the plan first, so both companion files write backward into a
file that exists and a mid-run death leaves the primary artifact. A new
check-plan-cross-references.sh resolves the links in both directions, and a
shared synthesis-failure-rule.md stops either file-writing caller from running
the readability pass against a plan that was never written.

Specialists now cite a decision's field rather than the whole entry, and two
findings citing one identifier with different figures no longer merge, since a
genuine disagreement usually cites different evidence.

The readability editor reports what it inserted with the source span it drew
from, and its ledger stops asserting that everything survived. All four
consuming skills had their branches rewritten, not only extended: each tested
for the sentence the narrowed ledger removes, so leaving them would have sent
every clean run down the degraded path.

Discovery measures the figures its tools reach and records what they cannot,
rather than passing a spec assertion through as fact. The premise that the
orchestrator can run arbitrary commands was wrong; it holds find, git, glob and
grep, and the permission grant is unchanged.

Also repairs four in-area defects the discovery round found: two instruction
sentences split across a file boundary, ten link labels a directory too
shallow, a stale round cap, and a section missing from the write order that
required it. The rule that would have prevented the split sentences now sits
beside the ceiling that caused them.

Run against the fourteen existing plan folders, the new check found the
reported defect class in six of them.
Audit the entities this branch touched and fix five discrepancies between
documentation and its source of truth.

- CLAUDE.md: record synthesis-failure-rule.md, the new han-planning-owned
  reference file two skills cite, in both the repository layout and the
  shared planning conventions doc map.
- readability-editor long-form doc: document the Insertions ledger the agent
  now returns, and correct the fact-preservation bullet, which described a
  blanket survival claim the agent explicitly no longer makes.
- docs/sizing.md: add ddd-analysis, which binds $size and reads
  default-swarm-size but appeared in none of the three sizing-aware lists.
  Qualify the "default is small" claim, which ddd-analysis contradicts by
  defaulting to medium.
- architectural-analysis: add the missing reverse boundary to ddd-analysis,
  in both the frontmatter description and the long-form doc, plus the
  pairing link. ddd-analysis names architectural-analysis three times as
  its alternative and nothing pointed back.

Claude-Session: https://claude.ai/code/session_01HtgjM85z795Cd8oNC8J7do
@mxriverlynn
mxriverlynn marked this pull request as ready for review September 9, 2026 20:23
@mxriverlynn
mxriverlynn merged commit d714ecc into v5.5.0-beta Sep 9, 2026
2 checks passed
@mxriverlynn
mxriverlynn deleted the gh-193-plan-implementation branch September 9, 2026 20:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant