Design docs: concise decision records (overlay #2000)

CHANGELOG.md

@@ -7,6 +7,37 @@
 > completion state and remaining P0 gates. No version bump or release claim is
 > made here while that status holds.
 
+## [1.61.1.0] - 2026-07-22
+
+## **Design docs now read like decision records.**
+## **The transcript padding is gone.**
+
+v1.61.0.0 put design docs in your repo at `docs/designs/`. This release fixes what is inside them. The `/plan` Discovery specialist now writes bullets over paragraphs, one bullet per decision with its why. An approach you killed during the conversation gets one line, name plus rejection reason, instead of a resurrected "Approach B" section that re-argues the case. Template sections that are empty or that restate what you already settled are omitted. There is no page cap, just a rule that every word earns its place: extra length has to come from genuinely open questions, not template completeness.
+
+### The numbers that matter
+
+Source: `bun run scripts/gstack2/run-parity.ts`, the executable parity inventory, plus the field report that triggered this (a support-system design doc where most of the content was approaches the user had already ruled out in chat).
+
+| Metric | Before | After |
+|---|---|---|
+| Judgment overlays | 27 | 28 |
+| Parity checks | 4,909 | 4,914 |
+| Lines per ruled-out approach | a full section | 1 |
+
+No before/after length benchmark for generated docs exists yet; the rule ships with an executable regression fixture (`evals/parity/regressions/pr-2000.json`) instead of a measured corpus.
+
+### What this means for builders
+
+When office hours hands you a design doc, you can read it in one sitting and see what was decided and why. Nothing you rejected in the session comes back as prose. If a doc runs long, it is because real questions are still open. Run `/plan` as usual; nothing to configure.
+
+### Itemized changes
+
+#### Changed
+- The `/plan` Discovery (office-hours) design doc is now a concise decision record (issue #2000): bullet points over paragraphs, ruled-out approaches collapsed to one line each with the rejection reason, settled or empty template sections omitted, no fixed page cap.
+
+#### For contributors
+- New judgment overlay `GSTACK2_FIX_2000_DESIGN_DOC_CONCISION` (targets office-hours) with executable regression `pr-2000.json`; parity inventory is now 4,914 checks across 28 regression ports.
+
 ## [1.61.0.0] - 2026-07-22
 
 ## **/plan now sizes its machinery to your ask.**

VERSION

@@ -1 +1 @@
-1.61.0.0
+1.61.1.0

scripts/gstack2/bug-fix-overlays.ts

@@ -391,6 +391,24 @@ Before scope-drift detection, read a \`## Review\` section from the project CLAU
       expected: { apply_repo_rules: true, silent_skip_if_absent: true },
     },
   },
+  {
+    pr: 2000,
+    url: 'https://github.com/garrytan/gstack/issues/2000',
+    title: 'Design docs record decisions concisely',
+    targets: ['office-hours'],
+    anchor: 'GSTACK2_FIX_2000_DESIGN_DOC_CONCISION',
+    body: `### Design-doc concision
+
+The design doc is a decision record, not a transcript of the session. There is no fixed page limit, but every word must earn its place: prefer bullet points over paragraphs, one bullet per decision with its why. An approach the user ruled out during the session gets at most one line — name plus rejection reason — never its own section, comparison matrix, or re-argued case. Omit template sections that are empty or that restate what the conversation already settled. Cut preamble, hedging, and restated context; extra length must be earned by genuinely open questions, not by template completeness. (Placement is governed by the repo-local design-artifact rule from issue #703.)`,
+    regression: {
+      input: { ruled_out_approaches: 3 },
+      expected: {
+        ruled_out_lines_each: 1,
+        bullets_over_paragraphs: true,
+        settled_sections_omitted: true,
+      },
+    },
+  },
 ];
 
 export function overlaysForSource(source: string): BugFixOverlay[] {
@@ -566,6 +584,14 @@ export function evaluateBugFixRegression(pr: number, rawInput: unknown): Record<
     }
     case 452:
       return { apply_repo_rules: input.claude_md_has_review_section === true, silent_skip_if_absent: true };
+    case 2000: {
+      const ruledOut = Number(input.ruled_out_approaches ?? 0);
+      return {
+        ruled_out_lines_each: ruledOut > 0 ? 1 : 0,
+        bullets_over_paragraphs: true,
+        settled_sections_omitted: true,
+      };
+    }
     case 703: {
       const inRepo = input.in_repository === true;
       return {

scripts/gstack2/generate-skill-tree.ts

@@ -82,7 +82,7 @@ function assertInventory(): void {
   }
   if (legacySections().length !== 16) throw new Error(`Expected 16 section templates, found ${legacySections().length}`);
   if (SCENARIOS.length !== 25) throw new Error(`Expected 25 parity scenarios, found ${SCENARIOS.length}`);
-  if (BUG_FIX_OVERLAYS.length !== 27) throw new Error(`Expected 27 upstream judgment overlays, found ${BUG_FIX_OVERLAYS.length}`);
+  if (BUG_FIX_OVERLAYS.length !== 28) throw new Error(`Expected 28 upstream judgment overlays, found ${BUG_FIX_OVERLAYS.length}`);
 }
 
 function toc(body: string): string {
@@ -758,7 +758,7 @@ ${rows}
 ## Mechanical versus judgment changes
 
 - \`JUDGMENT_PRESERVING_CARVE\`: pinned specialist workflow with the retired shared onboarding wrapper excluded, retired invocations resolved to six public routes, host/runtime paths normalized, and large carved phases loaded lazily from package-local pinned references.
-- \`BUG_FIX\`: the canonical carved body plus a clearly delimited judgment overlay sourced from one of the 27 upstream PRs and issues and its regression fixture.
+- \`BUG_FIX\`: the canonical carved body plus a clearly delimited judgment overlay sourced from one of the 28 upstream PRs and issues and its regression fixture.
 - Asset relocation is byte-for-byte from the pinned Git blob and is indexed per tree.
 `;
 }
@@ -779,7 +779,7 @@ function parityDoc(assetCount: number): string {
 
 Parity is executable, not a prose claim. Run \`bun run scripts/gstack2/run-parity.ts\` or the dedicated Bun tests.
 
-The pinned release inventory passes **${EXPECTED_PARITY_CHECKS.toLocaleString('en-US')} checks** across 55 specialist sources, 16 carved sections, 25 routing scenarios, 27 regression ports, and **${assetCount} assets**.
+The pinned release inventory passes **${EXPECTED_PARITY_CHECKS.toLocaleString('en-US')} checks** across 55 specialist sources, 16 carved sections, 25 routing scenarios, 28 regression ports, and **${assetCount} assets**.
 
 The suite verifies:
 
@@ -788,7 +788,7 @@ The suite verifies:
 - immutable full 1.x render hashes plus canonical specialist-render equality, with the excluded onboarding wrapper and lazy section references asserted explicitly;
 - preservation of nine behavioral contract dimensions per module;
 - 25 structured non-keyword routing fixtures with active/skipped modules, depth, mutation, and web context;
-- 25 upstream judgment-port regression fixtures and anchors;
+- 28 upstream judgment-port regression fixtures and anchors;
 - all linked asset copies against their pinned Git blobs;
 - frontmatter and \`agents/openai.yaml\` schema for each public skill.
 
@@ -938,7 +938,7 @@ function main(): void {
     schema_version: 1,
     base_sha: GSTACK2_BASE_SHA,
     public_skills: [...TREE_NAMES],
-    counts: { public_skills: 6, mandatory_inputs: 31, templates: 55, section_templates: 16, packaged_section_copies: sectionCopies.length, internal_execution_adapters: 1, scenarios: 25, bug_fix_ports: 25, assets: assets.length, dependency_copies: dependencyCopies.length, runtime_helpers: runtimeHelpers.length },
+    counts: { public_skills: 6, mandatory_inputs: 31, templates: 55, section_templates: 16, packaged_section_copies: sectionCopies.length, internal_execution_adapters: 1, scenarios: 25, bug_fix_ports: 28, assets: assets.length, dependency_copies: dependencyCopies.length, runtime_helpers: runtimeHelpers.length },
     sources: sourceRecords,
     sections: sectionRecords,
     section_copies: sectionCopies,

scripts/gstack2/run-parity.ts

@@ -21,8 +21,9 @@ const ALLOWED_DISPOSITIONS = new Set(['VERBATIM_PORT', 'MECHANICAL_PORT', 'JUDGM
 // proportional-planning overlay for issue #886 (25 -> 26, six plan-tree
 // targets) added 15 more (2 per targeted module + 3 regression checks). The
 // repo-local design-doc overlay for issue #703 (26 -> 27, five plan-tree
-// targets) added 13 more.
-export const EXPECTED_PARITY_CHECKS = 4909;
+// targets) added 13 more. The design-doc concision overlay for issue #2000
+// (27 -> 28, office-hours only) added 5 more.
+export const EXPECTED_PARITY_CHECKS = 4914;
 
 function sha256(value: string | Uint8Array): string {
   return createHash('sha256').update(value).digest('hex');
@@ -257,8 +258,8 @@ export function runParity(): ParityResult {
     check(JSON.stringify(json(path.join(ROOT, 'evals', 'parity', 'scenarios', `${scenario.id}.json`))) === JSON.stringify(scenario), `${scenario.id} generated fixture drift`);
   }
 
-  check(BUG_FIX_OVERLAYS.length === 27, `Expected 27 regression definitions; got ${BUG_FIX_OVERLAYS.length}`);
-  check(files(path.join(ROOT, 'evals', 'parity', 'regressions'), '.json').length === 27, 'Generated regression fixture count is not 27');
+  check(BUG_FIX_OVERLAYS.length === 28, `Expected 28 regression definitions; got ${BUG_FIX_OVERLAYS.length}`);
+  check(files(path.join(ROOT, 'evals', 'parity', 'regressions'), '.json').length === 28, 'Generated regression fixture count is not 28');
   for (const overlay of BUG_FIX_OVERLAYS) {
     const fixture = json(path.join(ROOT, 'evals', 'parity', 'regressions', `pr-${overlay.pr}.json`));
     check(JSON.stringify(fixture) === JSON.stringify(overlay), `PR #${overlay.pr} regression fixture drift`);

test/gstack2-skills.test.ts

@@ -27,7 +27,7 @@ describe('GStack 2 skill parity', () => {
     const result = runParity();
     expect(result.sources).toBe(55);
     expect(result.sections).toBe(16);
-    expect(result.regressions).toBe(27);
+    expect(result.regressions).toBe(28);
   }, 30_000);
 
   test('keeps image generation host-native, optional, and provider-free', () => {