fix(han-planning): close the six gaps feedback issue #193 reported - #208
Merged
Conversation
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
marked this pull request as ready for review
September 9, 2026 20:23
This was referenced Sep 9, 2026
Draft
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #193.
Feedback issue #193 reported six problems from a real
plan-implementationrun. Four were the same shape: a mechanicwritten 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 andthe 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 thatgrant 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.shresolves the links in both directions, and a sharedsynthesis-failure-rule.mdstopseither 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
docs/plans/, the new check found the reported defect class insix of them. Two were spot-verified as real: one plan cites
[D10]against a log that stops atD-8, and anotherreferences a "Phase 2" section that does not exist.
SKILL.mdfiles 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.