golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
5,960 Commits 1 Branch 0 Tags
12ee75a509cbfd8fe2ae2871056fa81777d7dcf5
Commit Graph

4 Commits

Author SHA1 Message Date
Jakub Zych
a9a7a328e6 refactor: hard-fork GSD -> MSD (Make Software Done) 
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD
across contents and paths, upstream package/repo coordinates -> @golem15/msd-core
and golem15com/msd-core. Deep links into upstream history, sibling upstream
packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is.

Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line,
package/plugin identity, regenerated lockfile, install-tree fixtures, derived
registries and benchmark baseline; migration checksum baseline re-locked
(MSD keeps its own install state, so no install had applied the old sums);
sort-order and regex-escaped expectations in tests adjusted.
 2026-10-06 01:47:40 +02:00
Tom Boucher
d7b5b2c2b6 fix(#4906): migrate the ROADMAP.md Plans: line onto the PlanningDoc seam — Phase 2 (#4933) 
* feat(#4906): migrate the ROADMAP.md **Plans:** line onto the PlanningDoc seam

Phase 2 of epic #4906. Migrates the two writers of ROADMAP.md's Plans field onto
the seam ADR-4910 locks, and deletes both bespoke regexes per Decision 2 — a
correct copy of a rule the seam now owns is the same divergence risk as an
incorrect one.

src/phase.cts's mutateMilestonePhase carried planCountBodyPattern, one capture
group, replace-to-end-of-line: this is #4852, still live before this change.
src/roadmap.cts's cmdRoadmapUpdatePlanProgress carried the correct three-arm
sibling (the #2853/#3584 correction) that phase.cts never adopted. Both now call
findField/setFieldValue/serialize against a PlanningDoc parsed from the same
milestone/phase-confined substring their existing withPhaseSection /
replaceInCurrentMilestone wrappers already compute — those confinement
wrappers are unchanged, only the field-write mechanism inside them moved.

Verified end-to-end through the real commands against real fixtures, not
against an isolated reimplementation of the classification logic:
cmdRoadmapUpdatePlanProgress and cmdPhaseComplete both preserve a trailing
human annotation across a real count rewrite, and both leave a bracketed
human annotation (the #3584 Finding A discriminator) untouched.

Found and fixed inline, in the already-merged src/planning-document.cts,
rather than deferred: BOLD_FIELD_RE recognized only **Label:** (colon inside
the closing bold). gsd-core/templates/roadmap.md ships every field, Plans
included, as **Label**: (colon outside) -- migrating roadmap.cts onto the
seam as it stood would have silently regressed real generated ROADMAP.md
files back to the bug this migration exists to remove. Widened to recognize
both spellings; deliberately NOT widened to a bare unbolded Label: form,
which would register ordinary prose as a spurious field.

roadmap.cts's writer also recognizes a bare singular/plural count (1 plan /
3 plans, no fraction) as an existing count token to overwrite, not template-
placeholder or freeform prose -- the template's own single-plan-phase shape
and #3584 Finding B's fix. Preserved exactly; this shape is easy to drop by
only porting the more common fraction form.

Two of Phase 2's three originally-cited defects turned out to be already
fixed on next, independent of this epic, and are struck via a dated ADR
amendment rather than silently narrowed: #4862 (stateReplaceField's own
anchoring hardening already preserves sibling fields) and #4499
(spliceFrontmatter's per-key preservation already keeps block sequences
byte-identical). Both reproduced against the built module before being
struck, not assumed. STATE.md's field-write engine is re-scoped out of this
phase entirely -- not because of its get_impact rating alone (measured the
same way, the two sites THIS phase keeps are also CRITICAL, and an earlier
draft of the amendment claimed otherwise without checking; corrected) but
because updateCore is a multi-field transaction with frontmatter sync and
preservation reconciliation that does not map onto PlanningDoc's node model,
where migrating it would mean designing that model, not calling an existing
seam function.

Refs #4852
Refs #4906

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(#4906): preserve a trailing annotation with no em-dash separator

Test authoring surfaced a real regression against an existing #3584 fixture:
`**Plans**: 0/1 plans executed (11-16 are gap closure from VERIFICATION)` -- a
parenthetical annotation glued on with a bare space, no em-dash -- was left
completely untouched by the migrated code instead of being rewritten with the
count updated and the parenthetical preserved.

Root cause: planning-document.cts's parseBoldFieldLine splits a field's value
from its trailing annotation only on the literal " -- " separator. An
em-dash-separated annotation already lives outside `value` in `trailingSpan`,
untouched by setFieldValue regardless -- that path was never broken. A
parenthetical with no em-dash has nowhere to go but inside `value`, and the
migrated classification required the WHOLE value to match a count-token shape
exactly, so this case fell into "leave untouched."

Fixed in the migrated call sites, not in the seam: prefix-match the count
token against the field's current value, then re-glue whatever textual suffix
follows WITHIN that value onto the new count text before writing. Correct for
both shapes with no special-casing -- the em-dash case's suffix-within-value
is empty by construction (the annotation already lives outside value), the
parenthetical case's suffix is exactly the glued content, preserved verbatim.

Deliberately not fixed by widening planning-document.cts's separator grammar
to also recognize a bare-space-then-parenthesis: that seam is already-merged
and already-tested, and guessing at an open-ended set of annotation shapes at
the seam level is exactly what isTemplatePlaceholder already avoids by
staying caller-side. "What counts as a Plans-field count token" is domain
knowledge about this one field.

phase.cts's writePlansField had no arm-2/arm-3 classification before this
migration -- its original regex unconditionally overwrote whatever value was
present. That unconditional-overwrite behavior is preserved exactly for
values with no recognizable count-token prefix; only the recognized-count
case gained suffix preservation, matching what phase.cts actually did before.

Verified end-to-end via the real cmdRoadmapUpdatePlanProgress and
cmdPhaseComplete commands against real fixtures for both the parenthetical
and em-dash shapes at both sites.

Refs #4906

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* test(#4906): cover the migrated Plans-line writers at both sites

15 cases across tests/phase.test.cjs and tests/roadmap.test.cjs, one per row
of the phase test matrix, extending the existing describe blocks and helper
functions those files already use for these two commands rather than
building parallel fixtures.

Covers: trailing-prose preservation on a real count rewrite at both sites
(the #4852 regression, and the #2853/#3584 non-regression); zero-trailing-
content boundary; the bracketed-template-placeholder vs bracketed-human-
annotation discriminator (#3584 Finding A); a missing Plans field not
crashing either command; an unrelated unreadable sibling node in the same
confined section surfacing rather than corrupting the field; confinement
holding across sibling phases and milestones; a round trip through the
command's own read path; CRLF safety; and a parity assertion that both sites
now produce identical Plans-line text for identical inputs, proving one
shared mechanism rather than source-grepping for the deleted regex literals.

Authoring caught a real regression before it could land silently: an
existing #3584 fixture using a parenthetical annotation with no em-dash
separator failed against the first version of the migration. Reported rather
than edited to match the broken behavior -- see the paired fix commit. That
existing test needed no changes once the fix landed; its assertion was
verified independently against the real CLI before this commit.

Refs #4906

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(#4906): give phase.cts's Plans writer the same arm-2/arm-3 classification as roadmap.cts

Isolated adversarial review (mandatory orthogonal review pass) executed
writePlansField against `[Deferred pending re-scope]` and the fresh-template
placeholder wording and found the first version of this migration kept
phase.cts's OLD unconditional-overwrite behavior for the no-count-prefix
case instead of adopting the same isTemplatePlaceholder / arm-3-untouched
classification roadmap.cts's sibling site already uses. A bracketed human
annotation was being silently rewritten to a new count -- a real
content-destroying regression against this phase's own design-doc behavior
table, not an accepted trade-off, and exactly the kind of divergence between
the two sites Decision 2's parity requirement exists to eliminate.

writePlansField now runs the same template-placeholder check and "no count
prefix and not a placeholder => leave untouched" branch before ever calling
setFieldValue. Added two site-1 tests (rows 4 and 6 of the phase test
matrix) mirroring the existing site-2 coverage for this exact discriminator.

Refs #4906

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(#4906): restore plain (non-bold) Plans: line support and fix a test helper mismatch

gsd-test (mandatory verification, run before every push) surfaced two real
defects the migration's manual CLI checks had not caught:

1. #1163 regression: a hand-edited/pre-template ROADMAP.md can carry a PLAIN
   (non-bold) `Plans:` line rather than the canonical `**Plans**:`/
   `**Plans:**` bold field. The old deleted regexes tolerated this shape;
   the seam's BOLD_FIELD_RE is deliberately bold-only (widening it would
   register ordinary prose like "Note: see below" as a spurious field
   seam-wide), so the migrated writers silently no-op'd on it instead of
   updating the count -- a real, previously-tested behavior lost.

   Fixed with a caller-side fallback in both src/roadmap.cts (where the
   failing #1163 test lives) and src/phase.cts (added for parity, per
   Decision 2 -- the two sites should not diverge on which legacy shapes
   they tolerate): when findField finds no boldField Plans node, look for a
   plain `Plans:` line directly and apply the same arm-1/2/3 classification
   against it. This is domain knowledge about one field's legacy tolerated
   shape, the same class of thing isTemplatePlaceholder already keeps
   caller-side rather than seam grammar.

2. tests/roadmap.test.cjs's new rows 4/5 (site 2) seeded the colon-outside
   spelling (`**Plans**: ...`) but their plansLineIn() helper only matched
   colon-inside (`**Plans:**`), so both assertions compared against
   `undefined` regardless of whether the write logic was correct -- a
   test-authoring bug, not a source defect. Fixed the helper to recognize
   both BOLD_FIELD_RE spellings, matching what the production code actually
   supports.

Verified via a real gsd-test run before this fix (outcome: failed, 5
failures, all in tests/roadmap.test.cjs) and will be re-verified via a real
gsd-test run on this commit before push, per this repo's non-rationalization
rule: a red gate is fixed, never explained away.

Refs #4906

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* chore(#4906): backfill the Phase 2 changeset fragment's PR number

pr:0 -> pr:4933, now that gh api POST /pulls has returned the real number.

Refs #4906

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

---------

Co-authored-by: sim <sim@local>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
 2026-09-23 19:25:39 -04:00
Tom Boucher
fac0e9de86 docs(#4906): ADR-4910 amendment — a write refuses on a document with any unreadable node (#4913) 
* docs(#4906): ADR-4910 amendment — a write refuses on a document with any unreadable node

§5 scoped the parse error to the node. That is correct for reads and was never
examined for writes.

§5 was reasoned entirely from #4899, a read bug. Node-scoping is right there: a
ragged Progress table must not make phase list and init.progress fail, because
those are the commands a user needs to see what to repair. But the rule was
stated unqualified, and it licensed something never considered — phase.complete
mutating a ROADMAP.md whose Progress table it could not read. A partial-view
write persists a wrong answer rather than merely returning one.

Amendment: reads stay node-scoped; a write refuses when ANY node in the document
carries a parse error, whether or not the mutation targets it. A reader answers a
bounded question from a bounded region; a writer asserts that the document it
emits is the document it read, and cannot make that assertion about a region it
could not parse. §3's byte-stability does not rescue it — splicing untouched
bytes faithfully is not the same as knowing they were consistent with the change.

Rejected: refusing only when the mutation's own target node is unreadable. It is
the appealing middle and it does not hold — phase.complete writes **Plans:**
while deriving that value from plan/summary counts in a different region. The
regions a write depends on are not statically the regions it touches.

Downstream: Phase 1 ships both scopes plus a hasUnreadableNodes predicate the
serializer consults; Phase 2 gains a new acceptance criterion (a refused write
leaves the file byte-identical on disk); Phase 4's census gains a second axis and
must publish both counts.

Appended as a dated section per docs/contributor-standards.md pattern 1 — the
original Decision body is unchanged.

Refs #4906
Refs #4910

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(#4906): correct the amendment's motivating example and state the limit it exposes

An isolated review pass falsified the first draft's central example. The
correction is recorded in the amendment rather than quietly patched, because it
bounds what the rule can promise.

- The draft claimed phase.complete derives the value it writes into **Plans:**
  from a different REGION of the same document. It does not. planCount and
  summaryCount come from findPhaseInternal at src/phase.cts:3429-3434 — a
  filesystem scan of the phase directory. No PlanningDoc node holds them.
  That widens the dependency rather than narrowing it, and it makes an explicit
  limit necessary: a document-scoped write refusal protects the document's own
  consistency and says nothing about the correctness of a value sourced from
  outside the document. Recorded as a stated limit and named out of scope for
  this epic.

- The rejected alternative (refuse only when the mutation's own target node is
  unreadable) is re-grounded on two arguments that survive: it would almost
  never fire, since a verb locates the node in order to write it; and it guards
  something smaller than the operation performs, because serialization re-emits
  the whole file.

- §5's body names `phase list` as a consumer an unreadable Progress table would
  block. It is not one — cmdPhasesList (src/phase.cts:207) enumerates phases/
  and never opens ROADMAP.md. init.progress and roadmap.analyze are the real
  instances; the argument never needed three. §5's body left unmodified per the
  append-only rule, correction carried in the amendment, fold in at ratification.

- Clarified that the new WriteOutcome refusal sits on a different axis from §5's
  reserved document-level Result<PlanningDoc> parse failure, so no reader can
  conclude that reservation was reopened. A document can be valid to open and
  still refuse to be written.

Refs #4906
Refs #4910

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: sim <sim@local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
 2026-09-21 00:17:10 -04:00
Tom Boucher
01dbda9c49 docs(#4910): ADR-4910 — the PlanningDoc parse → mutate → serialize seam — Phase 0 of #4906 (#4911) 
* docs(#4910): ADR-4910 — the PlanningDoc parse → mutate → serialize seam — Phase 0 of #4906

Design lock for epic #4906. Docs-only; no production code lands here.

Eight decisions: one PlanningDoc seam composing markdown-sectionizer,
markdown-table and frontmatter as layers; node-replacement writes so a field
write cannot reach past its own value; byte-stable serialization for untouched
regions; escape-or-refuse shared between each artifact's writer and its reader,
with an explicit accepted-superset-of-emittable split; a typed parse error
scoped to the node rather than the document; a type-narrowed write boundary
paired with a lint; a positive control per accepted grammar; and one
implementation per shared pattern.

Two corrections to the epic's stated mechanism, both load-bearing for later
phases:

- The epic asks for a ratchet where a reintroduced content.replace() "does not
  typecheck". It cannot: fs.writeFileSync(p, s.replace(...)) typechecks fine
  because fs has never heard of PlanningDoc. Enforcement is type-narrowing plus
  a lint that owns the bypass, and the ADR says so rather than shipping a
  guarantee one require() defeats.
- The epic names scripts/lint-planning-artifact-writer-drift.cjs as the drain
  point. That script is a registry-completeness guard that states "No ratchet /
  no baseline" by design and never inspects how a write is performed. It is
  correct on its own axis and left untouched; the right home is
  local/no-adhoc-markdown-parsing.

ADR-2143's Phase 4 already shipped the table-regex and replace-mutation
detectors, so the ADR scopes the remaining gap precisely rather than asking for
that work twice: adhocReplaceMutation keys on a table-or-section regex, and
#4852's pattern is a bold-label field regex — which is why the defect sits in
src/phase.cts, a file the rule does lint, with lint:ci green.

Per docs/adr/README.md lifecycle rule 3, ADR-1372 and ADR-2143 are NOT given
the reciprocal `Subsumed by` back-link here: a Proposed ADR's Subsumes claim is
prospective, so its targets are not marked until ratification. Both back-links
land in the Phase 6 ratification PR. ADR index regenerated.

Refs #4906
Closes #4910

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(#4910): apply review findings — link every ADR cross-reference and state the node-scoping interpretation

Three review passes ran against the ADR: an isolated adversarial fact-check of
every citation, and both axes of /code-review as separate sub-agents.

Standards axis (hard violation of docs/adr/README.md lifecycle rule 2): 14 bare
ADR-1372 / ADR-2143 / ADR-1411 references in body prose. gen-adr-index.cjs does
not catch this — its bare-id check runs only over relation-field values, never
body prose — so a green lint:generated-sync did not clear it. Every bare
cross-reference is now a file link; only the self-reference ADR-4910 remains
bare, which is not a cross-reference.

Spec axis: §5 scopes the parse error to the node, while #4906's criterion reads
"an unparseable shape surfaces could-not-parse with the offending span" with no
document-or-node qualifier. Both readings are faithful to that sentence and they
produce materially different Phase 1 and Phase 4 work. §5 now records the
distributive reading explicitly, names the document-scoped alternative, states
what it would cost (one bad table failing phase list and init.progress alongside
roadmap.analyze), and names what changes if the epic meant the other one. A
silent narrowing became a stated one.

Refs #4906
Closes #4910

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(#4910): make each phase's acceptance a structural property, not a list of fixed issues

Phases 2-5 read as "fixes #4852, #4862, #4499" — a point-fix list with a seam
attached. That is the failure the epic names in its own words: "an
implementation that does that has not closed this epic, even with every symptom
gone and CI green."

New section "What makes a phase done" locks three criteria every phase carries:

- Census -> zero. A phase enumerates every instance of its anti-pattern in the
  tree, publishes the count in its PR, and closes when it is zero. Not "the
  reported ones".
- Deletion, not coexistence. Bespoke implementations are removed, not kept in
  sync beside the seam — including src/roadmap.cts:1196's three-arm
  planCountPattern, which is correct today and still goes, because a correct
  copy of a rule the seam owns is the two-copies-that-agree case.
- Unrepresentable by construction. Each phase ships one property that makes its
  class impossible rather than currently absent: a property over generated
  documents, a type that does not admit the wrong shape, or a drift guard.

The absorbed issues are demoted to fail-first regression evidence. A phase may
not close on those tests alone.

Each phase restated accordingly, with its own census / deletion /
unrepresentable / evidence breakdown.

The six community point-fix PRs and their issues were closed unmerged
(#4762/#4736, #4897/#4837, #4848/#4661, #4610/#4605, #4609/#4606,
#4530/#4499). The ADR now records that as executed rather than pending, which
is what lets census-to-zero be an acceptance criterion at all — a landed point
fix would make the tree look healthier than it is. Phase PRs reference those
six with Refs, since CONTRIBUTING forbids a closing keyword against an
already-closed issue.

Refs #4906
Closes #4910

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: sim <sim@local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
 2026-09-20 23:47:33 -04:00