pd-m5: suggest-only triggers for progressive disclosure#153
Merged
Conversation
Session knowledge residue from the merged pd-m4 (CONVENTIONS digestion) work, landed as the first commit of the M5 branch. Learnings: - A guard derived from a capability accessor silently lifts when the accessor is extended (T04 opening the mover before T13). - Skill/doc examples of a serialized structure must round-trip through the real parser (the latent ctx-digest plan-JSON bug). - Using the proprietary sibling repo as design evidence leaks its internals into tracked files. Decisions: - ctx convention add requires --section; no default; placeholders rejected (strict). - Theme declaration via the Themes section keyword, on all three canonical kinds. Task: - M5: suggest-only trigger wiring for progressive disclosure. Spec: specs/progressive-disclosure.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
Formalizes phase 5 of progressive disclosure (the suggest-only triggers) into specs/progressive-disclosure.md, resolving the nudge-threshold TBD the pd-m4 plan flagged as blocking. One knowledge.Health(ctxDir, thresholds) function feeds all three surfaces (the check-knowledge hook, /ctx-remember, /ctx-wrap-up), so the Go hook and the prose skills cannot drift. It emits two signal kinds, because "should I fold?" and "is this too heavy to be useful context?" are different questions: - Foldable root (a COUNT): staged entries via disclosure.StagedEntries (## [ blocks / ## sections, excluding ## Themes) over a per-kind threshold → suggest /ctx-digest. Reads a never-migrated root correctly. - Heavy page (a BYTE count): bytes over the root AND every theme file under .context/<noun>/ → advisory split-or-extract. The root-only measure was blind to the bloat folding relocates into theme files. The heavy-page remedy is deliberately not tier-2 auto-fold: past a byte ceiling, an LLM is a poor linter and more Markdown is the wrong fix, so the human decides whether the content belongs in tooling instead. convention_line_count (a size measure) is retired for convention_section_count (the watermark unit); a shared theme_page_byte_ceiling is added. No state file — staging plus on-disk bytes are self-describing. The check-knowledge throttle / log-first plumbing is reused so a declining user is not nagged. Records both decisions in DECISIONS.md. Implementation follows via /ctx-task-out --milestone pd-m5. Spec: specs/progressive-disclosure.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
Plan document at specs/plans/pd-m5.md: data model, contracts, an 8-row test matrix, 23 falsifiable tasks in 6 epics, execution waves, and a measurement gate (T22). Epic anchors synced to TASKS.md, partitioning T01-T23 (3+5+4+2+6+3). Blocking TBD (nudge-threshold) resolved in the spec + DECISIONS; default threshold values (section_count=12, byte_ceiling=64KB) carried as deferrable, tunable via rc. Spec: specs/progressive-disclosure.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
E1 config: retire ConventionLineCount (line measure) for ConventionSectionCount (staged sections, default 12) and add ThemePageByteCeiling (default 65536); runtime defaults, rc accessors, .ctxrc schema, and the unit text keys (sections, bytes) updated together. E2 core: knowledge.Health emits two signals from one scan — foldable roots (staging count via disclosure.StagedEntries, so a never-migrated root reads full and a folded one quiets) and heavy pages (bytes over the root AND every theme file, closing the fold-created blindness). Both-fire orders foldable first. Unexported scan helpers split into scan.go; Thresholds/finding types in types.go (file-convention + mixed-visibility audits). Tests (M1-M7): un-migrated foldable, folded-quiet, heavy theme file, both-fire ordering, convention-measure-is-sections, boundary (>N) and disable (0). Full suite + make lint green. Spec: specs/progressive-disclosure.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
Warning text routes by signal kind: foldable roots lead with /ctx-digest (consolidate/drift demoted to secondary), heavy pages advise split-or-extract-to-tooling. FormatWarnings groups findings by kind and attaches each remedy; the generic remedy block is retired from the template and the now-dead fallback key removed. New knowledge.Report (no throttle, no relay) and a ctx system check-knowledge --report path the /ctx-remember and /ctx-wrap-up skills call for the live state on demand. thresholds() shared by CheckHealth and Report. Flag wired via flagbind + a system flag desc key; print via write/setup. Spec: specs/progressive-disclosure.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
…E4-E6) E4: /ctx-remember runs 'ctx system check-knowledge --report' after recall and surfaces foldable/heavy roots in the readback (read-only); /ctx-wrap-up surfaces them as a next-session suggestion and explicitly never folds inline (the human is leaving). Copilot skills synced. E6: surface-parity test (M8) — the hook path and the report path derive from one Health scan, so the report text is exactly what the nudge box wraps. Measurement gate (T22) driven on a realistic .context (35-entry LEARNINGS + 91 KB theme file): both signals surface, foldable first, with correct remedies. Milestone gate (T23): make lint 0, go test green, make audit pass. All 23 tasks and every DoD box complete. 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
Milestone 5 wires progressive disclosure into the session loop. One
knowledge.Healthfunction emits two suggestion-only signals — foldableroots (staging has accreted → run
/ctx-digest) and heavy pages(bytes over a ceiling → split the theme or extract it to tooling) — and
feeds all three session surfaces (the
check-knowledgegrowth hook,/ctx-remember,/ctx-wrap-up) from that single source, so the Go hookand the prose skills cannot drift. Nothing auto-folds; no state file is
introduced. This resolves the nudge-threshold TBD the pd-m4 plan flagged
as blocking.
The branch also carries one pd-m4 residue commit (session captures) that
rode onto this branch after PR #152 merged.
Changes
internal/config/runtime,internal/rc,.ctxrcschema):retire the line-count measure
convention_line_countforconvention_section_count(the foldability watermark unit, default 12)and add
theme_page_byte_ceiling(default 65536). — servesspecs/progressive-disclosure.mdinternal/cli/system/core/knowledge):knowledge.Healthcomputes foldability as a staging count viadisclosure.StagedEntries(so a never-migrated root reads full and afolded one quiets) and weight as bytes over the root and every theme
file — closing the blindness the root-only measure had to the bulk
folding relocates. Both-fire on one root orders foldable first. —
serves
specs/progressive-disclosure.mdfoldable leads with
/ctx-digest(consolidate/drift demoted tosecondary), heavy advises split-or-extract-to-tooling ("a context file
this heavy is a linter in prose"). A new non-throttled, non-relaying
ctx system check-knowledge --reportpath lets the skills read the livestate on demand. — serves
specs/progressive-disclosure.md/ctx-remembersurfaces foldable/heavy roots in itsreadback (read-only);
/ctx-wrap-upsurfaces them as a next-sessionsuggestion and never folds inline (the human is leaving). Copilot skills
synced. — serves
specs/progressive-disclosure.mdspecs/progressive-disclosure.mdphase 5 formalized;decomposed into
specs/plans/pd-m5.md(23 tasks, 6 epics, test matrix).Specs
specs/progressive-disclosure.md— the bounded-root model; phase 5(suggest-only triggers) is what this milestone implements
specs/plans/pd-m5.md— the implementation plan and execution ledgerthis branch executed
Closed tasks
[E1]Config: retireConventionLineCount; addConventionSectionCount+ThemePageByteCeiling+ runtime defaults[E2]Health core:findingKind/Path; foldable signal viadisclosure.StagedEntries; heavy signal over root + theme-file bytes;foldable-first ordering
[E3]Wiring: per-kind warning text; format routing;check-knowledgereport path; hook uses
Health[E4]Skills:/ctx-remember+/ctx-wrap-upsurface foldable/heavy,suggest-only
[E5]Tests: health fixtures, heavy root + theme file, both-fireordering, convention measure, boundary/disable, surface parity
[E6]Sync + gates: copilot sync, measurement gate, milestone gateAll 23 tasks in
specs/plans/pd-m5.mdare[x].Verification
make lint0 issues,go test ./...green,make auditall checks passed.file, both-fire ordering, convention-measure-is-sections, boundary
(
>N) and disable (0), and hook↔report surface parity..context(35-entryLEARNINGS + 91 KB theme file): both signals surfaced, foldable first,
with the correct per-kind remedies.
Notes for reviewers
convention_section_count=12,theme_page_byte_ceiling=65536) are educated guesses, recorded in theplan's Risks as rc-tunable; real-world use may warrant a tweak (an rc
change, not code).
convention_line_countis a breaking rc-key change (line → sectionmeasure); intentional per the watermark decision, framed as user
education.