pd-m4: teach progressive disclosure the convention kind#152
Merged
Conversation
… mover, prepend add-path Design pass for progressive-disclosure milestone 4 (CONVENTIONS). The M3 mover refuses the convention kind; the spec had assumed conventions accrete as `### ` entries under a `## Recent` staging zone, but the real CONVENTIONS.md is 18 stable, curated `## ` sections. Resolved: - Curated-taxonomy model: fold the `## ` sections into a handful of theme files; the root keeps `## Themes` gists. Conventions are not an accreting stream. - Unify into the entry-kind path (Approach A): all three kinds share preamble | staging | `## Themes`, parametrized by a per-kind entry prefix (`## [` vs `## `) and identity (timestamp vs section title). Retire parseConvention, ConventionLinePrefix, HeadingRecent (## Recent). - Dumb line-scanner, no fence detection (a rabbit hole in a destructive parser); byte-conservation + the human-gated plan review keep it safe. Fail loud on duplicate `## ` titles (ErrDuplicateStagedTitle). - Convention add-path prepends above `## Themes` (was AppendAtEnd), correcting the original inconsistency — decisions/learnings already prepend. This deliberately relaxes the spec's "no add-path change" non-goal. Revises specs/progressive-disclosure.md (layout, invariants, tests, acceptance, non-goals, phasing) and records the decision in DECISIONS.md. Implementation follows via /ctx-task-out --milestone pd-m4. Spec: specs/progressive-disclosure.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
Progressive-disclosure milestone 4: teach the mover to digest CONVENTIONS.md, whose entries are curated `## ` sections rather than timestamped `## [` entries. Unifies the two parse paths into one, prefix-parametrized on the per-kind entry marker. Core (internal/disclosure): - EntryPrefix(Kind): `## [` for learning/decision, `## ` for convention. - One parse path (parseRegions); parseConvention deleted, Reconstruct de-branched. Convention staging enumerates `## ` sections by title identity (no timestamp), skipping the structural `## Themes` and HTML-comment examples with a deliberately dumb line scanner. - Validate generalized to the per-kind prefix; new dup-title fail-loud (ErrDuplicateStagedTitle) since a convention's title is its whole identity. Retires ConventionLinePrefix / HeadingRecent (`## Recent`). - Apply digests conventions end-to-end (append→verify→remove, one root rewrite); the refusal was derived from ThemeDir, so an explicit gate guarded it until the parse/validate paths landed. Add-path (ctx convention add): - `--section` is now REQUIRED for conventions and rejects placeholder values (TBD, n/a, …): a default section is a catch-all an undecided caller dumps everything into. A bullet lands at the top of its H2 section, which keeps it enumerable and above `## Themes`. - `--section Themes` declares a theme on all three canonical kinds: content is `<name> — <gist>`, and it writes both the gist bullet and the theme file, so the gist↔file pairing invariant holds at once. - Shared build.RequiredBodyFlags exempts theme adds from the per-kind body-flag gate; ordinary adds still require their fields. Skill + real rollout: - ctx-digest skill gains the convention path, the dup-title guard, and a fix to the plan-JSON example (entries are objects, not strings — the documented string form failed json.Unmarshal since M3). Copilot synced. - Real .context/CONVENTIONS.md folded: 18 sections → 5 themes (code-style, layout, workflow, docs, cli), root 390 → 22 lines. Conservation, invariants, and byte-exact preamble verified. Bundled (jumbo commit, human-approved — spans specs, primary trailer below; secondary specs cited inline for traceability): - build(tooling): exact-pin zensical in the manifest; `make site` gates on it via `check-tools.sh --only zensical --strict`, catching drift in BOTH directions (behind = regression, ahead = unreviewed). Pin and installer read one source of truth. (Spec: specs/check-tools.md) - build(site): rebuild docs with zensical 0.0.51 and fix a dead blog link fragment (#step-5-reindex-after-manual-edits → #step-5-project-a-table-of-contents-on-demand). `make site` had been silently regenerating every page with whatever generator was on PATH. - docs: scrub a sibling-project design detail that leaked into the pd-m4 plan; describe the design on ctx's own merits. (Spec: specs/public-repo-hygiene.md) - test: temp-repo tests set local commit.gpgsign=false so `go test` never reaches for the GPG agent and hangs the terminal. Spec: specs/progressive-disclosure.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
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
1 participant
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.
Summary
Progressive-disclosure milestone 4 teaches the mover to digest
CONVENTIONS.md, whose entries are curated##sections rather thanthe timestamped
## [entries of LEARNINGS/DECISIONS. The two parsepaths collapse into one, parametrized on a per-kind entry prefix, and the
real
.context/CONVENTIONS.mdis folded from 390 lines into a 22-lineroot plus five theme files. Bundled alongside (human-approved jumbo): a
make siteversion gate that stops silent generator drift, and twosupporting fixes.
Changes
internal/disclosure):EntryPrefix(Kind)parametrizes one parse path (
parseRegions);parseConventiondeletedand
Reconstructde-branched. Staging enumerates##sections bytitle identity (no timestamp), skipping the structural
## ThemesandHTML-comment examples via a deliberately dumb line scanner.
Validategeneralized to the per-kind prefix with a new dup-title fail-loud
(
ErrDuplicateStagedTitle);Applydigests conventions end-to-end.Retires
ConventionLinePrefix/HeadingRecent. — servesspecs/progressive-disclosure.mdctx convention add):--sectionis now required andrejects placeholder values (a catch-all section is where an undecided
caller dumps everything); a bullet lands at the top of its H2 section,
keeping it enumerable and above
## Themes.--section Themesdeclaresa theme on all three canonical kinds — writes both the gist bullet and
the theme file so the gist↔file pairing invariant holds at once. —
serves
specs/progressive-disclosure.mdctx-digestgains the convention path, thedup-title guard, and a fix to its plan-JSON example (entries are
objects, not strings — the documented string form had failed
json.Unmarshalsince M3); Copilot skills synced. Real.context/CONVENTIONS.mdfolded into 5 themes (code-style, layout,workflow, docs, cli). — serves
specs/progressive-disclosure.mdmake siterefuses to build unless the local generator matches, viacheck-tools.sh --only zensical --strict, catching drift in bothdirections (behind = silent regression, ahead = unreviewed rebuild).
Pin and installer read one source of truth. — serves
specs/check-tools.mdblog link fragment corrected; a sibling-project design detail that
leaked into the pd-m4 plan scrubbed to describe the design on ctx's own
merits (serves
specs/public-repo-hygiene.md); temp-repo tests setlocal
commit.gpgsign=falsesogo testnever reaches for the GPGagent.
Specs
specs/progressive-disclosure.md— the bounded-root model thismilestone extends to the convention kind (design commit + implementation)
specs/check-tools.md— the tooling-manifest checker themake siteversion gate builds on
specs/public-repo-hygiene.md— the public-tree rule the plan-filescrub restores
Closed tasks
[E1]Config + vocabulary:EntryPrefix(Kind), retireConventionLinePrefix/HeadingRecent,ErrDuplicateStagedTitle,ThemeDir(convention)[E2]Parser unification: convention##-enumerator, prefix-parametrizedparse path,
parseConventiondeleted, kind-aware inspect,SplitStaging[E3]Validate: per-kind entry-below-themes, dup-title fail-loud,rule-3 via the enumerator
[E4]Mover: lift the convention refusal,Applyend-to-end,title-only identity through the plan
[E5]Add-path: section-targeted convention add + post-fold invariant[E6]ctx-digestskill — convention path + Copilot sync[E7]Measurement gate on a realistic fixture; human-gated realrollout; milestone gate
[E3]:ctx-digestapply-path skill +Copilot sync + measurement gate)
All 22 tasks in
specs/plans/pd-m4.mdare[x].Verification
make lint0 issues,go test ./...green,make auditpass.18 sections → 5 themes; byte-conservation (every section span present
in exactly one theme file, none missing/duplicated/leaked), preamble
byte-exact, bounded root, no broken theme links. Empty-plan re-apply is
a byte-exact no-op.
fixture: mis-grouped as documented, bytes conserved.