diff --git a/.gitattributes b/.gitattributes index 92e301fde7..6cab444175 100644 --- a/.gitattributes +++ b/.gitattributes @@ -51,3 +51,17 @@ bin/* text eol=lf # the content-addressed staged filename. lib/diagram-render/dist/*.html text eol=lf whitespace=-trailing-space lib/diagram-render/dist/*.json text eol=lf + +# GStack 2 generator output (scripts/gstack2/, `bun run gen:gstack2`). +# Marked linguist-generated so PR reviews collapse these by default and +# reviewers see only the hand-edited generator inputs. check:gstack2-generated +# enforces that these always match a clean regeneration, so their diffs are +# reproducible rather than reviewable. +skills/** linguist-generated=true +compat/** linguist-generated=true +evals/parity/** linguist-generated=true +docs/gstack-2/JUDGMENT-PARITY.md linguist-generated=true +docs/gstack-2/JUDGMENT-PROVENANCE.json linguist-generated=true +docs/gstack-2/SCENARIOS.md linguist-generated=true +docs/gstack-2/SKILL-MIGRATION.md linguist-generated=true +docs/gstack-2/BACKLOG-MAP.json linguist-generated=true diff --git a/.github/workflows/gstack2-gate.yml b/.github/workflows/gstack2-gate.yml index 6c0cbf9c6d..03ece139a1 100644 --- a/.github/workflows/gstack2-gate.yml +++ b/.github/workflows/gstack2-gate.yml @@ -25,6 +25,8 @@ jobs: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 with: fetch-depth: 0 + - name: Fetch the pinned GStack 2 base commit (not reachable from PR refs) + run: git fetch --no-tags --depth=1 origin bb57306d98c97011b0919c6132705a15b1579781 - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2 with: bun-version: 1.3.14 @@ -51,6 +53,8 @@ jobs: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 with: fetch-depth: 0 + - name: Fetch the pinned GStack 2 base commit (not reachable from PR refs) + run: git fetch --no-tags --depth=1 origin bb57306d98c97011b0919c6132705a15b1579781 - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2 with: bun-version: 1.3.14 @@ -66,6 +70,8 @@ jobs: timeout-minutes: 15 steps: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + - name: Fetch the pinned GStack 2 base commit (not reachable from PR refs) + run: git fetch --no-tags --depth=1 origin bb57306d98c97011b0919c6132705a15b1579781 - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2 with: bun-version: 1.3.14 @@ -84,6 +90,8 @@ jobs: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 with: fetch-depth: 0 + - name: Fetch the pinned GStack 2 base commit (not reachable from PR refs) + run: git fetch --no-tags --depth=1 origin bb57306d98c97011b0919c6132705a15b1579781 - name: Build the declared development container run: docker build --file .devcontainer/Dockerfile --tag gstack2-devcontainer . - name: Run the GStack 2 gate inside the container diff --git a/CHANGELOG.md b/CHANGELOG.md index 3fc149c519..dbce423c46 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,46 @@ > completion state and remaining P0 gates. No version bump or release claim is > made here while that status holds. +## [1.61.0.0] - 2026-07-22 + +## **/plan now sizes its machinery to your ask.** +## **A terminal toy gets one question round, not a startup diagnostic.** + +Ask /plan for something small and it plans something small. The dispatcher now classifies every request on fifteen build-scale vectors (audience, users, commercial intent, deployment, time horizon, integration surface, extensibility, stakes, and so on) and prints the verdict as a `Scale:` line in the execution header: session, hobby, project, product, or venture. Every planning specialist keys its effort to that line. "A cool space animation in my terminal" is session-scale and gets one batched question round, no web research, no outside design voices, and a one-page doc with next steps in hours. "A startup with customizable APIs" is venture-scale and gets the full question pressure, exactly as before. Classification comes from your prompt and cheap repository evidence only; /plan never asks questions just to decide how many questions to ask. + +### The numbers that matter + +Source: a real /plan Discovery session on 2026-07-22 for a zero-player terminal spaceship toy (transcript `~/.claude/projects/-Users-sinabina-spacegame/b01e246b-*.jsonl`). The After column is the enforced rule at session scale, pinned by the executable regression in `evals/parity/regressions/pr-886.json` (run: `bun run test:gstack2`). + +| Metric (session-scale ask) | Before | After | +|---|---|---| +| AskUserQuestion rounds | 10, one at a time | 1, batched | +| Adversarial review iterations on the doc | 3 | 1 max | +| Web searches by default | 2 | 0, on request | +| Wireframe + outside-voice offers | 2 | 0, on request | +| Next-steps horizon | phased roadmap + distribution plan | hours | +| Output tokens for the session | 115,395 measured | no measurement yet | + +Ten separate question rounds means ten full round-trips before a single line of design exists. For a toy built for fun, that was the whole session. One batched round answers the same questions in one pass. + +### What this means for you + +Small ideas stop costing big-idea tokens and big-idea patience. You can throw a one-liner at /plan and get a one-page plan the same sitting, and the moment your answers reveal real ambition (users, revenue, a platform) the scale upgrades mid-session and the full workflow comes back. Approval gates never shrink at any scale. Just describe what you want to build; the sizing is /plan's job now. + +### Itemized changes + +#### Added + +- **Build-scale classification in /plan.** The dispatcher's execution header gains a `Scale:` line (session, hobby, project, product, venture) classified from fifteen scale vectors before any questioning begins. Highest vector wins; unknown vectors default low; explicit statements dominate inference. +- **Proportional-planning judgment port (#886)** across all six planning specialists (office-hours, plan-ceo-review, plan-eng-review, plan-devex-review, spec, autoplan): question batching, research and outside-voice gating, review-iteration caps, artifact size, and step units keyed to the printed Scale. product and venture scale change nothing; STOP and approval gates are unchanged everywhere. +- **Design docs land in your repo (#703).** When you plan inside a repository, the design doc is written to `docs/designs/.md` and approval questions name that path, not a hashed directory under `~/.gstack`. The cross-session copy in `~/.gstack/projects/` is still written so downstream skills and prior-design discovery keep working, and plan reviews now prefer the repo-local doc when both exist. + +#### For contributors + +- Overlay #886 anchors to the upstream issue "GENERAL: Reduce Token Overhead" and ships an executable vector-to-tier regression evaluated by `run-parity.ts` (check inventory 4,881 to 4,896). +- Generator output (`skills/**`, `compat/**`, `evals/parity/**`, generated `docs/gstack-2/` docs) is now marked `linguist-generated`, so PRs collapse it and reviewers see only hand-edited generator inputs. `check:gstack2-generated` keeps the collapsed files honest. +- Overlay headings now say "issue" instead of "PR" when the source URL is an issue. + ## [1.60.1.0] - 2026-07-09 ## **The /autoplan dual-voice eval is back on the board, catching real regressions.** diff --git a/VERSION b/VERSION index c4190e0048..82b3fa4c6d 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.60.1.0 +1.61.0.0 diff --git a/docs/gstack-2/JUDGMENT-PARITY.md b/docs/gstack-2/JUDGMENT-PARITY.md index c0aed2787e..20e06d0997 100644 --- a/docs/gstack-2/JUDGMENT-PARITY.md +++ b/docs/gstack-2/JUDGMENT-PARITY.md @@ -2,7 +2,7 @@ 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 **4,881 checks** across 55 specialist sources, 16 carved sections, 25 routing scenarios, 25 regression ports, and **78 assets**. +The pinned release inventory passes **4,909 checks** across 55 specialist sources, 16 carved sections, 25 routing scenarios, 27 regression ports, and **78 assets**. The suite verifies: diff --git a/docs/gstack-2/JUDGMENT-PROVENANCE.json b/docs/gstack-2/JUDGMENT-PROVENANCE.json index ac3b722559..78349a8d18 100644 --- a/docs/gstack-2/JUDGMENT-PROVENANCE.json +++ b/docs/gstack-2/JUDGMENT-PROVENANCE.json @@ -90,7 +90,9 @@ 679, 2030, 1049, - 1116 + 1116, + 886, + 703 ], "original_source_file": "office-hours/SKILL.md.tmpl", "original_line_range": "1-526", @@ -204,7 +206,9 @@ "disposition": "BUG_FIX", "overlays": [ 679, - 2030 + 2030, + 886, + 703 ], "original_source_file": "plan-ceo-review/SKILL.md.tmpl", "original_line_range": "1-427", @@ -346,7 +350,9 @@ 679, 1071, 2030, - 592 + 592, + 886, + 703 ], "original_source_file": "plan-eng-review/SKILL.md.tmpl", "original_line_range": "1-158", @@ -465,7 +471,9 @@ "disposition": "BUG_FIX", "overlays": [ 679, - 2030 + 2030, + 886, + 703 ], "original_source_file": "plan-devex-review/SKILL.md.tmpl", "original_line_range": "1-462", @@ -599,7 +607,9 @@ "overlays": [ 679, 2014, - 2023 + 2023, + 886, + 703 ], "original_source_file": "autoplan/SKILL.md.tmpl", "original_line_range": "1-916", @@ -688,7 +698,8 @@ "target": "skills/plan/references/legacy/spec.md", "disposition": "BUG_FIX", "overlays": [ - 679 + 679, + 886 ], "original_source_file": "spec/SKILL.md.tmpl", "original_line_range": "1-769", @@ -7413,6 +7424,33 @@ ], "anchor": "GSTACK2_FIX_1116_INLINE_APPROVAL_DOC" }, + { + "pr": 886, + "url": "https://github.com/garrytan/gstack/issues/886", + "title": "Scale planning machinery to the printed build scale", + "targets": [ + "office-hours", + "plan-ceo-review", + "plan-eng-review", + "plan-devex-review", + "spec", + "autoplan" + ], + "anchor": "GSTACK2_FIX_886_PROPORTIONAL_PLANNING" + }, + { + "pr": 703, + "url": "https://github.com/garrytan/gstack/issues/703", + "title": "Write design docs repo-local and read them from the repo first", + "targets": [ + "office-hours", + "plan-ceo-review", + "plan-eng-review", + "plan-devex-review", + "autoplan" + ], + "anchor": "GSTACK2_FIX_703_REPO_LOCAL_DESIGN_DOCS" + }, { "pr": 452, "url": "https://github.com/garrytan/gstack/pull/452", diff --git a/docs/gstack-2/SKILL-MIGRATION.md b/docs/gstack-2/SKILL-MIGRATION.md index 0f90b0b46d..70b470412c 100644 --- a/docs/gstack-2/SKILL-MIGRATION.md +++ b/docs/gstack-2/SKILL-MIGRATION.md @@ -11,12 +11,12 @@ The fixed public modes are: Design = `Explore | Generate | Critique | Implement` | Legacy invocation | Replacement | Visibility | Mandatory | Judgment overlays | |---|---|---|---|---| | `/gstack` | `$plan --mode Discovery --module gstack` | internal (internal) | no | #679 | -| `/office-hours` | `$plan --mode Discovery --module office-hours` | internal (primary) | yes | #679, #2030, #1049, #1116 | -| `/plan-ceo-review` | `$plan --mode Product --module plan-ceo-review` | internal (primary) | yes | #679, #2030 | -| `/plan-eng-review` | `$plan --mode Engineering --module plan-eng-review` | internal (primary) | yes | #679, #1071, #2030, #592 | -| `/plan-devex-review` | `$plan --mode DX --module plan-devex-review` | internal (primary) | yes | #679, #2030 | -| `/autoplan` | `$plan --mode Full chain --module autoplan` | internal (primary) | yes | #679, #2014, #2023 | -| `/spec` | `$plan --mode Specification --module spec` | internal (primary) | yes | #679 | +| `/office-hours` | `$plan --mode Discovery --module office-hours` | internal (primary) | yes | #679, #2030, #1049, #1116, #886, #703 | +| `/plan-ceo-review` | `$plan --mode Product --module plan-ceo-review` | internal (primary) | yes | #679, #2030, #886, #703 | +| `/plan-eng-review` | `$plan --mode Engineering --module plan-eng-review` | internal (primary) | yes | #679, #1071, #2030, #592, #886, #703 | +| `/plan-devex-review` | `$plan --mode DX --module plan-devex-review` | internal (primary) | yes | #679, #2030, #886, #703 | +| `/autoplan` | `$plan --mode Full chain --module autoplan` | internal (primary) | yes | #679, #2014, #2023, #886, #703 | +| `/spec` | `$plan --mode Specification --module spec` | internal (primary) | yes | #679, #886 | | `/plan-tune` | `$plan --mode Discovery --module plan-tune` | internal (primary) | yes | #679 | | `/context-save` | `$plan --mode Discovery --module context-save` | internal (internal) | no | #679 | | `/context-restore` | `$plan --mode Discovery --module context-restore` | internal (internal) | no | #679 | @@ -75,5 +75,5 @@ The fixed public modes are: Design = `Explore | Generate | Critique | Implement` ## 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 25 upstream PRs and its regression fixture. +- `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. - Asset relocation is byte-for-byte from the pinned Git blob and is indexed per tree. diff --git a/evals/parity/contracts/autoplan.json b/evals/parity/contracts/autoplan.json index 1282d343bc..6ef08ed433 100644 --- a/evals/parity/contracts/autoplan.json +++ b/evals/parity/contracts/autoplan.json @@ -14,7 +14,9 @@ "overlays": [ 679, 2014, - 2023 + 2023, + 886, + 703 ], "contract": { "question_order": "Preserve the source workflow order; gather prerequisites before consequential questions.", diff --git a/evals/parity/contracts/office-hours.json b/evals/parity/contracts/office-hours.json index 666dc0077c..89e2f0e132 100644 --- a/evals/parity/contracts/office-hours.json +++ b/evals/parity/contracts/office-hours.json @@ -15,7 +15,9 @@ 679, 2030, 1049, - 1116 + 1116, + 886, + 703 ], "contract": { "question_order": "Preserve the source workflow order; gather prerequisites before consequential questions.", diff --git a/evals/parity/contracts/plan-ceo-review.json b/evals/parity/contracts/plan-ceo-review.json index 700a85d233..8f69e12b4e 100644 --- a/evals/parity/contracts/plan-ceo-review.json +++ b/evals/parity/contracts/plan-ceo-review.json @@ -13,7 +13,9 @@ "target": "skills/plan/references/legacy/plan-ceo-review.md", "overlays": [ 679, - 2030 + 2030, + 886, + 703 ], "contract": { "question_order": "Preserve the source workflow order; gather prerequisites before consequential questions.", diff --git a/evals/parity/contracts/plan-devex-review.json b/evals/parity/contracts/plan-devex-review.json index d8624cbb62..67f7df867f 100644 --- a/evals/parity/contracts/plan-devex-review.json +++ b/evals/parity/contracts/plan-devex-review.json @@ -13,7 +13,9 @@ "target": "skills/plan/references/legacy/plan-devex-review.md", "overlays": [ 679, - 2030 + 2030, + 886, + 703 ], "contract": { "question_order": "Preserve the source workflow order; gather prerequisites before consequential questions.", diff --git a/evals/parity/contracts/plan-eng-review.json b/evals/parity/contracts/plan-eng-review.json index 3da0652ab1..182e08596a 100644 --- a/evals/parity/contracts/plan-eng-review.json +++ b/evals/parity/contracts/plan-eng-review.json @@ -15,7 +15,9 @@ 679, 1071, 2030, - 592 + 592, + 886, + 703 ], "contract": { "question_order": "Preserve the source workflow order; gather prerequisites before consequential questions.", diff --git a/evals/parity/contracts/spec.json b/evals/parity/contracts/spec.json index 7eeb62e502..037a71024b 100644 --- a/evals/parity/contracts/spec.json +++ b/evals/parity/contracts/spec.json @@ -12,7 +12,8 @@ "normalized_render_sha256": "76b7c03e6d8e7b852beda0a58409d97153771dd8f7b870bbdda23e996ac23fc1", "target": "skills/plan/references/legacy/spec.md", "overlays": [ - 679 + 679, + 886 ], "contract": { "question_order": "Preserve the source workflow order; gather prerequisites before consequential questions.", diff --git a/evals/parity/manifest.json b/evals/parity/manifest.json index ac3b722559..78349a8d18 100644 --- a/evals/parity/manifest.json +++ b/evals/parity/manifest.json @@ -90,7 +90,9 @@ 679, 2030, 1049, - 1116 + 1116, + 886, + 703 ], "original_source_file": "office-hours/SKILL.md.tmpl", "original_line_range": "1-526", @@ -204,7 +206,9 @@ "disposition": "BUG_FIX", "overlays": [ 679, - 2030 + 2030, + 886, + 703 ], "original_source_file": "plan-ceo-review/SKILL.md.tmpl", "original_line_range": "1-427", @@ -346,7 +350,9 @@ 679, 1071, 2030, - 592 + 592, + 886, + 703 ], "original_source_file": "plan-eng-review/SKILL.md.tmpl", "original_line_range": "1-158", @@ -465,7 +471,9 @@ "disposition": "BUG_FIX", "overlays": [ 679, - 2030 + 2030, + 886, + 703 ], "original_source_file": "plan-devex-review/SKILL.md.tmpl", "original_line_range": "1-462", @@ -599,7 +607,9 @@ "overlays": [ 679, 2014, - 2023 + 2023, + 886, + 703 ], "original_source_file": "autoplan/SKILL.md.tmpl", "original_line_range": "1-916", @@ -688,7 +698,8 @@ "target": "skills/plan/references/legacy/spec.md", "disposition": "BUG_FIX", "overlays": [ - 679 + 679, + 886 ], "original_source_file": "spec/SKILL.md.tmpl", "original_line_range": "1-769", @@ -7413,6 +7424,33 @@ ], "anchor": "GSTACK2_FIX_1116_INLINE_APPROVAL_DOC" }, + { + "pr": 886, + "url": "https://github.com/garrytan/gstack/issues/886", + "title": "Scale planning machinery to the printed build scale", + "targets": [ + "office-hours", + "plan-ceo-review", + "plan-eng-review", + "plan-devex-review", + "spec", + "autoplan" + ], + "anchor": "GSTACK2_FIX_886_PROPORTIONAL_PLANNING" + }, + { + "pr": 703, + "url": "https://github.com/garrytan/gstack/issues/703", + "title": "Write design docs repo-local and read them from the repo first", + "targets": [ + "office-hours", + "plan-ceo-review", + "plan-eng-review", + "plan-devex-review", + "autoplan" + ], + "anchor": "GSTACK2_FIX_703_REPO_LOCAL_DESIGN_DOCS" + }, { "pr": 452, "url": "https://github.com/garrytan/gstack/pull/452", diff --git a/evals/parity/regressions/pr-703.json b/evals/parity/regressions/pr-703.json new file mode 100644 index 0000000000..a88ea581b6 --- /dev/null +++ b/evals/parity/regressions/pr-703.json @@ -0,0 +1,26 @@ +{ + "pr": 703, + "url": "https://github.com/garrytan/gstack/issues/703", + "title": "Write design docs repo-local and read them from the repo first", + "targets": [ + "office-hours", + "plan-ceo-review", + "plan-eng-review", + "plan-devex-review", + "autoplan" + ], + "anchor": "GSTACK2_FIX_703_REPO_LOCAL_DESIGN_DOCS", + "body": "### Repo-local design artifacts\n\nWhen the session produces a design or plan document and the working directory is inside a repository, write it to `docs/designs/.md` in that repository (create `docs/designs/` if needed) and name that path every time the document is presented or approval is requested. A hashed home-directory path is never the thing the user is asked to open. Keep writing the cross-session copy under `\"${GSTACK_HOME:-$HOME/.gstack}\"/projects//` with the existing filename convention — downstream skills, prior-design lookup, and cross-team discovery depend on that store — but the repo-local file is the canonical one the user owns and edits. Outside a repository, the `$GSTACK_HOME` path remains the only copy; print it in full when asking for approval. When reviewing, prefer a repo-local design doc (`docs/designs/`, `docs/plans/`, or an explicitly provided path) over the `$GSTACK_HOME` store whenever both exist.", + "regression": { + "input": { + "in_repository": true, + "artifact": "design-doc" + }, + "expected": { + "canonical_path": "docs/designs/", + "gstack_home_copy": true, + "approval_names_visible_path": true, + "reviewer_prefers": "repo-local" + } + } +} diff --git a/evals/parity/regressions/pr-886.json b/evals/parity/regressions/pr-886.json new file mode 100644 index 0000000000..c9b6961b48 --- /dev/null +++ b/evals/parity/regressions/pr-886.json @@ -0,0 +1,35 @@ +{ + "pr": 886, + "url": "https://github.com/garrytan/gstack/issues/886", + "title": "Scale planning machinery to the printed build scale", + "targets": [ + "office-hours", + "plan-ceo-review", + "plan-eng-review", + "plan-devex-review", + "spec", + "autoplan" + ], + "anchor": "GSTACK2_FIX_886_PROPORTIONAL_PLANNING", + "body": "### Proportional planning for the printed build scale\n\nThe /plan dispatcher prints a `Scale:` header line classified from fifteen build-scale vectors (its Build scale section). This rule authorizes every planning specialist to size its machinery to that scale while keeping every STOP gate and approval boundary; a polite user answering every question is not evidence the full machinery is wanted, and the user can always ask for the complete treatment.\n\n- `session` and `hobby`: batch every question the initial prompt left unanswered into one AskUserQuestion round (two rounds for hobby); skip web or landscape research, outside voices, second opinions, and visual sketches unless the user asks (privacy gates are unchanged whenever they run); cap any adversarial or spec review loop at one iteration; keep the decision artifact near one page with next steps sized in hours (session) or days (hobby), never a phased multi-week roadmap or a distribution plan the user did not ask for.\n- `project`: run the specialist's default workflow, batching question rounds where its source authorizes smart skips; size the roadmap in weeks.\n- `product` and `venture`: the full specialist workflow and its complete question pressure apply; this rule removes nothing.\n- Never run a questioning round merely to classify scale. Classify from the prompt and cheap repository evidence, defaulting unknown vectors low; a specialist's own later questions may raise the scale mid-session, and an upgrade restores the full workflow from that point.\n\nFor office-hours specifically: at session or hobby scale, batch the Phase 2B questions (this refines the one-at-a-time rule, whose pressure exists for startup diagnostics), default-skip the Phase 2.75 landscape search, gate the visual sketch and outside design voices on an explicit ask, and cap the Spec Review Loop at one iteration.", + "regression": { + "input": { + "audience": "self", + "users": "none", + "commercial": "none", + "deployment": "none", + "horizon": "session", + "stakes": "fun", + "extensibility": "fixed" + }, + "expected": { + "scale": "session", + "questions_batched": true, + "question_rounds_max": 1, + "web_search": "on-request", + "outside_voices": "on-request", + "review_iterations_max": 1, + "step_unit": "hours" + } + } +} diff --git a/evals/parity/transcripts/deterministic/ceo-review.json b/evals/parity/transcripts/deterministic/ceo-review.json index dbb54530cc..a80d8eb058 100644 --- a/evals/parity/transcripts/deterministic/ceo-review.json +++ b/evals/parity/transcripts/deterministic/ceo-review.json @@ -95,6 +95,20 @@ "reproduced_defect": "Record only signal-bearing learnings", "regression_fixture": "evals/parity/regressions/pr-2030.json", "explanation": "### Signal-gated learning\n\nPersist a learning only when the interaction contains a useful, reusable signal such as an explicit preference, correction, accepted recommendation, or rejected direction. Track helpful and harmful outcomes separately. Do not manufacture a learning merely because a workflow completed." + }, + { + "classification": "INTENTIONAL_IMPROVEMENT", + "issue_or_pr": "https://github.com/garrytan/gstack/issues/886", + "reproduced_defect": "Scale planning machinery to the printed build scale", + "regression_fixture": "evals/parity/regressions/pr-886.json", + "explanation": "### Proportional planning for the printed build scale\n\nThe /plan dispatcher prints a `Scale:` header line classified from fifteen build-scale vectors (its Build scale section). This rule authorizes every planning specialist to size its machinery to that scale while keeping every STOP gate and approval boundary; a polite user answering every question is not evidence the full machinery is wanted, and the user can always ask for the complete treatment.\n\n- `session` and `hobby`: batch every question the initial prompt left unanswered into one AskUserQuestion round (two rounds for hobby); skip web or landscape research, outside voices, second opinions, and visual sketches unless the user asks (privacy gates are unchanged whenever they run); cap any adversarial or spec review loop at one iteration; keep the decision artifact near one page with next steps sized in hours (session) or days (hobby), never a phased multi-week roadmap or a distribution plan the user did not ask for.\n- `project`: run the specialist's default workflow, batching question rounds where its source authorizes smart skips; size the roadmap in weeks.\n- `product` and `venture`: the full specialist workflow and its complete question pressure apply; this rule removes nothing.\n- Never run a questioning round merely to classify scale. Classify from the prompt and cheap repository evidence, defaulting unknown vectors low; a specialist's own later questions may raise the scale mid-session, and an upgrade restores the full workflow from that point.\n\nFor office-hours specifically: at session or hobby scale, batch the Phase 2B questions (this refines the one-at-a-time rule, whose pressure exists for startup diagnostics), default-skip the Phase 2.75 landscape search, gate the visual sketch and outside design voices on an explicit ask, and cap the Spec Review Loop at one iteration." + }, + { + "classification": "INTENTIONAL_IMPROVEMENT", + "issue_or_pr": "https://github.com/garrytan/gstack/issues/703", + "reproduced_defect": "Write design docs repo-local and read them from the repo first", + "regression_fixture": "evals/parity/regressions/pr-703.json", + "explanation": "### Repo-local design artifacts\n\nWhen the session produces a design or plan document and the working directory is inside a repository, write it to `docs/designs/.md` in that repository (create `docs/designs/` if needed) and name that path every time the document is presented or approval is requested. A hashed home-directory path is never the thing the user is asked to open. Keep writing the cross-session copy under `\"${GSTACK_HOME:-$HOME/.gstack}\"/projects//` with the existing filename convention — downstream skills, prior-design lookup, and cross-team discovery depend on that store — but the repo-local file is the canonical one the user owns and edits. Outside a repository, the `$GSTACK_HOME` path remains the only copy; print it in full when asking for approval. When reviewing, prefer a repo-local design doc (`docs/designs/`, `docs/plans/`, or an explicitly provided path) over the `$GSTACK_HOME` store whenever both exist." } ] } diff --git a/evals/parity/transcripts/deterministic/dx-review.json b/evals/parity/transcripts/deterministic/dx-review.json index 8b380468a0..90fc8ac7e6 100644 --- a/evals/parity/transcripts/deterministic/dx-review.json +++ b/evals/parity/transcripts/deterministic/dx-review.json @@ -96,6 +96,20 @@ "reproduced_defect": "Record only signal-bearing learnings", "regression_fixture": "evals/parity/regressions/pr-2030.json", "explanation": "### Signal-gated learning\n\nPersist a learning only when the interaction contains a useful, reusable signal such as an explicit preference, correction, accepted recommendation, or rejected direction. Track helpful and harmful outcomes separately. Do not manufacture a learning merely because a workflow completed." + }, + { + "classification": "INTENTIONAL_IMPROVEMENT", + "issue_or_pr": "https://github.com/garrytan/gstack/issues/886", + "reproduced_defect": "Scale planning machinery to the printed build scale", + "regression_fixture": "evals/parity/regressions/pr-886.json", + "explanation": "### Proportional planning for the printed build scale\n\nThe /plan dispatcher prints a `Scale:` header line classified from fifteen build-scale vectors (its Build scale section). This rule authorizes every planning specialist to size its machinery to that scale while keeping every STOP gate and approval boundary; a polite user answering every question is not evidence the full machinery is wanted, and the user can always ask for the complete treatment.\n\n- `session` and `hobby`: batch every question the initial prompt left unanswered into one AskUserQuestion round (two rounds for hobby); skip web or landscape research, outside voices, second opinions, and visual sketches unless the user asks (privacy gates are unchanged whenever they run); cap any adversarial or spec review loop at one iteration; keep the decision artifact near one page with next steps sized in hours (session) or days (hobby), never a phased multi-week roadmap or a distribution plan the user did not ask for.\n- `project`: run the specialist's default workflow, batching question rounds where its source authorizes smart skips; size the roadmap in weeks.\n- `product` and `venture`: the full specialist workflow and its complete question pressure apply; this rule removes nothing.\n- Never run a questioning round merely to classify scale. Classify from the prompt and cheap repository evidence, defaulting unknown vectors low; a specialist's own later questions may raise the scale mid-session, and an upgrade restores the full workflow from that point.\n\nFor office-hours specifically: at session or hobby scale, batch the Phase 2B questions (this refines the one-at-a-time rule, whose pressure exists for startup diagnostics), default-skip the Phase 2.75 landscape search, gate the visual sketch and outside design voices on an explicit ask, and cap the Spec Review Loop at one iteration." + }, + { + "classification": "INTENTIONAL_IMPROVEMENT", + "issue_or_pr": "https://github.com/garrytan/gstack/issues/703", + "reproduced_defect": "Write design docs repo-local and read them from the repo first", + "regression_fixture": "evals/parity/regressions/pr-703.json", + "explanation": "### Repo-local design artifacts\n\nWhen the session produces a design or plan document and the working directory is inside a repository, write it to `docs/designs/.md` in that repository (create `docs/designs/` if needed) and name that path every time the document is presented or approval is requested. A hashed home-directory path is never the thing the user is asked to open. Keep writing the cross-session copy under `\"${GSTACK_HOME:-$HOME/.gstack}\"/projects//` with the existing filename convention — downstream skills, prior-design lookup, and cross-team discovery depend on that store — but the repo-local file is the canonical one the user owns and edits. Outside a repository, the `$GSTACK_HOME` path remains the only copy; print it in full when asking for approval. When reviewing, prefer a repo-local design doc (`docs/designs/`, `docs/plans/`, or an explicitly provided path) over the `$GSTACK_HOME` store whenever both exist." } ] } diff --git a/evals/parity/transcripts/deterministic/engineering-review.json b/evals/parity/transcripts/deterministic/engineering-review.json index 9ff7131d33..181da792e4 100644 --- a/evals/parity/transcripts/deterministic/engineering-review.json +++ b/evals/parity/transcripts/deterministic/engineering-review.json @@ -109,6 +109,20 @@ "reproduced_defect": "Run a pre-mortem before challenging scope", "regression_fixture": "evals/parity/regressions/pr-592.json", "explanation": "### Pre-mortem before scope challenge\n\nBefore reviewing anything, run a pre-mortem: it is three months later and this plan failed, name the top three reasons why. Reason from production reality, not the plan's internal logic, and name concrete failure modes (data loss, performance cliff, security hole, team confusion), not abstract worries. Present those three failure modes to the user before the scope challenge, which follows the pre-mortem rather than opening the review." + }, + { + "classification": "INTENTIONAL_IMPROVEMENT", + "issue_or_pr": "https://github.com/garrytan/gstack/issues/886", + "reproduced_defect": "Scale planning machinery to the printed build scale", + "regression_fixture": "evals/parity/regressions/pr-886.json", + "explanation": "### Proportional planning for the printed build scale\n\nThe /plan dispatcher prints a `Scale:` header line classified from fifteen build-scale vectors (its Build scale section). This rule authorizes every planning specialist to size its machinery to that scale while keeping every STOP gate and approval boundary; a polite user answering every question is not evidence the full machinery is wanted, and the user can always ask for the complete treatment.\n\n- `session` and `hobby`: batch every question the initial prompt left unanswered into one AskUserQuestion round (two rounds for hobby); skip web or landscape research, outside voices, second opinions, and visual sketches unless the user asks (privacy gates are unchanged whenever they run); cap any adversarial or spec review loop at one iteration; keep the decision artifact near one page with next steps sized in hours (session) or days (hobby), never a phased multi-week roadmap or a distribution plan the user did not ask for.\n- `project`: run the specialist's default workflow, batching question rounds where its source authorizes smart skips; size the roadmap in weeks.\n- `product` and `venture`: the full specialist workflow and its complete question pressure apply; this rule removes nothing.\n- Never run a questioning round merely to classify scale. Classify from the prompt and cheap repository evidence, defaulting unknown vectors low; a specialist's own later questions may raise the scale mid-session, and an upgrade restores the full workflow from that point.\n\nFor office-hours specifically: at session or hobby scale, batch the Phase 2B questions (this refines the one-at-a-time rule, whose pressure exists for startup diagnostics), default-skip the Phase 2.75 landscape search, gate the visual sketch and outside design voices on an explicit ask, and cap the Spec Review Loop at one iteration." + }, + { + "classification": "INTENTIONAL_IMPROVEMENT", + "issue_or_pr": "https://github.com/garrytan/gstack/issues/703", + "reproduced_defect": "Write design docs repo-local and read them from the repo first", + "regression_fixture": "evals/parity/regressions/pr-703.json", + "explanation": "### Repo-local design artifacts\n\nWhen the session produces a design or plan document and the working directory is inside a repository, write it to `docs/designs/.md` in that repository (create `docs/designs/` if needed) and name that path every time the document is presented or approval is requested. A hashed home-directory path is never the thing the user is asked to open. Keep writing the cross-session copy under `\"${GSTACK_HOME:-$HOME/.gstack}\"/projects//` with the existing filename convention — downstream skills, prior-design lookup, and cross-team discovery depend on that store — but the repo-local file is the canonical one the user owns and edits. Outside a repository, the `$GSTACK_HOME` path remains the only copy; print it in full when asking for approval. When reviewing, prefer a repo-local design doc (`docs/designs/`, `docs/plans/`, or an explicitly provided path) over the `$GSTACK_HOME` store whenever both exist." } ] } diff --git a/evals/parity/transcripts/deterministic/office-hours.json b/evals/parity/transcripts/deterministic/office-hours.json index 2dfa0becfa..54fa1e7516 100644 --- a/evals/parity/transcripts/deterministic/office-hours.json +++ b/evals/parity/transcripts/deterministic/office-hours.json @@ -109,6 +109,20 @@ "reproduced_defect": "Print the design doc inline before the approval gate", "regression_fixture": "evals/parity/regressions/pr-1116.json", "explanation": "### Inline design doc at the approval gate\n\nAt the Phase 5 approval gate, print the full design-doc body as direct assistant text before the Approve/Revise/Start-over AskUserQuestion. Do not point the user at the file path and do not rely on a `Bash cat` or `Read` tool call to display it: tool outputs are frequently collapsed in the Claude Code UI, which leaves the user approving a document they cannot see. The assistant message is the one surface guaranteed to render, so emit a short preamble naming the saved path followed by the verbatim document body, then ask for approval." + }, + { + "classification": "INTENTIONAL_IMPROVEMENT", + "issue_or_pr": "https://github.com/garrytan/gstack/issues/886", + "reproduced_defect": "Scale planning machinery to the printed build scale", + "regression_fixture": "evals/parity/regressions/pr-886.json", + "explanation": "### Proportional planning for the printed build scale\n\nThe /plan dispatcher prints a `Scale:` header line classified from fifteen build-scale vectors (its Build scale section). This rule authorizes every planning specialist to size its machinery to that scale while keeping every STOP gate and approval boundary; a polite user answering every question is not evidence the full machinery is wanted, and the user can always ask for the complete treatment.\n\n- `session` and `hobby`: batch every question the initial prompt left unanswered into one AskUserQuestion round (two rounds for hobby); skip web or landscape research, outside voices, second opinions, and visual sketches unless the user asks (privacy gates are unchanged whenever they run); cap any adversarial or spec review loop at one iteration; keep the decision artifact near one page with next steps sized in hours (session) or days (hobby), never a phased multi-week roadmap or a distribution plan the user did not ask for.\n- `project`: run the specialist's default workflow, batching question rounds where its source authorizes smart skips; size the roadmap in weeks.\n- `product` and `venture`: the full specialist workflow and its complete question pressure apply; this rule removes nothing.\n- Never run a questioning round merely to classify scale. Classify from the prompt and cheap repository evidence, defaulting unknown vectors low; a specialist's own later questions may raise the scale mid-session, and an upgrade restores the full workflow from that point.\n\nFor office-hours specifically: at session or hobby scale, batch the Phase 2B questions (this refines the one-at-a-time rule, whose pressure exists for startup diagnostics), default-skip the Phase 2.75 landscape search, gate the visual sketch and outside design voices on an explicit ask, and cap the Spec Review Loop at one iteration." + }, + { + "classification": "INTENTIONAL_IMPROVEMENT", + "issue_or_pr": "https://github.com/garrytan/gstack/issues/703", + "reproduced_defect": "Write design docs repo-local and read them from the repo first", + "regression_fixture": "evals/parity/regressions/pr-703.json", + "explanation": "### Repo-local design artifacts\n\nWhen the session produces a design or plan document and the working directory is inside a repository, write it to `docs/designs/.md` in that repository (create `docs/designs/` if needed) and name that path every time the document is presented or approval is requested. A hashed home-directory path is never the thing the user is asked to open. Keep writing the cross-session copy under `\"${GSTACK_HOME:-$HOME/.gstack}\"/projects//` with the existing filename convention — downstream skills, prior-design lookup, and cross-team discovery depend on that store — but the repo-local file is the canonical one the user owns and edits. Outside a repository, the `$GSTACK_HOME` path remains the only copy; print it in full when asking for approval. When reviewing, prefer a repo-local design doc (`docs/designs/`, `docs/plans/`, or an explicitly provided path) over the `$GSTACK_HOME` store whenever both exist." } ] } diff --git a/evals/parity/transcripts/deterministic/specification.json b/evals/parity/transcripts/deterministic/specification.json index 9c47b2d089..ae195eade8 100644 --- a/evals/parity/transcripts/deterministic/specification.json +++ b/evals/parity/transcripts/deterministic/specification.json @@ -88,6 +88,13 @@ "reproduced_defect": "Match the user language", "regression_fixture": "evals/parity/regressions/pr-679.json", "explanation": "### User-language rule\n\nWrite questions, progress updates, reports, and artifacts in the language used by the user. Source material, code identifiers, commands, and quotations may remain in their original language when translating them would reduce accuracy." + }, + { + "classification": "INTENTIONAL_IMPROVEMENT", + "issue_or_pr": "https://github.com/garrytan/gstack/issues/886", + "reproduced_defect": "Scale planning machinery to the printed build scale", + "regression_fixture": "evals/parity/regressions/pr-886.json", + "explanation": "### Proportional planning for the printed build scale\n\nThe /plan dispatcher prints a `Scale:` header line classified from fifteen build-scale vectors (its Build scale section). This rule authorizes every planning specialist to size its machinery to that scale while keeping every STOP gate and approval boundary; a polite user answering every question is not evidence the full machinery is wanted, and the user can always ask for the complete treatment.\n\n- `session` and `hobby`: batch every question the initial prompt left unanswered into one AskUserQuestion round (two rounds for hobby); skip web or landscape research, outside voices, second opinions, and visual sketches unless the user asks (privacy gates are unchanged whenever they run); cap any adversarial or spec review loop at one iteration; keep the decision artifact near one page with next steps sized in hours (session) or days (hobby), never a phased multi-week roadmap or a distribution plan the user did not ask for.\n- `project`: run the specialist's default workflow, batching question rounds where its source authorizes smart skips; size the roadmap in weeks.\n- `product` and `venture`: the full specialist workflow and its complete question pressure apply; this rule removes nothing.\n- Never run a questioning round merely to classify scale. Classify from the prompt and cheap repository evidence, defaulting unknown vectors low; a specialist's own later questions may raise the scale mid-session, and an upgrade restores the full workflow from that point.\n\nFor office-hours specifically: at session or hobby scale, batch the Phase 2B questions (this refines the one-at-a-time rule, whose pressure exists for startup diagnostics), default-skip the Phase 2.75 landscape search, gate the visual sketch and outside design voices on an explicit ask, and cap the Spec Review Loop at one iteration." } ] } diff --git a/evals/parity/transcripts/policy-units.json b/evals/parity/transcripts/policy-units.json index 6afea0e7c2..b94d7a1daf 100644 --- a/evals/parity/transcripts/policy-units.json +++ b/evals/parity/transcripts/policy-units.json @@ -426,7 +426,7 @@ "prompt_sha256": "51b7d53bc342e8632e34ae31a167cbde568ab5ee2a6dd2ccc980583a30604164", "semantic_attempt_sha256": "06f77b27c9bd360562655b23ca00a0dd021bdb14ebaaf3d836845e4e0cb43d68" }, - "policy_sha256": "43d5cbbf88ed4f9afa3e7af214b4aa8c3a764a7006d76a864344df05d1f76392", + "policy_sha256": "7436f2bd70592738eda54ae9666d52ae909a4d44c06297e6486afda124cdbf41", "policy_present": true, "prompt_is_not_authority_input": true, "verdict": "PASS" diff --git a/package.json b/package.json index aa3f6e575a..75c289fd44 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "gstack", - "version": "1.60.1.0", + "version": "1.61.0.0", "description": "GStack 2 — six portable Agent Skills with an optional host-neutral runtime.", "license": "MIT", "type": "module", diff --git a/scripts/gstack2/bug-fix-overlays.ts b/scripts/gstack2/bug-fix-overlays.ts index 031bb4893a..d178738989 100644 --- a/scripts/gstack2/bug-fix-overlays.ts +++ b/scripts/gstack2/bug-fix-overlays.ts @@ -342,6 +342,41 @@ At the Phase 5 approval gate, print the full design-doc body as direct assistant expected: { print_doc_inline: true, before_approval_auq: true }, }, }, + { + pr: 886, + url: 'https://github.com/garrytan/gstack/issues/886', + title: 'Scale planning machinery to the printed build scale', + targets: ['office-hours', 'plan-ceo-review', 'plan-eng-review', 'plan-devex-review', 'spec', 'autoplan'], + anchor: 'GSTACK2_FIX_886_PROPORTIONAL_PLANNING', + body: `### Proportional planning for the printed build scale + +The /plan dispatcher prints a \`Scale:\` header line classified from fifteen build-scale vectors (its Build scale section). This rule authorizes every planning specialist to size its machinery to that scale while keeping every STOP gate and approval boundary; a polite user answering every question is not evidence the full machinery is wanted, and the user can always ask for the complete treatment. + +- \`session\` and \`hobby\`: batch every question the initial prompt left unanswered into one AskUserQuestion round (two rounds for hobby); skip web or landscape research, outside voices, second opinions, and visual sketches unless the user asks (privacy gates are unchanged whenever they run); cap any adversarial or spec review loop at one iteration; keep the decision artifact near one page with next steps sized in hours (session) or days (hobby), never a phased multi-week roadmap or a distribution plan the user did not ask for. +- \`project\`: run the specialist's default workflow, batching question rounds where its source authorizes smart skips; size the roadmap in weeks. +- \`product\` and \`venture\`: the full specialist workflow and its complete question pressure apply; this rule removes nothing. +- Never run a questioning round merely to classify scale. Classify from the prompt and cheap repository evidence, defaulting unknown vectors low; a specialist's own later questions may raise the scale mid-session, and an upgrade restores the full workflow from that point. + +For office-hours specifically: at session or hobby scale, batch the Phase 2B questions (this refines the one-at-a-time rule, whose pressure exists for startup diagnostics), default-skip the Phase 2.75 landscape search, gate the visual sketch and outside design voices on an explicit ask, and cap the Spec Review Loop at one iteration.`, + regression: { + input: { audience: 'self', users: 'none', commercial: 'none', deployment: 'none', horizon: 'session', stakes: 'fun', extensibility: 'fixed' }, + expected: { scale: 'session', questions_batched: true, question_rounds_max: 1, web_search: 'on-request', outside_voices: 'on-request', review_iterations_max: 1, step_unit: 'hours' }, + }, + }, + { + pr: 703, + url: 'https://github.com/garrytan/gstack/issues/703', + title: 'Write design docs repo-local and read them from the repo first', + targets: ['office-hours', 'plan-ceo-review', 'plan-eng-review', 'plan-devex-review', 'autoplan'], + anchor: 'GSTACK2_FIX_703_REPO_LOCAL_DESIGN_DOCS', + body: `### Repo-local design artifacts + +When the session produces a design or plan document and the working directory is inside a repository, write it to \`docs/designs/.md\` in that repository (create \`docs/designs/\` if needed) and name that path every time the document is presented or approval is requested. A hashed home-directory path is never the thing the user is asked to open. Keep writing the cross-session copy under \`"\${GSTACK_HOME:-\$HOME/.gstack}"/projects//\` with the existing filename convention — downstream skills, prior-design lookup, and cross-team discovery depend on that store — but the repo-local file is the canonical one the user owns and edits. Outside a repository, the \`\$GSTACK_HOME\` path remains the only copy; print it in full when asking for approval. When reviewing, prefer a repo-local design doc (\`docs/designs/\`, \`docs/plans/\`, or an explicitly provided path) over the \`\$GSTACK_HOME\` store whenever both exist.`, + regression: { + input: { in_repository: true, artifact: 'design-doc' }, + expected: { canonical_path: 'docs/designs/', gstack_home_copy: true, approval_names_visible_path: true, reviewer_prefers: 'repo-local' }, + }, + }, { pr: 452, url: 'https://github.com/garrytan/gstack/pull/452', @@ -531,6 +566,50 @@ 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 703: { + const inRepo = input.in_repository === true; + return { + canonical_path: inRepo ? 'docs/designs/' : 'gstack-home-projects-store', + gstack_home_copy: true, + approval_names_visible_path: true, + reviewer_prefers: 'repo-local', + }; + } + case 886: { + const ranks: Record> = { + audience: { self: 0, friends: 1, team: 2, public: 3 }, + users: { none: 0, handful: 1, many: 3 }, + commercial: { none: 0, maybe: 2, core: 4 }, + deployment: { none: 0, local: 0, hosted: 2, production: 3 }, + horizon: { session: 0, days: 1, weeks: 2, months: 4 }, + maintenance: { throwaway: 0, kept: 1, maintained: 2 }, + integration: { standalone: 0, 'consumes-apis': 1, 'exposes-apis': 3, 'multi-service': 3 }, + extensibility: { fixed: 0, configurable: 2, 'customizable-platform': 4 }, + data: { none: 0, personal: 2, regulated: 4 }, + stakes: { fun: 0, annoyance: 1, money: 3, safety: 4 }, + team: { solo: 0, few: 2, org: 3 }, + codebase: { greenfield: 0, existing: 1, 'legacy-production': 3 }, + reversibility: { discardable: 0, breaking: 3 }, + distribution: { private: 0, shared: 1, published: 3 }, + compliance: { none: 0, some: 2, audited: 4 }, + }; + // Highest tier any vector demands wins; unknown vectors default low. + const rank = Object.entries(ranks).reduce( + (max, [vector, levels]) => Math.max(max, levels[String(input[vector] ?? '')] ?? 0), + 0, + ); + const scale = ['session', 'hobby', 'project', 'product', 'venture'][rank]; + const small = rank <= 1; + return { + scale, + questions_batched: rank <= 2, + question_rounds_max: small ? rank + 1 : null, + web_search: small ? 'on-request' : 'privacy-gated-offer', + outside_voices: small ? 'on-request' : 'offer', + review_iterations_max: small ? 1 : 3, + step_unit: ['hours', 'days', 'weeks', 'stage-appropriate', 'stage-appropriate'][rank], + }; + } default: throw new Error(`No executable GStack 2 regression evaluator for PR #${pr}`); } diff --git a/scripts/gstack2/generate-skill-tree.ts b/scripts/gstack2/generate-skill-tree.ts index f80fbb7a45..760c55283e 100644 --- a/scripts/gstack2/generate-skill-tree.ts +++ b/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 !== 25) throw new Error(`Expected 25 upstream judgment overlays, found ${BUG_FIX_OVERLAYS.length}`); + if (BUG_FIX_OVERLAYS.length !== 27) throw new Error(`Expected 27 upstream judgment overlays, found ${BUG_FIX_OVERLAYS.length}`); } function toc(body: string): string { @@ -159,7 +159,7 @@ function renderModule(assignment: SourceAssignment): { content: string; renderSh : overlays.length ? 'BUG_FIX' : 'JUDGMENT_PRESERVING_CARVE'; const overlayText = overlays.map((overlay) => [ ``, - `## Upstream judgment port: PR #${overlay.pr}`, + `## Upstream judgment port: ${overlay.url.includes('/issues/') ? 'issue' : 'PR'} #${overlay.pr}`, '', `[${overlay.title}](${overlay.url})`, '', @@ -203,7 +203,23 @@ function rootSkill(dispatcher: DispatcherDefinition): string { ? '\n9. When `system-functional` is active, read `references/SYSTEM-FUNCTIONAL.md` completely and execute it alongside the selected preserved specialists.\n' : dispatcher.name === 'ship' ? '\n9. Before push, PR creation/update, merge, deploy, rollback, release publication, or external notification, read `references/EXTERNAL-EFFECTS.md` and execute the action through its durable state wrapper.\n' - : ''; + : dispatcher.name === 'plan' + ? '\n9. Classify the Scale header line from the Build scale section before any questioning begins. Every planning specialist applies its proportional-planning judgment port to that scale.\n' + : ''; + const scaleLine = dispatcher.name === 'plan' + ? 'Scale: \n' + : ''; + const buildScale = dispatcher.name === 'plan' + ? ` +## Build scale + +Classify the request on fifteen scale vectors before any questioning begins, from the prompt and cheap repository evidence only. Never run a questioning round merely to classify scale. Default unknown vectors to the low end; the specialist's own workflow raises the scale naturally when answers reveal more (builder talk turning into startup talk upgrades mid-session). + +Vectors: audience (self → friends/team → public), expected users (none → handful → many), commercial intent (none → maybe → core), deployment target (none/local → hosted → production), time horizon (one sitting → days → weeks → months+), maintenance expectation (throwaway → kept → maintained), integration surface (standalone → consumes APIs → exposes APIs/multi-service), extensibility ask (fixed → configurable → customizable platform), data sensitivity (none → personal → regulated), failure stakes (lost fun → annoyance → money/trust/safety), team (solo → few → org), codebase (greenfield → existing repo → legacy production), reversibility (discardable → migrations/breaking changes), distribution (private → shared → published), compliance (none → some → audited). + +The highest tier any vector demands wins: \`session\` (all vectors low — one sitting, for fun, self only), \`hobby\` (kept personal tool, days), \`project\` (shared or in a real repo, weeks), \`product\` (external users, hosted, revenue intent), \`venture\` (startup ambition, platform/API surface, team, months+). "A cool space animation in my terminal" is session-scale. "A startup with customizable APIs" is venture-scale. Print the result on the header's Scale line with the two or three vectors that decided it. +` + : ''; return `--- name: ${dispatcher.name} @@ -223,7 +239,7 @@ Before any substantive output, print these exact labels in this exact order. Res Target: Mode: Depth: -Mutation: +${scaleLine}Mutation: Active modules: Skipped modules: Web context: @@ -239,7 +255,7 @@ Web context: 6. Preserve report-only versus mutation boundaries. Missing mutation authorization fails closed: do not edit merely because a specialist can fix. Commits, pushes, PRs, merges, deploys, messages, and other external mutations still require affirmative authority from the user. 7. Match the user's language. Keep code identifiers, commands, and source quotations original when translation would reduce accuracy. 8. At exit, report completed artifacts, evidence, unresolved decisions, skipped modules with reasons, and any blocked gate. -${supplemental} +${supplemental}${buildScale} ## Top-level modes @@ -742,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 25 upstream PRs and its regression fixture. +- \`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. - Asset relocation is byte-for-byte from the pinned Git blob and is indexed per tree. `; } @@ -763,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, 25 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, 27 regression ports, and **${assetCount} assets**. The suite verifies: @@ -997,12 +1013,12 @@ function runCheck(): void { } catch { disk = null; } - if (!disk) drift.push(`missing ${path.relative(ROOT, abs)}`); - else if (!disk.equals(bytes)) drift.push(`stale ${path.relative(ROOT, abs)}`); + if (!disk) drift.push(`missing ${normalizeRepositoryPath(path.relative(ROOT, abs))}`); + else if (!disk.equals(bytes)) drift.push(`stale ${normalizeRepositoryPath(path.relative(ROOT, abs))}`); } for (const root of cleaned) { for (const abs of diskFiles(root)) { - if (!files.has(abs)) drift.push(`orphaned ${path.relative(ROOT, abs)}`); + if (!files.has(abs)) drift.push(`orphaned ${normalizeRepositoryPath(path.relative(ROOT, abs))}`); } } drift.sort(); diff --git a/scripts/gstack2/render-legacy.ts b/scripts/gstack2/render-legacy.ts index fb4cfc6033..f5e08d3945 100644 --- a/scripts/gstack2/render-legacy.ts +++ b/scripts/gstack2/render-legacy.ts @@ -32,13 +32,29 @@ export function legacyRelativePath(source: string): string { return repositoryRelativePath(legacyTemplatePath(source)); } +let pinnedBaseFetchAttempted = false; + function pinnedText(relativePath: string): string { - const result = Bun.spawnSync({ + const show = () => Bun.spawnSync({ cmd: ['git', 'show', pinnedRevisionPath(relativePath)], cwd: ROOT, stdout: 'pipe', stderr: 'pipe', }); + let result = show(); + if (result.exitCode !== 0 && !pinnedBaseFetchAttempted) { + // CI and shallow checkouts only fetch the PR refs; GSTACK2_BASE_SHA is + // reachable from codex/* branches only, so its objects may be absent. + // A depth-1 fetch of the pinned sha restores git show for every caller. + pinnedBaseFetchAttempted = true; + Bun.spawnSync({ + cmd: ['git', 'fetch', '--no-tags', '--depth=1', 'origin', GSTACK2_BASE_SHA], + cwd: ROOT, + stdout: 'pipe', + stderr: 'pipe', + }); + result = show(); + } if (result.exitCode !== 0) throw new Error(`Unable to read ${relativePath} at ${GSTACK2_BASE_SHA}: ${result.stderr.toString()}`); return result.stdout.toString(); } diff --git a/scripts/gstack2/run-parity.ts b/scripts/gstack2/run-parity.ts index 252ce95197..e2eebba959 100644 --- a/scripts/gstack2/run-parity.ts +++ b/scripts/gstack2/run-parity.ts @@ -17,8 +17,12 @@ const ALLOWED_DISPOSITIONS = new Set(['VERBATIM_PORT', 'MECHANICAL_PORT', 'JUDGM // accounted for the 16 lazy-section checks; the remaining 136 cover runtime // contracts, retired-invocation guards, and generated package closure. Porting // six more upstream judgment overlays (16 -> 22) added 30 checks. Three more -// Tier-2 overlays (22 -> 25) added 15 checks (5 per overlay). -export const EXPECTED_PARITY_CHECKS = 4881; +// Tier-2 overlays (22 -> 25) added 15 checks (5 per overlay). The +// 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; function sha256(value: string | Uint8Array): string { return createHash('sha256').update(value).digest('hex'); @@ -253,8 +257,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 === 25, `Expected 25 regression definitions; got ${BUG_FIX_OVERLAYS.length}`); - check(files(path.join(ROOT, 'evals', 'parity', 'regressions'), '.json').length === 25, 'Generated regression fixture count is not 25'); + 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'); 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`); diff --git a/skills/plan/SKILL.md b/skills/plan/SKILL.md index 8c06285b8c..36452e7f72 100644 --- a/skills/plan/SKILL.md +++ b/skills/plan/SKILL.md @@ -16,6 +16,7 @@ Before any substantive output, print these exact labels in this exact order. Res Target: Mode: Depth: +Scale: Mutation: Active modules: Skipped modules: @@ -33,6 +34,16 @@ Web context: 7. Match the user's language. Keep code identifiers, commands, and source quotations original when translation would reduce accuracy. 8. At exit, report completed artifacts, evidence, unresolved decisions, skipped modules with reasons, and any blocked gate. +9. Classify the Scale header line from the Build scale section before any questioning begins. Every planning specialist applies its proportional-planning judgment port to that scale. + +## Build scale + +Classify the request on fifteen scale vectors before any questioning begins, from the prompt and cheap repository evidence only. Never run a questioning round merely to classify scale. Default unknown vectors to the low end; the specialist's own workflow raises the scale naturally when answers reveal more (builder talk turning into startup talk upgrades mid-session). + +Vectors: audience (self → friends/team → public), expected users (none → handful → many), commercial intent (none → maybe → core), deployment target (none/local → hosted → production), time horizon (one sitting → days → weeks → months+), maintenance expectation (throwaway → kept → maintained), integration surface (standalone → consumes APIs → exposes APIs/multi-service), extensibility ask (fixed → configurable → customizable platform), data sensitivity (none → personal → regulated), failure stakes (lost fun → annoyance → money/trust/safety), team (solo → few → org), codebase (greenfield → existing repo → legacy production), reversibility (discardable → migrations/breaking changes), distribution (private → shared → published), compliance (none → some → audited). + +The highest tier any vector demands wins: `session` (all vectors low — one sitting, for fun, self only), `hobby` (kept personal tool, days), `project` (shared or in a real repo, weeks), `product` (external users, hosted, revenue intent), `venture` (startup ambition, platform/API surface, team, months+). "A cool space animation in my terminal" is session-scale. "A startup with customizable APIs" is venture-scale. Print the result on the header's Scale line with the two or three vectors that decided it. + ## Top-level modes diff --git a/skills/plan/references/legacy/autoplan.md b/skills/plan/references/legacy/autoplan.md index d99331bc21..053c81f175 100644 --- a/skills/plan/references/legacy/autoplan.md +++ b/skills/plan/references/legacy/autoplan.md @@ -1088,3 +1088,30 @@ Before design and DX phases, print the detected scope signals and counts that dr When only one model produced a review row, label it **Claude-only** or **Codex-only** and print a visible single-voice banner. Never describe a one-model result as consensus, agreement, or cross-model validation. + + +## Upstream judgment port: issue #886 + +[Scale planning machinery to the printed build scale](https://github.com/garrytan/gstack/issues/886) + +### Proportional planning for the printed build scale + +The /plan dispatcher prints a `Scale:` header line classified from fifteen build-scale vectors (its Build scale section). This rule authorizes every planning specialist to size its machinery to that scale while keeping every STOP gate and approval boundary; a polite user answering every question is not evidence the full machinery is wanted, and the user can always ask for the complete treatment. + +- `session` and `hobby`: batch every question the initial prompt left unanswered into one AskUserQuestion round (two rounds for hobby); skip web or landscape research, outside voices, second opinions, and visual sketches unless the user asks (privacy gates are unchanged whenever they run); cap any adversarial or spec review loop at one iteration; keep the decision artifact near one page with next steps sized in hours (session) or days (hobby), never a phased multi-week roadmap or a distribution plan the user did not ask for. +- `project`: run the specialist's default workflow, batching question rounds where its source authorizes smart skips; size the roadmap in weeks. +- `product` and `venture`: the full specialist workflow and its complete question pressure apply; this rule removes nothing. +- Never run a questioning round merely to classify scale. Classify from the prompt and cheap repository evidence, defaulting unknown vectors low; a specialist's own later questions may raise the scale mid-session, and an upgrade restores the full workflow from that point. + +For office-hours specifically: at session or hobby scale, batch the Phase 2B questions (this refines the one-at-a-time rule, whose pressure exists for startup diagnostics), default-skip the Phase 2.75 landscape search, gate the visual sketch and outside design voices on an explicit ask, and cap the Spec Review Loop at one iteration. + + + +## Upstream judgment port: issue #703 + +[Write design docs repo-local and read them from the repo first](https://github.com/garrytan/gstack/issues/703) + +### Repo-local design artifacts + +When the session produces a design or plan document and the working directory is inside a repository, write it to `docs/designs/.md` in that repository (create `docs/designs/` if needed) and name that path every time the document is presented or approval is requested. A hashed home-directory path is never the thing the user is asked to open. Keep writing the cross-session copy under `"${GSTACK_HOME:-$HOME/.gstack}"/projects//` with the existing filename convention — downstream skills, prior-design lookup, and cross-team discovery depend on that store — but the repo-local file is the canonical one the user owns and edits. Outside a repository, the `$GSTACK_HOME` path remains the only copy; print it in full when asking for approval. When reviewing, prefer a repo-local design doc (`docs/designs/`, `docs/plans/`, or an explicitly provided path) over the `$GSTACK_HOME` store whenever both exist. + diff --git a/skills/plan/references/legacy/office-hours.md b/skills/plan/references/legacy/office-hours.md index 4909fd0501..1ce41a132e 100644 --- a/skills/plan/references/legacy/office-hours.md +++ b/skills/plan/references/legacy/office-hours.md @@ -770,3 +770,30 @@ The design doc file is the artifact of this session. Before the telemetry block At the Phase 5 approval gate, print the full design-doc body as direct assistant text before the Approve/Revise/Start-over AskUserQuestion. Do not point the user at the file path and do not rely on a `Bash cat` or `Read` tool call to display it: tool outputs are frequently collapsed in the Claude Code UI, which leaves the user approving a document they cannot see. The assistant message is the one surface guaranteed to render, so emit a short preamble naming the saved path followed by the verbatim document body, then ask for approval. + + +## Upstream judgment port: issue #886 + +[Scale planning machinery to the printed build scale](https://github.com/garrytan/gstack/issues/886) + +### Proportional planning for the printed build scale + +The /plan dispatcher prints a `Scale:` header line classified from fifteen build-scale vectors (its Build scale section). This rule authorizes every planning specialist to size its machinery to that scale while keeping every STOP gate and approval boundary; a polite user answering every question is not evidence the full machinery is wanted, and the user can always ask for the complete treatment. + +- `session` and `hobby`: batch every question the initial prompt left unanswered into one AskUserQuestion round (two rounds for hobby); skip web or landscape research, outside voices, second opinions, and visual sketches unless the user asks (privacy gates are unchanged whenever they run); cap any adversarial or spec review loop at one iteration; keep the decision artifact near one page with next steps sized in hours (session) or days (hobby), never a phased multi-week roadmap or a distribution plan the user did not ask for. +- `project`: run the specialist's default workflow, batching question rounds where its source authorizes smart skips; size the roadmap in weeks. +- `product` and `venture`: the full specialist workflow and its complete question pressure apply; this rule removes nothing. +- Never run a questioning round merely to classify scale. Classify from the prompt and cheap repository evidence, defaulting unknown vectors low; a specialist's own later questions may raise the scale mid-session, and an upgrade restores the full workflow from that point. + +For office-hours specifically: at session or hobby scale, batch the Phase 2B questions (this refines the one-at-a-time rule, whose pressure exists for startup diagnostics), default-skip the Phase 2.75 landscape search, gate the visual sketch and outside design voices on an explicit ask, and cap the Spec Review Loop at one iteration. + + + +## Upstream judgment port: issue #703 + +[Write design docs repo-local and read them from the repo first](https://github.com/garrytan/gstack/issues/703) + +### Repo-local design artifacts + +When the session produces a design or plan document and the working directory is inside a repository, write it to `docs/designs/.md` in that repository (create `docs/designs/` if needed) and name that path every time the document is presented or approval is requested. A hashed home-directory path is never the thing the user is asked to open. Keep writing the cross-session copy under `"${GSTACK_HOME:-$HOME/.gstack}"/projects//` with the existing filename convention — downstream skills, prior-design lookup, and cross-team discovery depend on that store — but the repo-local file is the canonical one the user owns and edits. Outside a repository, the `$GSTACK_HOME` path remains the only copy; print it in full when asking for approval. When reviewing, prefer a repo-local design doc (`docs/designs/`, `docs/plans/`, or an explicitly provided path) over the `$GSTACK_HOME` store whenever both exist. + diff --git a/skills/plan/references/legacy/plan-ceo-review.md b/skills/plan/references/legacy/plan-ceo-review.md index 6be0123797..9c63956c28 100644 --- a/skills/plan/references/legacy/plan-ceo-review.md +++ b/skills/plan/references/legacy/plan-ceo-review.md @@ -647,3 +647,30 @@ Write questions, progress updates, reports, and artifacts in the language used b Persist a learning only when the interaction contains a useful, reusable signal such as an explicit preference, correction, accepted recommendation, or rejected direction. Track helpful and harmful outcomes separately. Do not manufacture a learning merely because a workflow completed. + + +## Upstream judgment port: issue #886 + +[Scale planning machinery to the printed build scale](https://github.com/garrytan/gstack/issues/886) + +### Proportional planning for the printed build scale + +The /plan dispatcher prints a `Scale:` header line classified from fifteen build-scale vectors (its Build scale section). This rule authorizes every planning specialist to size its machinery to that scale while keeping every STOP gate and approval boundary; a polite user answering every question is not evidence the full machinery is wanted, and the user can always ask for the complete treatment. + +- `session` and `hobby`: batch every question the initial prompt left unanswered into one AskUserQuestion round (two rounds for hobby); skip web or landscape research, outside voices, second opinions, and visual sketches unless the user asks (privacy gates are unchanged whenever they run); cap any adversarial or spec review loop at one iteration; keep the decision artifact near one page with next steps sized in hours (session) or days (hobby), never a phased multi-week roadmap or a distribution plan the user did not ask for. +- `project`: run the specialist's default workflow, batching question rounds where its source authorizes smart skips; size the roadmap in weeks. +- `product` and `venture`: the full specialist workflow and its complete question pressure apply; this rule removes nothing. +- Never run a questioning round merely to classify scale. Classify from the prompt and cheap repository evidence, defaulting unknown vectors low; a specialist's own later questions may raise the scale mid-session, and an upgrade restores the full workflow from that point. + +For office-hours specifically: at session or hobby scale, batch the Phase 2B questions (this refines the one-at-a-time rule, whose pressure exists for startup diagnostics), default-skip the Phase 2.75 landscape search, gate the visual sketch and outside design voices on an explicit ask, and cap the Spec Review Loop at one iteration. + + + +## Upstream judgment port: issue #703 + +[Write design docs repo-local and read them from the repo first](https://github.com/garrytan/gstack/issues/703) + +### Repo-local design artifacts + +When the session produces a design or plan document and the working directory is inside a repository, write it to `docs/designs/.md` in that repository (create `docs/designs/` if needed) and name that path every time the document is presented or approval is requested. A hashed home-directory path is never the thing the user is asked to open. Keep writing the cross-session copy under `"${GSTACK_HOME:-$HOME/.gstack}"/projects//` with the existing filename convention — downstream skills, prior-design lookup, and cross-team discovery depend on that store — but the repo-local file is the canonical one the user owns and edits. Outside a repository, the `$GSTACK_HOME` path remains the only copy; print it in full when asking for approval. When reviewing, prefer a repo-local design doc (`docs/designs/`, `docs/plans/`, or an explicitly provided path) over the `$GSTACK_HOME` store whenever both exist. + diff --git a/skills/plan/references/legacy/plan-devex-review.md b/skills/plan/references/legacy/plan-devex-review.md index 0ab57a6df3..9d5e3adc9e 100644 --- a/skills/plan/references/legacy/plan-devex-review.md +++ b/skills/plan/references/legacy/plan-devex-review.md @@ -685,3 +685,30 @@ Write questions, progress updates, reports, and artifacts in the language used b Persist a learning only when the interaction contains a useful, reusable signal such as an explicit preference, correction, accepted recommendation, or rejected direction. Track helpful and harmful outcomes separately. Do not manufacture a learning merely because a workflow completed. + + +## Upstream judgment port: issue #886 + +[Scale planning machinery to the printed build scale](https://github.com/garrytan/gstack/issues/886) + +### Proportional planning for the printed build scale + +The /plan dispatcher prints a `Scale:` header line classified from fifteen build-scale vectors (its Build scale section). This rule authorizes every planning specialist to size its machinery to that scale while keeping every STOP gate and approval boundary; a polite user answering every question is not evidence the full machinery is wanted, and the user can always ask for the complete treatment. + +- `session` and `hobby`: batch every question the initial prompt left unanswered into one AskUserQuestion round (two rounds for hobby); skip web or landscape research, outside voices, second opinions, and visual sketches unless the user asks (privacy gates are unchanged whenever they run); cap any adversarial or spec review loop at one iteration; keep the decision artifact near one page with next steps sized in hours (session) or days (hobby), never a phased multi-week roadmap or a distribution plan the user did not ask for. +- `project`: run the specialist's default workflow, batching question rounds where its source authorizes smart skips; size the roadmap in weeks. +- `product` and `venture`: the full specialist workflow and its complete question pressure apply; this rule removes nothing. +- Never run a questioning round merely to classify scale. Classify from the prompt and cheap repository evidence, defaulting unknown vectors low; a specialist's own later questions may raise the scale mid-session, and an upgrade restores the full workflow from that point. + +For office-hours specifically: at session or hobby scale, batch the Phase 2B questions (this refines the one-at-a-time rule, whose pressure exists for startup diagnostics), default-skip the Phase 2.75 landscape search, gate the visual sketch and outside design voices on an explicit ask, and cap the Spec Review Loop at one iteration. + + + +## Upstream judgment port: issue #703 + +[Write design docs repo-local and read them from the repo first](https://github.com/garrytan/gstack/issues/703) + +### Repo-local design artifacts + +When the session produces a design or plan document and the working directory is inside a repository, write it to `docs/designs/.md` in that repository (create `docs/designs/` if needed) and name that path every time the document is presented or approval is requested. A hashed home-directory path is never the thing the user is asked to open. Keep writing the cross-session copy under `"${GSTACK_HOME:-$HOME/.gstack}"/projects//` with the existing filename convention — downstream skills, prior-design lookup, and cross-team discovery depend on that store — but the repo-local file is the canonical one the user owns and edits. Outside a repository, the `$GSTACK_HOME` path remains the only copy; print it in full when asking for approval. When reviewing, prefer a repo-local design doc (`docs/designs/`, `docs/plans/`, or an explicitly provided path) over the `$GSTACK_HOME` store whenever both exist. + diff --git a/skills/plan/references/legacy/plan-eng-review.md b/skills/plan/references/legacy/plan-eng-review.md index 7b1f7aac26..3b23256771 100644 --- a/skills/plan/references/legacy/plan-eng-review.md +++ b/skills/plan/references/legacy/plan-eng-review.md @@ -295,3 +295,30 @@ Persist a learning only when the interaction contains a useful, reusable signal Before reviewing anything, run a pre-mortem: it is three months later and this plan failed, name the top three reasons why. Reason from production reality, not the plan's internal logic, and name concrete failure modes (data loss, performance cliff, security hole, team confusion), not abstract worries. Present those three failure modes to the user before the scope challenge, which follows the pre-mortem rather than opening the review. + + +## Upstream judgment port: issue #886 + +[Scale planning machinery to the printed build scale](https://github.com/garrytan/gstack/issues/886) + +### Proportional planning for the printed build scale + +The /plan dispatcher prints a `Scale:` header line classified from fifteen build-scale vectors (its Build scale section). This rule authorizes every planning specialist to size its machinery to that scale while keeping every STOP gate and approval boundary; a polite user answering every question is not evidence the full machinery is wanted, and the user can always ask for the complete treatment. + +- `session` and `hobby`: batch every question the initial prompt left unanswered into one AskUserQuestion round (two rounds for hobby); skip web or landscape research, outside voices, second opinions, and visual sketches unless the user asks (privacy gates are unchanged whenever they run); cap any adversarial or spec review loop at one iteration; keep the decision artifact near one page with next steps sized in hours (session) or days (hobby), never a phased multi-week roadmap or a distribution plan the user did not ask for. +- `project`: run the specialist's default workflow, batching question rounds where its source authorizes smart skips; size the roadmap in weeks. +- `product` and `venture`: the full specialist workflow and its complete question pressure apply; this rule removes nothing. +- Never run a questioning round merely to classify scale. Classify from the prompt and cheap repository evidence, defaulting unknown vectors low; a specialist's own later questions may raise the scale mid-session, and an upgrade restores the full workflow from that point. + +For office-hours specifically: at session or hobby scale, batch the Phase 2B questions (this refines the one-at-a-time rule, whose pressure exists for startup diagnostics), default-skip the Phase 2.75 landscape search, gate the visual sketch and outside design voices on an explicit ask, and cap the Spec Review Loop at one iteration. + + + +## Upstream judgment port: issue #703 + +[Write design docs repo-local and read them from the repo first](https://github.com/garrytan/gstack/issues/703) + +### Repo-local design artifacts + +When the session produces a design or plan document and the working directory is inside a repository, write it to `docs/designs/.md` in that repository (create `docs/designs/` if needed) and name that path every time the document is presented or approval is requested. A hashed home-directory path is never the thing the user is asked to open. Keep writing the cross-session copy under `"${GSTACK_HOME:-$HOME/.gstack}"/projects//` with the existing filename convention — downstream skills, prior-design lookup, and cross-team discovery depend on that store — but the repo-local file is the canonical one the user owns and edits. Outside a repository, the `$GSTACK_HOME` path remains the only copy; print it in full when asking for approval. When reviewing, prefer a repo-local design doc (`docs/designs/`, `docs/plans/`, or an explicitly provided path) over the `$GSTACK_HOME` store whenever both exist. + diff --git a/skills/plan/references/legacy/spec.md b/skills/plan/references/legacy/spec.md index 076210d947..eca3c694b9 100644 --- a/skills/plan/references/legacy/spec.md +++ b/skills/plan/references/legacy/spec.md @@ -805,3 +805,20 @@ Add to the standard template: Write questions, progress updates, reports, and artifacts in the language used by the user. Source material, code identifiers, commands, and quotations may remain in their original language when translating them would reduce accuracy. + + +## Upstream judgment port: issue #886 + +[Scale planning machinery to the printed build scale](https://github.com/garrytan/gstack/issues/886) + +### Proportional planning for the printed build scale + +The /plan dispatcher prints a `Scale:` header line classified from fifteen build-scale vectors (its Build scale section). This rule authorizes every planning specialist to size its machinery to that scale while keeping every STOP gate and approval boundary; a polite user answering every question is not evidence the full machinery is wanted, and the user can always ask for the complete treatment. + +- `session` and `hobby`: batch every question the initial prompt left unanswered into one AskUserQuestion round (two rounds for hobby); skip web or landscape research, outside voices, second opinions, and visual sketches unless the user asks (privacy gates are unchanged whenever they run); cap any adversarial or spec review loop at one iteration; keep the decision artifact near one page with next steps sized in hours (session) or days (hobby), never a phased multi-week roadmap or a distribution plan the user did not ask for. +- `project`: run the specialist's default workflow, batching question rounds where its source authorizes smart skips; size the roadmap in weeks. +- `product` and `venture`: the full specialist workflow and its complete question pressure apply; this rule removes nothing. +- Never run a questioning round merely to classify scale. Classify from the prompt and cheap repository evidence, defaulting unknown vectors low; a specialist's own later questions may raise the scale mid-session, and an upgrade restores the full workflow from that point. + +For office-hours specifically: at session or hobby scale, batch the Phase 2B questions (this refines the one-at-a-time rule, whose pressure exists for startup diagnostics), default-skip the Phase 2.75 landscape search, gate the visual sketch and outside design voices on an explicit ask, and cap the Spec Review Loop at one iteration. + diff --git a/test/gstack2-skills.test.ts b/test/gstack2-skills.test.ts index 9ace6c93db..f9d3610e90 100644 --- a/test/gstack2-skills.test.ts +++ b/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(25); + expect(result.regressions).toBe(27); }, 30_000); test('keeps image generation host-native, optional, and provider-free', () => {