document gstack 2 evidence and blocked gates

2026-09-21 04:10:47 +02:00 · 2026-07-17 11:08:51 -07:00
parent 9919c4cdd3
commit 7d760ff1d1
19 changed files with 10026 additions and 208 deletions
@@ -2,8 +2,100 @@

 Thanks for wanting to make gstack better. Whether you're fixing a typo in a skill prompt or building an entirely new workflow, this guide will get you up and running fast.

+## GStack 2 contribution contract
+
+GStack 2 deliberately has six public nouns: `plan`, `design`, `qa`, `debug`,
+`review`, and `ship`. Preserve that small surface. A proposal for PM,
+accessibility, language, backend, dashboards, sales, or orchestration normally
+belongs as a mode, an internal utility, or a community extension—not a seventh
+first-party command.
+
+A contribution must do at least one of the following:
+
+- improve preserved judgment or the evidence proving it;
+- remove duplicated/default surface without deleting behavior;
+- fix a linked reproduction and add a regression test; or
+- repair bounded infrastructure with one actionable diagnosis and repair
+  location.
+
+New public commands, new first-party host adapters, and new external services
+require an accepted issue before implementation. External services also
+require explicit maintainer approval. Do not add a provider/plugin marketplace,
+workflow engine, cloud-browser or cloud-device backend, alternate iOS driver,
+database merely for centralization, or local model/runtime download.
+
+Edit specialist behavior at its canonical legacy template or an explicitly
+reviewed bug-fix overlay. Do not hand-edit generated files under
+`skills/*/references/legacy/`, `evals/parity/`, `compat/`, or the generated
+GStack 2 migration/parity/provenance/scenario docs. Run:
+
+```bash
+bun run gen:gstack2
+bun run test:gstack2
+```
+
+Every behavioral change must account for questions, pressure, smart skips,
+STOP/approval gates, evidence, artifacts, mutation boundaries, exit behavior,
+and voice. “Shorter” is not evidence of parity. Changes to routing need a
+structured scenario fixture; changes to an upstream judgment port need a
+reproduction-linked regression fixture.
+
+Install work must test the standard Agent Skills installer, not a new
+collection of host paths. Runtime work must preserve no-network-before-consent,
+worktree isolation, atomic writes, resumable idempotency, readable state,
+failure rollback, and runtime-absent judgment behavior.
+
+Suggested issue labels (prepare repository automation in a PR, but do not
+create labels or mutate GitHub without authorization):
+
+```text
+reproducible-bug
+judgment
+workflow
+context
+adapter
+community-pack
+2.0-port
+superseded
+needs-evidence
+not-core
+```
+
+Issue templates should ask for: observed versus expected behavior, minimal
+reproduction, host/OS/version, evidence or transcript with secrets removed,
+root-cause hypothesis if known, affected judgment module, proposed disposition,
+and a replacement-test contract. Service/adapter/public-command proposals must
+also explain why an existing mode or standards-compatible installer cannot
+solve the need.
+
+The sections below retain the 1.x development workflow where it still applies.
+Host-specific generation and dev symlinking are not the canonical GStack 2
+installation path. On this branch, `./setup` installs only the optional managed
+runtime; it no longer places host skills or accepts legacy setup flags.
+
 ## Quick start

+For GStack 2 source work:
+
+```bash
+git clone https://github.com/time-attack/gstack.git && cd gstack
+bun install
+bun run gen:gstack2
+bun run test:gstack2
+```
+
+Exercise standard installation only in disposable homes/projects. The
+repository harness covers the supported matrix without touching operator skill
+directories:
+
+```bash
+bun test test/gstack2-installation.test.ts
+bun run scripts/gstack2/test-install-matrix.ts --full \
+  --output /tmp/gstack2-install-matrix.json
+```
+
+### Legacy 1.x dev-mode quick start
+
 gstack skills are Markdown files that Claude Code discovers from a `skills/` directory. Normally they live at `~/.claude/skills/gstack/` (your global install). But when you're developing gstack itself, you want Claude Code to use the skills *in your working tree* — so edits take effect instantly without copying or deploying anything.

 That's what dev mode does. It symlinks your repo into the local `.claude/skills/` directory so Claude Code reads skills straight from your checkout.
@@ -259,7 +351,20 @@ Tests run against the browse binary directly — they don't require dev mode.

 ## Editing SKILL.md files

-SKILL.md files are **generated** from `.tmpl` templates. Don't edit the `.md` directly — your changes will be overwritten on the next build.
+There are two generation paths. GStack 2 public dispatchers, preserved modules,
+compatibility routes, and parity fixtures are generated by `gen:gstack2`; edit
+its assignment/route/scenario/overlay inputs or the canonical legacy template,
+then regenerate. The older host-specific `SKILL.md` files are generated from
+`.tmpl` templates. Do not hand-edit either kind of output.
+
+For GStack 2:
+
+```bash
+bun run gen:gstack2
+bun run test:gstack2
+```
+
+For retained 1.x host output:

 ```bash
 # 1. Edit the template
@@ -306,9 +411,10 @@ terminology, security jargon, frontend framework concepts). Don't add terms
 that only appear in one or two niche skills — the cost-to-value trade isn't
 worth the review overhead.

-## Multi-host development
+## Legacy 1.x multi-host development

-gstack generates SKILL.md files for 8 hosts from one set of `.tmpl` templates.
+This section documents compatibility output, not canonical GStack 2
+installation. GStack 1.x generates SKILL.md files for 8 hosts from one set of `.tmpl` templates.
 Each host is a typed config in `hosts/*.ts`. The generator reads these configs
 to produce host-appropriate output (different frontmatter, paths, tool names).

@@ -357,7 +463,9 @@ bun run skill:check

 ### Adding a new host

-See [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md) for the full guide. Short version:
+GStack 2 first-party host adapters require an accepted issue and proof that the
+standard portable tree is insufficient. The guide below applies only to the
+legacy generator: see [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md).

 1. Create `hosts/myhost.ts` (copy from `hosts/opencode.ts`)
 2. Add to `hosts/index.ts`
@@ -369,7 +477,9 @@ Zero generator, setup, or tooling code changes needed.

 ### Adding a new skill

-When you add a new skill template, all hosts get it automatically:
+Do not add a seventh GStack 2 public skill without an accepted issue. Prefer a
+mode, internal module, or community extension. For a legacy compatibility
+template, all legacy host outputs are generated automatically:
 1. Create `{skill}/SKILL.md.tmpl`
 2. Run `bun run gen:skill-docs --host all`
 3. The dynamic template discovery picks it up, no static list to update
@@ -377,6 +487,13 @@ When you add a new skill template, all hosts get it automatically:

 ## Conductor workspaces

+The 1.x `bin/dev-setup` path below still passes host-placement and hook flags to
+`./setup`; the GStack 2 runtime-only wrapper intentionally rejects them. Treat
+this integration as pending migration, not a working 2.0 install path. Use the
+source commands and isolated installer harness above for current 2.0 work.
+
+### Historical 1.x behavior
+
 If you're using [Conductor](https://conductor.build) to run multiple Claude Code sessions in parallel, `conductor.json` wires up workspace lifecycle automatically:

 | Hook | Script | What it does |
@@ -485,7 +602,7 @@ When community PRs accumulate, batch them into themed waves:
 5. **Ship as one PR** — single PR to main with all attributions preserved
   in merge commits. Include a summary table of what merged and what closed.

-See [PR #205](../../pull/205) (v0.8.3) for the first wave as an example.
+See [PR #205](https://github.com/garrytan/gstack/pull/205) (v0.8.3) for the first wave as an example.

 ## Upgrade migrations