mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-01 22:45:02 +01:00
docs: CHANGELOG matches the merged skip lists and the baseline diff (ship review, run 4)
The headline still called the autoplan and inline /office-hours skip entries a follow-up, but the main merge added them; it now says the loaded skills skip their shared Read. The #3451 sentence is dropped, because that fix shipped in v1.91.237.0 and is recorded there. The typecheck baseline line says the TS2769 entry was re-keyed for the 'preamble' artifact kind with its count unchanged, not fixed and lowered. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
1 parent
198ebfd647
commit
5c29dac287
1 file changed
+3
-3
+3
-3
@@ -2,7 +2,7 @@
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
**Tier 2+ skills load the shared preamble once per session instead of once per invocation.** Every tier 2+ SKILL.md carried the same ~23 KB of preamble (AskUserQuestion format, voice, writing style, completeness, completion protocol and more), so each skill invocation re-read text the conversation already held. That text now renders once per host into `sections/preamble.md` beside each tier 2+ SKILL.md. The SKILL.md keeps a short "Shared preamble (load first)" pointer naming the file and its id (a hash of the shared text before host rewrites), and asks for the Read unless the skill's own earlier Read of that file, headed by that id, is still in context, so other text that merely carries the id cannot stand in for the shared rules. Measured with Anthropic token counting: review's SKILL.md drops from 21,884 to 16,103 tokens, ship from 22,688 to 16,907, office-hours from 27,100 to 23,085 and design-review from 39,040 to 33,261. The shared file is 5,953 tokens, so a skill's first invocation in a session costs about 170 tokens more than before (about 1,900 for office-hours, about 3,800 for plan-eng-review) and every later invocation of that skill saves about 5,800 (4,000 for office-hours, 2,200 for plan-eng-review). The skip is tied to the skill's own copy of the file, so the first invocation of each different skill pays the Read again. A /autoplan run's four review-skill loads carry 17,941 fewer SKILL.md tokens (191,871 → 173,930), but /autoplan's section skip list and the inline /office-hours loader do not yet name the "Shared preamble (load first)" section, so each loaded skill can still ask for its own shared file; adding it grows size-pinned skills and is a follow-up.
|
||||
**Tier 2+ skills load the shared preamble once per session instead of once per invocation.** Every tier 2+ SKILL.md carried the same ~23 KB of preamble (AskUserQuestion format, voice, writing style, completeness, completion protocol and more), so each skill invocation re-read text the conversation already held. That text now renders once per host into `sections/preamble.md` beside each tier 2+ SKILL.md. The SKILL.md keeps a short "Shared preamble (load first)" pointer naming the file and its id (a hash of the shared text before host rewrites), and asks for the Read unless the skill's own earlier Read of that file, headed by that id, is still in context, so other text that merely carries the id cannot stand in for the shared rules. Measured with Anthropic token counting: review's SKILL.md drops from 21,884 to 16,103 tokens, ship from 22,688 to 16,907, office-hours from 27,100 to 23,085 and design-review from 39,040 to 33,261. The shared file is 5,953 tokens, so a skill's first invocation in a session costs about 170 tokens more than before (about 1,900 for office-hours, about 3,800 for plan-eng-review) and every later invocation of that skill saves about 5,800 (4,000 for office-hours, 2,200 for plan-eng-review). The skip is tied to the skill's own copy of the file, so the first invocation of each different skill pays the Read again. A /autoplan run's four review-skill loads carry 17,941 fewer SKILL.md tokens (191,871 → 173,930), and /autoplan and the inline /office-hours loader skip each loaded skill's "Shared preamble (load first)" section, because the parent already holds the shared preamble.
|
||||
|
||||
### Changed
|
||||
- **`scripts/resolvers/preamble-hoist.ts`** (new) renders `{{PREAMBLE}}` for tier 2+ skills: a section moves to the shared file only when this skill's render of it is byte-identical to the shared render, so no skill's instructions change. Sections that name the skill (the start command, Question Tuning, Repo Ownership, Search Before Building, Telemetry), text without its own heading, and skill-specific variants stay inline; a variant that keeps the shared subsection headings carries only its differing `###` subsections. Tier 1 skills keep their short preamble inline. Across all 41 hoisted skills, the SKILL.md with its shared file applied holds exactly the paragraphs the pre-hoist SKILL.md held.
|
||||
@@ -17,7 +17,7 @@
|
||||
- `test/fixtures/skill-md-size-allowlist.json`: 63 pins lowered and 26 deleted (now within the 100,000-character limit). None raised. The deferral note (owner Garry, revisit 2026-11-15) is retired here and in `test/skill-md-size-guard.test.ts`.
|
||||
- `test/section-manifest-consistency.test.ts`: the generated-orphan check exempts the shared `sections/preamble.md` only when the skill's SKILL.md carries the "Shared preamble (load first)" pointer, because that file renders from `scripts/resolvers/preamble-hoist.ts` rather than a section template; it still must carry the AUTO-GENERATED header, and the generation freshness check covers its content. `test/paid-pr-profile.test.ts` covers the planner change.
|
||||
- `test/preamble-hoist.test.ts` (new): tier 1 output is unchanged, and a tier 2+ SKILL.md with its `sections/preamble.md` applied holds exactly the pre-hoist preamble; the pointer opens the preamble, precedes the start command and names the shared file's id. `test/gen-skill-docs-checks.test.ts` checks that each host renders one shared preamble, beside every pointer and under the id the pointer names. `test/host-conformance.test.ts` checks that `setup --status` still finds a broken bare `sections/` pointer when a carved Claude skill's installed `sections/` is a directory symlink. A second `test/preamble-hoist.test.ts` case checks, on every host, tier and render option, that the pointer allows the skip only when the skill's own Read of the file is in context, never on the id alone.
|
||||
- Ship goldens regenerated. 27 paid-test touchfile keys gain `test/helpers/skill-startup.ts`, which is also a global touchfile pinned in `scripts/harness-version.json` (recorded non-behavioral) because `test/helpers/skill-fixture.ts` builds its fixtures through it, and every key that names `scripts/resolvers/preamble.ts` also names `scripts/resolvers/preamble-hoist.ts`, so a hoist change selects the same paid cases. One existing test-typecheck diagnostic fixed and its baseline lowered.
|
||||
- Ship goldens regenerated. 27 paid-test touchfile keys gain `test/helpers/skill-startup.ts`, which is also a global touchfile pinned in `scripts/harness-version.json` (recorded non-behavioral) because `test/helpers/skill-fixture.ts` builds its fixtures through it, and every key that names `scripts/resolvers/preamble.ts` also names `scripts/resolvers/preamble-hoist.ts`, so a hoist change selects the same paid cases. The existing TS2769 test-typecheck baseline entry for `test/gen-skill-docs-checks.test.ts` is re-keyed for the new `preamble` artifact kind, its count unchanged.
|
||||
- `test/skill-llm-eval.test.ts`: the `voice directive tone` judge reads review's Voice section through `readSkillEffective` (SKILL.md plus its shared preamble), because the section now lives in `review/sections/preamble.md`. The text it judges is byte-identical to main's; rubric and thresholds are unchanged.
|
||||
- `test/helpers/touchfiles-data.ts`: `ETHOS.md` is registered on the 41 paid cases whose touchfiles cover `plan-ceo-review` or `office-hours`, the two skills that tell the agent to read it, so an ETHOS.md change selects those cases instead of restoring the full gate. The unknown-dependency examples in `test/paid-pr-profile.test.ts`, `test/paid-free-boundary.test.ts` and `test/pr-dependencies.test.ts` now use `SECURITY.md` and `LICENSE`, and the first checks that ETHOS.md maps to its reader cases.
|
||||
|
||||
@@ -31,7 +31,7 @@
|
||||
- **`scripts/resolvers/preamble/generate-completeness-section.ts`**: the default section reads "Complete coverage, minimal code": recommend full coverage of the requirement (tests, edge cases, error paths) and no code beyond it, prefer the smaller diff at equal coverage, and add no checks for impossible states. Unrelated work stays separate scope. The `Completeness: X/10` scoring rule and the GPT-5.6 Sol variant are unchanged. The section is 3 characters shorter, so every regenerated skill shrinks and 89 size pins go down.
|
||||
- **`ETHOS.md`**: "Completeness is cheap ... always prefer A" becomes "Complete coverage, minimal code": completeness is measured in coverage, not lines; at equal coverage choose the smaller diff; no speculative abstractions, impossible-state checks or unneeded refactors. A new anti-pattern names the impossible-state fallback. Section 1's opener now says "When covering the whole requirement costs minutes more than the shortcut, cover it. Every time. Complete means complete coverage, not more code.", and "How They Work Together" says Boil the Ocean means "cover the whole requirement with the least code" instead of "do the complete thing".
|
||||
- **`plan-ceo-review/SKILL.md.tmpl`**: the Philosophy bullet "COMPLETENESS IS CHEAP: AI makes 70 LOC seconds. Prefer complete ~150 LOC over 90% ~80 LOC. Boil the ocean." becomes "COMPLETENESS IS COVERAGE": cover the whole requirement (tests, edge cases, error paths) rather than a 90% shortcut, add no code beyond the accepted scope (so SCOPE EXPANSION and SELECTIVE EXPANSION still build what the user accepted), and choose the smaller diff at equal coverage. plan-ceo-review is under the 100,000-character limit on every host and has no size pin, so it grows about 100 characters without a pin change.
|
||||
- **First-run intro**: the one-time Boil the Ocean intro in `bin/gstack-skill-start` says "complete coverage, minimal code" instead of "do the complete thing when AI makes marginal cost near-zero". The agents digest's Boil the Ocean bullet (`scripts/gen-agents-digest.ts`, regenerated `agents-digest/gstack-AGENTS.md`) says the same: "complete coverage, minimal code: cover the whole requirement (tests, edge cases, error paths) and write no code beyond it". The version gate no longer treats a release output regenerated at the base VERSION as a stamp (#3451).
|
||||
- **First-run intro**: the one-time Boil the Ocean intro in `bin/gstack-skill-start` says "complete coverage, minimal code" instead of "do the complete thing when AI makes marginal cost near-zero". The agents digest's Boil the Ocean bullet (`scripts/gen-agents-digest.ts`, regenerated `agents-digest/gstack-AGENTS.md`) says the same: "complete coverage, minimal code: cover the whole requirement (tests, edge cases, error paths) and write no code beyond it".
|
||||
- `review/specialists/simplification.md` quotes the new house rule instead of "If A is 70 lines more, choose A", and `CLAUDE.md` restates it in place of "Completeness is cheap ... the complete thing is the goal".
|
||||
|
||||
### Tests
|
||||
|
||||
Reference in new issue
Block a user