From 07b59e396c6be5a86619a43151cb9ed62a15ae69 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sat, 29 Aug 2026 10:10:35 -0700 Subject: [PATCH] =?UTF-8?q?v1.75.0.0=20feat:=20ponytail=20import=20wave=20?= =?UTF-8?q?=E2=80=94=20simplification=20review=20lens,=20arm=20benchmark,?= =?UTF-8?q?=20reuse=20ladder,=20instruction-tier=20digest=20(#2722)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(autoplan): eng review always runs last — the gate reviews the final amended plan Reorder the pipeline to CEO -> Design (if UI scope) -> DX (if developer-facing scope) -> Eng. The old order (CEO -> Design -> Eng -> DX) let DX findings land AFTER the required gate signed off, so eng validated a stale plan. Accept-all semantics made explicit: every AskUserQuestion resolves to the recommended option; premises no longer pause the pipeline mid-run (clearly-wrong ones queue as User-Challenge items at the single Final Approval Gate). Eng's Codex voice now sees the DX consensus summary. New free static test pins the order; the chain E2E gains DX-between and Eng-terminal assertions. Co-Authored-By: Claude Fable 5 * feat(review): simplification specialist — advisory over-engineering lens with ponytail's tag vocabulary New 8th Review Army specialist (DIFF_LINES > 100, --simplification force flag) hunting unrequested STRUCTURE only: delete/stdlib/native/speculative/shrink closed tags, one-line findings, lines_removable field. speculative: replaces ponytail's yagni: tag — we import the lens, not the posture; coverage stays sacred (Completeness Gaps owns it, suppressions inlined, shrink needs >=5 lines). Advisory carve-out in the merge step: advisory findings are excluded from quality_score and the findings-count header, render with an [ADVISORY] label, and are ASK-only in Fix-First. Zero-findings case prints the lens-scoped 'Simplification: lean already — nothing to cut.' from the PARENT (the specialist keeps the exact NO FINDINGS contract); with findings, the parent prints 'net: -N lines possible' summed from lines_removable. Tests: static pins for the carve-out + early-out contract (gen-skill-docs), two periodic e2e cases with planted fixtures — activation (over-build traps: hand-rolled Intl, one-impl abstract, dead config) and false-flag precision (a lean ETHOS 'choose A' diff must yield NO FINDINGS). Inspired by dietrichgebert/ponytail's /ponytail-review. Co-Authored-By: Claude Fable 5 * feat(preamble): reuse ladder in Search Before Building — rungs 2-5 of ponytail's ladder, completeness kept Tier-3+ skills gain a per-edit reflex the section only stated as research discipline: before writing new code, stop at the first rung that holds — repo helper, stdlib, native platform feature, installed dependency — then build the COMPLETE version of what remains. The closing clause is the explicit reconciliation with Boil the Ocean: the ladder governs structure, never coverage. Rungs 1/6/7 (YAGNI / one line / minimum that works) are deliberately NOT imported. Also ports ponytail's root-cause rule: one guard in the shared function beats a guard in every caller. Co-Authored-By: Claude Fable 5 * feat(preamble): bounded-closer output rule for tier-2+ skills After completing work, skills report in a few short lines — what changed, what was skipped, what to watch — and cut any explanation that outgrows the change. Explicit exemptions protect every mandated output: decision briefs, completion-status blocks, user-requested explanations, and report-shaped skills' report formats (the report IS the work in /qa-only, /plan-*-review, /retro, /document-generate). Rationale is signal-to-noise, not tokens: ponytail's own benchmark shows terse prose alone doesn't cut cost (caveman arm: -20% LOC, +7% tokens), and independent replications found its 'skipped on purpose' essays ate the code savings. Includes a good/bad closer example pair per the model-overlay guidance that a positive example beats a 'don't be verbose' instruction. Co-Authored-By: Claude Fable 5 * docs(resolvers): terse-mode savings claim matches measurement — 2.6KB, not 3-5KB Measured on the v1.71 render: --explain-level=terse saves exactly 2,611 bytes per tier-2+ skill. The old ~3-5KB claim predated the preamble restructuring. Co-Authored-By: Claude Fable 5 * feat(retro,preamble): gstack-shortcut debt ledger — accepted shortcuts leave a joined trail When the user accepts an option that is BOTH Completeness <= 7 AND a durable-scope call, the decision ledger entry (gstack-decision-log, ceiling + upgrade trigger in the rationale) is the source of truth, and the agent marks each cut corner in code with gstack-shortcut(dec-): , upgrade when — same edit, no follow-up question, never agent-initiated. /retro Step 11.5 harvests markers into a debt ledger (grep || true — zero matches is the healthy case; skill installs and docs excluded), joins on the decision id so nothing double-counts, tags unlinked and no-trigger rot risks, and closes with 'N markers, M with no trigger.' /review suppressions: a marker with ceiling+trigger downgrades a would-be Completeness Gaps finding to acknowledged debt. Redaction test pins that the marker ships untouched (the ledger is the point) — it does not match the TODO(owner) hygiene shape. Format from dietrichgebert/ponytail's ponytail-debt; store inverted to gstack's existing decision ledger. Co-Authored-By: Claude Fable 5 * test: refresh golden ship baselines after preamble additions (reuse ladder + bounded closer) The golden-file regression test pins the rendered ship skill byte-for-byte; the WS3/WS7 preamble sections are deliberate changes, so the baselines re-capture per the goldens' own update protocol. Co-Authored-By: Claude Fable 5 * feat(hosts): instruction-only tier — a 2KB committed rules digest any agent host can read New agents-digest/gstack-AGENTS.md (1,765 bytes, hard 2,048-byte budget): gstack's ethos one-liners, the reuse ladder, and voice rules for hosts with no install arm — Zed, Amp, Jules, or any AGENTS.md-reading agent. Generated by scripts/gen-agents-digest.ts, auto-refreshed by gen:skill-docs, committed like llms.txt so setup's explainer arms can point at it before any toolchain exists. First line carries the gstack version as its own staleness nudge. Delivery is print-path + user-performed copy ONLY: setup never writes or overwrites a user's AGENTS.md (a test pins this — no cp/ln/mv/redirect into AGENTS.md anywhere in setup). openclaw and hermes explainer arms print the path; slate keeps routing to the full Claude install and gbrain ships from its own repo. HostConfig gains the optional install.instructionTier slot, declared by both instruction-tier hosts. README host table now matches what setup actually does. Inspired by dietrichgebert/ponytail's instruction-tier AGENTS.md fallback — one generated source, never per-host hand copies. Co-Authored-By: Claude Fable 5 * feat(preamble): AskUserQuestion repetition cut — gated, passed NOT-WORSE A/B Removes the duplicate statements v1.71's compaction left in the AskUserQuestion Format section: the completeness rule restated in the prose triad, the auto-decide marker syntax stated twice, the Conductor-flakiness explanation stated twice, and the self-check's full triad restatement. Every verbosity floor and all 14 format pins stay (Layer 0 green). The gate this decision rested on ran before landing (new periodic skill-e2e-auq-repetition-cut-ab.test.ts, pre-cut ref 3263fffe vs this render, same harness as auq-verbose-vs-carved-ab): POST 7/7 format elements, substance 5 — identical to PRE. No degradation; the load-bearing-repetition hypothesis did not hold for these duplicates. Net: -236 bytes per tier-2+ skill (~9.7KB corpus). Golden ship baselines re-captured for the deliberate change. Co-Authored-By: Claude Fable 5 * feat(evals): with-skill vs without-skill arm benchmark — measures whether gstack's behavioral layer earns its tokens Ponytail's honest-benchmark method pointed at gstack itself: 3 build-shaped tasks (native-platform over-build trap, CRUD endpoint, bug fix with planted decoys) x 2 arms, real claude -p sessions, scored on the git diff left behind. A research instrument, not a release gate — no assertion compares arm scores. Arms use the PROVEN project-scope pattern: the with-arm installs a build-discipline skill (extracted reuse-ladder + bounded-closer content, not whole-file copies) into the fixture's .claude/skills/ with a CLAUDE.md routing line and an explicit invocation; a live spike confirmed claude -p discovers and invokes project-scope skills via the Skill tool (3 turns, exact-output probe). Fixtures are git init + local bare origin; diff capture is three lines of git, no worktree machinery. Failure taxonomy: zero-diff arms are VALID scored cells (deterministic 0/none, no API call), harvest failures record harvest:null, judge_error cells are excluded from aggregates but named in the report — nothing drops silently. armJudge: fixed sonnet judge, 0-3 unrequested-structure rubric, must name the construct or say none, bounded retry-on-malformed; callJudge gains optional temperature/max_tokens (defaults unchanged). recordE2E now populates tokens_used for every E2E. Eval schema v2: harvest gains {insertions, deletions, net}, tolerant reads keep v1 runs comparable. Registered periodic in E2E_TIERS + touchfiles (with the auq-repetition-cut A/B); periodic detach timeout raised to the new shard-census floor. Free selftest (8 tests, zero API) pins fixtures, extraction, arm asymmetry, diff capture, judge plumbing, and the retry bound. Co-Authored-By: Claude Fable 5 * test: absorb the ponytail-import wave into the guard fixtures — ceilings, schema pin, triad phrasing Skeleton ceilings re-captured for the 17 carved skills the wave deliberately grew (reuse ladder + bounded closer + shortcut trail, net of the gated -236B AUQ cut), each with its measured size in the comment per the carve-guards protocol. eval-store schema pin updated to v2 (harvest gains insertions/deletions/net). The AUQ prose-triad keeps its pinned per-choice phrasing ('explicit on EACH choice') while still deferring the score scale to the canonical Format rule — the shipped cut is strictly closer to the pre-cut text than the render that already passed the NOT-WORSE gate. Autoplan carve anchors follow the Phase 2.5 renumbering. Golden ship baselines re-captured. Co-Authored-By: Claude Fable 5 * test: observability partial-file pin follows eval-store schema v2 Co-Authored-By: Claude Fable 5 * feat(test-runner): GSTACK_FREE_JOBS + opt-in flaky-retry pass for syscall-supervised sandboxes GSTACK_FREE_JOBS overrides the computed shard count (the free runner's analogue of the paid runner's EVALS_JOBS). On Vercel sandboxes, PID 1 installs a seccomp filter whose supervisor spuriously fails access(2) for busy processes — measured: 200/200 git-init probes fail 'Cannot access work tree: Permission denied' while the suite runs at 6 shards, 0/200 idle; statx succeeds while access fails on the same path in the same process. One serial mega-shard maximizes per-process pressure and fails too; 2 shards is the measured sweet spot. GSTACK_FREE_RETRY_FLAKY=1 (default OFF — dev boxes should see flakes) re-runs attributed failures once, serially, capped at 5 files; a clean retry downgrades to a loud FLAKY-PASS naming the offenders, a repeat failure stays red, timeouts and unattributed failures never retry. Co-Authored-By: Claude Fable 5 * fix(browse): portable temp paths — TEMP_DIRS allowlist, tmpdir()-based test files Local path validation now accepts os.tmpdir() alongside the classic /tmp (new TEMP_DIRS in platform.ts): on macOS os.tmpdir() is /var/folders/..., and TMPDIR-honoring CI/sandbox environments point it elsewhere entirely — both are legitimate scratch space. Remote file serving (TEMP_ONLY) stays pinned to TEMP_DIR alone; no change to the exfil boundary. commands.test.ts drops 41 hardcoded /tmp literals for a tmpp() helper on os.tmpdir() (two message assertions now reference the same variable), and path-validation's symlink-escape test targets /etc/hosts instead of /etc/crontab — the target must EXIST for realpath to resolve the link (a dangling target falls back to the link's own path and passes vacuously), and /etc/crontab is absent on Amazon Linux. Co-Authored-By: Claude Fable 5 * fix(config): portable sha256 — Linux ships sha256sum, not shasum resolve-user-slug and endpoint hashing exited 127 on Amazon Linux (shasum is a macOS/perl tool). New _sha256_hex helper prefers sha256sum and falls back to shasum, matching gstack-verify-gate's existing pattern; both call sites converted. Co-Authored-By: Claude Fable 5 * fix(next-version): only trust ls-remote when origin is actually configured Without the guard, git DWIMs the literal 'origin' as an ssh host/path; on hosts whose transport launders exit codes the probe 'succeeds' with zero branches and the allocator silently sees an empty queue — the exact duplicate-allocation failure (#2545) fetchGitClaimed exists to prevent. git remote get-url origin gates the probe; absence falls through to the existing local-refs path with its staleness warning. Co-Authored-By: Claude Fable 5 * docs(testing): sandbox-doctor — one command makes a cloud sandbox run the suite green Measured failure taxonomy for Vercel/Conductor sandboxes (missing /dev/fd, 64M /dev/shm, seccomp-supervisor access(2) EACCES under load, uid-1000 processes with FULL capabilities defeating chmod-denial tests, no X server, no git identity, Conductor git-shim exit-code laundering) plus the idempotent script that treats all of it and seeds the run recipe. Co-Authored-By: Claude Fable 5 * fix(config): converge on main's self-contained sha8_of — its tests extract the function standalone The merge kept a branch-local _sha256_hex helper; main's v1.72 landed the same portability fix inline WITH tests that extract sha8_of()'s text and run it under a shim-only PATH — a helper call can't satisfy that shape. Adopt the landed implementation at both hash sites. Co-Authored-By: Claude Fable 5 * test: coverage for GSTACK_FREE_JOBS override and failingFiles attribution Co-Authored-By: Claude Fable 5 * test: coverage for TEMP_DIRS widening and remote-serving TEMP_ONLY asymmetry Co-Authored-By: Claude Fable 5 * test: coverage for gstack-shortcut marker grammar and retro harvest joint Co-Authored-By: Claude Fable 5 * test: coverage for sandbox-doctor shell syntax and idempotency guards Co-Authored-By: Claude Fable 5 * fix(test-runner): empty-shard outcome carries failingFiles; harden flaky-retry list The empty-shard early return omitted the (required) failingFiles field — tsc TS2741 — feeding undefined into the flaky-retry flatMap. Also drop the dead 'else if (worst !== 0)' guard (the enclosing if already pins it). Co-Authored-By: Claude Fable 5 * fix(release): version-bump write regenerates the version-stamped agents digest agents-digest/gstack-AGENTS.md embeds VERSION in its first line and is byte-freshness-gated (test/agents-digest.test.ts + Skill Docs Freshness CI), but nothing in the release path regenerated it — every version-bumping ship of this repo would land red. write now spawns the repo's own generator when present (agentsDigest true/false/null in the output JSON), and ship's evidence gate allow-lists the digest alongside VERSION/package.json. Co-Authored-By: Claude Fable 5 * fix(setup): instruction-tier explainer prints the script-anchored digest path $(pwd) printed a nonexistent path when setup ran from any other directory; both arms now share one print_instruction_tier() using SOURCE_GSTACK_DIR. Co-Authored-By: Claude Fable 5 * test(digest): broaden AGENTS.md writer tripwire; pin digest-resolver ladder lockstep The print-path-only guard now catches tee/install/rsync/dd/truncate, >> appends, and laundered variable-destination writes. New test ties the digest's hand-rendered reuse-ladder text to the preamble resolver so an edit to either fails CI instead of shipping drift. Co-Authored-By: Claude Fable 5 * fix(retro): shortcut harvest drops placeholder markers and convention docs The Step 11.5 grep matched documentation mentions (dec-, dec-*) in checklists, resolver sources, and convention tests, reporting phantom debt rows on gstack itself. A trailing filter kills placeholder forms; prose tells the agent to discard convention-quoting hits. Co-Authored-By: Claude Fable 5 * fix(review): advisory findings count in per-specialist stats Without this, simplification (all-advisory by construction) would log findings:0 every run and auto-gate itself into permanent silence after 10 dispatches. The advisory carve-out governs score and header only. Co-Authored-By: Claude Fable 5 * fix(evals): arm-benchmark harvest and judge hardening - Harvest diffs against the recorded seed SHA (origin/main is movable by an agent that commits AND pushes; a recorded SHA is not). - Fixtures get a node_modules .gitignore and the git wrapper a 64MB maxBuffer, so a vendored-dependency arm is scored instead of killing the cell. - The judge diff cap is a named constant with loud truncation (log + judge_reasoning suffix). - Judge prompt block markers carry a per-call random sentinel, so a diff containing a faked closing marker cannot escape the data block. Co-Authored-By: Claude Fable 5 * fix(evals): AUQ A/B vendored pre-cut arm + judge-error inconclusive taxonomy - The PRE arm read a branch-local SHA (3263fffe) that becomes unreachable on fresh clones after the squash-merge; the pre-cut render is now a vendored fixture. - A judge failure on one side no longer coerces substance to 0 (which fabricated DEGRADATION on POST-side failures and masked regressions on PRE-side failures): null substance = inconclusive, format still gates. Co-Authored-By: Claude Fable 5 * test: regression pin for the originConfigured guard vs laundering git shims On healthy hosts the guarded and unguarded paths behave identically, so a revert passes the suite; only a shim that makes 'git ls-remote' exit 0 with empty output (the Conductor wrapper's observed behavior) exposes it. Pins that the empty 'successful' probe is never trusted as an empty queue. Co-Authored-By: Claude Fable 5 * fix(sandbox-doctor): missing /dev/shm no longer aborts the doctor under set -eu Co-Authored-By: Claude Fable 5 * chore(touchfiles): close dep-list gaps for the new evals - arm-benchmark entries gain ship/SKILL.md (buildBehavioralSkill extracts sections from the rendered ship skill) - review-army-simplification entries gain their planted fixtures + test file - auq-repetition-cut-ab gains llm-judge.ts and the vendored PRE fixture Co-Authored-By: Claude Fable 5 * chore: re-capture context-budget fixture — lock the WS6-3 reduction and Step 9 deltas Per the ratchet protocol: the AUQ repetition cut shrank per-skill eager tokens but the fixture was never re-captured, leaving the win unlocked. Co-Authored-By: Claude Fable 5 * fix(release): digest regen is an explicit --regen-digest opt-in, not presence-sniffed code exec Review (security) caught the cycle-1 fix executing any repo's scripts/gen-agents-digest.ts on plain 'write' — arbitrary code exec from a hostile clone on a routine bump, contradicting the binary's own containment posture. The regen still runs the TARGET repo's generator (a 'trusted' copy beside the binary would false-red the freshness gate on version drift), but only under the flag: /ship passes it deliberately, in a repo whose code the operator already executes (its test suite). Plain write is side-effect-free again. Also: uniform output shape (agentsDigest: null on the JSON-manifest branch), a REAL generator round-trip test replacing the misnamed lockstep check, and land-and-deploy's evidence gate gets the same digest allow-path as ship so the two grading surfaces agree. Co-Authored-By: Claude Fable 5 * fix(test-runner): flaky-retry vetoes on ANY unattributable failure evidence The gate equated 'some failure attributed' with 'all failures attributed': a shard with one attributed failure plus a headerless failure, an unhandled error between tests, or a truncated run (no terminal summary) qualified for retry — re-running only failingFiles and masking the rest as FLAKY-PASS, re-opening the silent-truncation hole the strict classifier closes. FreeShardOutcome now carries unattributedFailures; nonzero vetoes the retry. Pins: mixed shard, truncated-with-attributed shard, empty-shard field values. Co-Authored-By: Claude Fable 5 * fix(next-version): a configured origin advertising zero heads is never trusted The originConfigured guard covered only the no-origin laundering case. With origin configured (the normal Conductor worktree state), the laundering shim makes a failed ls-remote exit 0 with empty stdout — read as 'the queue is empty', the exact duplicate-allocation bug (#2545) one layer up. A reachable remote always advertises at least its default branch, so an exit-0 zero-head probe now falls back to local refs/remotes/origin with a laundering-specific warning. Regression test shims git for both configurations. Co-Authored-By: Claude Fable 5 * fix(sandbox-doctor): loud on git-shim patch drift; document the retry-contract override - The /conductor/bin/git patch was a silent no-op if the shim's bytes drift from the exact pattern — now warns that laundering is NOT fixed. - The bashrc block documents why GSTACK_FREE_RETRY_FLAKY=1 deliberately overrides the runner's default-OFF contract on this sandbox, and how to undo it. - Test pins the guarded shm form (missing /dev/shm must not abort set -eu). Co-Authored-By: Claude Fable 5 * test(digest): pin the script-anchored explainer path; catch declaration-prefixed writers - Asserts $SOURCE_GSTACK_DIR/agents-digest path and forbids $(pwd)/agents-digest (the cycle-1 fix was revertible without failing anything). - The laundered-assignment arm now matches local/export/declare/readonly/typeset prefixed assignments — the likeliest in-function writer shape in setup. Co-Authored-By: Claude Fable 5 * refactor(evals): arm-benchmark selftest runs FREE on every PR The selftest lived inside the paid skill-e2e-* file, so fixture-integrity and plumbing pins executed weekly at best — a broken fixture would ship past every gating check and be discovered when the periodic run burned money on a dead instrument. Harness extracted to test/helpers/arm-benchmark-harness.ts, selftest to test/arm-benchmark-selftest.test.ts (free suite). Touchfiles: harness added to the three benchmark dep lists; the auq-repetition-cut-ab tier comment now states the MANUAL re-run obligation honestly (periodic runs force EVALS_ALL, so dep lists cannot auto-trigger it). Co-Authored-By: Claude Fable 5 * chore: re-capture context-budget fixture after cycle-2 template deltas Co-Authored-By: Claude Fable 5 * fix(sandbox-doctor): keep both heredoc bodies under the 512B pipe-deadlock window The cycle-2 additions pushed the python-patch and bashrc heredocs into the 512-65536B window test/heredoc-pipe-deadlock.test.ts guards (sh scripts get no BASH_COMPAT escape hatch). Same content, tighter prose; the drift warning now reuses the patch pattern variable instead of a second literal. Co-Authored-By: Claude Fable 5 * fix(review): a gstack-shortcut marker only suppresses findings when its decision id resolves in the ledger Cross-model catch (Claude adversarial + Codex agreed): any diff author could fabricate a marker and silence Completeness review of that gap. Reviewers now resolve the dec-id via gstack-decision-search; an orphan marker is reported as a forged suppression, not honored as debt. Co-Authored-By: Claude Fable 5 * fix(autoplan): define the B2 gate path — accepted premise challenges amend the plan and re-run Eng The final gate offered B2 (respond to User Challenges) but the option handler table omitted it, leaving accepted challenges with no amendment or Eng re-review path. B2 now walks challenges one at a time; an accepted one amends the plan and re-runs Eng (the gate always reviews the final plan), sharing D's 3-cycle cap. Co-Authored-By: Claude Fable 5 * feat(evals): arm benchmark runs each fixture's functional oracle — correctness before LOC The plan's metric order is diff-quality FIRST, but cells never ran the fixtures' own run-tests.js, so a refusal, a broken implementation, and working code were indistinguishable in aggregates (Codex adversarial catch). Tasks with an oracle declare checkCmd; every cell records checks=pass|fail|none in the report line and eval store. Selftest pins the oracle declarations and that the planted bug fails its own check pre-fix. Co-Authored-By: Claude Fable 5 * fix(ship): check the bump's agentsDigest result; state the --regen-digest trust envelope honestly A failed digest regen warned and moved on — ship now instructs re-running the generator and staging the digest with the bump (the freshness check stays red otherwise). The 'no-op everywhere else' phrasing oversold safety: the step now names what executes and why that is inside the envelope Step 5 already opened (the repo's own test suite). Co-Authored-By: Claude Fable 5 * fix(test-runner): GSTACK_FREE_JOBS accepts digits only — parseInt truncation defeated the loud-failure contract '2abc' silently became 2 and '3.7' became 3 despite the error text claiming a positive-integer requirement. Strict /^\d+$/ pre-check; both shapes pinned. Co-Authored-By: Claude Fable 5 * fix(sandbox-doctor): atomic git-shim patch, :99-socket Xvfb check, dnf gate, non-interactive sudo - The /conductor/bin/git patch writes tmp-then-rename with a .orig backup — a concurrently spawned git can never exec a truncated shim. - Xvfb running-check looks for the :99 socket, not any-display pgrep. - Xvfb install is dnf-gated so non-dnf distros degrade to a warning instead of aborting the remaining fixes under set -eu. - The bashrc /dev/fd restore uses sudo -n || true — no password prompt at every shell start on non-passwordless machines. - BASH_COMPAT=50 keeps heredoc bodies off the bash pipe window. Co-Authored-By: Claude Fable 5 * fix(build): a failed agents-digest regen fails gen-skill-docs instead of deferring the red to CI Co-Authored-By: Claude Fable 5 * fix(browse): an untrustable TMPDIR (/, $HOME, a cwd ancestor) never widens the local allowlist TEMP_DIRS honors os.tmpdir() at daemon start; a daemon launched with TMPDIR=/ would have trusted the whole filesystem for local path validation for its lifetime. Subprocess pins cover /, $HOME, cwd-ancestor rejection and that a benign distinct TMPDIR (the sandbox recipe's $HOME/tmp) stays honored. Co-Authored-By: Claude Fable 5 * chore: zero-heads warning names the benign cause too; digest path declaration made load-bearing; ratchet re-capture - The ls-remote zero-heads warning no longer accuses an empty remote of running a laundering shim. - instructionTier.rulesFile now must equal the generator's DIGEST_RELPATH (and setup must print it) — the declaration fails with the real path instead of lying silently. Co-Authored-By: Claude Fable 5 * chore: file ship-time follow-ups in TODOS skillify HOME-override gate red (pre-existing, proven on main), the auq-verbose-vs-carved-ab branch-local ref, eval-store harvest union, evidence digest allow-path scoping, and the WS6-2 dead-frontmatter live-host verification deferral. Co-Authored-By: Claude Fable 5 * v1.73.0.0 chore: version bump + CHANGELOG — ponytail import wave Co-Authored-By: Claude Fable 5 * chore: raise ship skeleton parity ceiling — measured 75,592 after the v1.73 release-step prose The --regen-digest trust-envelope paragraph (Step 12) and the evidence-gate digest note (Step 16) grew the ship skeleton past the previous 75,420 ceiling. Re-measured per the deliberate-change protocol. Co-Authored-By: Claude Fable 5 * docs: update project documentation for v1.73.0.0 - README.md, docs/skills.md, AGENTS.md: /autoplan phase order corrected to CEO → design → DX → eng (eng always last); /review rows note the advisory simplification lens - docs/PROJECT_STRUCTURE.md: add agents-digest/, gen-agents-digest.ts, sandbox-doctor.sh, test-free-shards.ts to the annotated tree - CONTRIBUTING.md: document GSTACK_FREE_JOBS, GSTACK_FREE_RETRY_FLAKY, and the sandbox-doctor one-command fixer in the Tier 1 test section Co-Authored-By: Claude Fable 5 * docs: apply cross-model doc-review fixes for v1.73.0.0 - README.md: host table gains the OpenClaw explainer arm row (setup has the arm; the table claimed to match setup) - docs/skills.md: /review completeness-gaps section documents the gstack-shortcut(dec-) acknowledged-debt suppression and orphan-marker flagging; /autoplan deep-dive states the recommended-option default with the 6 principles as tie-breakers - CONTRIBUTING.md: host count 8 -> 10 (Hermes, GBrain), supported-hosts list completed - docs/TESTING_INTERNALS.md: sandbox recipe says to source ~/.bashrc after the doctor seeds it; GSTACK_FREE_JOBS wording fixed from "caps" to "overrides in either direction" (matches the un-clamped runner) Co-Authored-By: Claude Fable 5 * fix(test): temp-dirs asymmetry pins are topology-aware; TMPDIR probes are POSIX-only CI exposed two wrong assumptions in the new temp-dirs tests, neither a product bug: - The remote-serving asymmetry test assumed a distinct os.tmpdir() lies OUTSIDE TEMP_DIR, but the free-shard runner nests each child's TMPDIR inside /tmp on CI — a file there is under TEMP_DIR, so serving it remotely is legitimate. The test now pins the actual exfil boundary on every topology (a cwd project file is locally readable, never remotely servable) and branches the os.tmpdir() case on nested-vs-outside. Reproduced locally with TMPDIR=/tmp/nested-tmp before fixing. - The untrustable-TMPDIR subprocess probes set TMPDIR, which Windows os.tmpdir() ignores (reads TEMP/TMP) — and on Windows TEMP_DIR is DEFINED as os.tmpdir(), so the fixed+movable two-dir topology the guard filters does not exist there. Probes now skip on Windows with that rationale; the benign-TMPDIR assertion compares realpaths. Verified under all three POSIX topologies: TMPDIR=$HOME/tmp (outside), TMPDIR=/tmp/nested-tmp (CI shard shape), TMPDIR unset (identical). Co-Authored-By: Claude Fable 5 * fix(build): DIGEST_RELPATH is a forward-slash literal on every platform path.join built it with backslashes on Windows, so the wiring test's string comparisons against setup and hosts/*.ts (which carry the forward-slash literal) could never match there — windows-free-tests red. path.join(root, DIGEST_RELPATH) at the write site normalizes fine. Co-Authored-By: Claude Fable 5 * fix(sandbox-doctor): bashrc block re-heals the /dev/shm remount on sandbox restart The 4G remount does not survive restarts; a reverted 64M shm made the multi-tab browse handoff test fail consistently under suite concurrency (observed live: two consecutive full-run failures, green in isolation, green again after remounting). Same guarded arithmetic as the doctor body. Co-Authored-By: Claude Fable 5 * fix(test): close the cross-shard porcelain race that failed Windows CI Two-part fix for the gen-skill-docs-out-dir isolation-pin failure: - cookie-import-browser built its scratch cookie DBs inside the TRACKED browse/test/fixtures/ dir (created in beforeAll, deleted in afterAll), so they flash as untracked files mid-run — a concurrent shard's porcelain snapshot caught the window on Windows. The DBs now live in a per-run tmpdir; zero source-tree writes. - gen-skill-docs-out-dir is the free suite's only LIVE porcelain-snapshot test, so it joins TREE_MUTATING (the serial quiet window): any concurrent transient tree-write can race it, and its own spawned render rewrites llms.txt/agents-digest in place (idempotent on a fresh tree). The race is pre-existing; this branch's +5 test files reshuffled shard composition and exposed it. Co-Authored-By: Claude Fable 5 * v1.75.0.0 chore: queue-advance rebump — perth-v2 landed v1.74.0.0 on main The v1.73.0.0 slot this branch claimed was superseded when #2721 merged; same MINOR level relative to main per the versioning invariant. CHANGELOG entry renumbered (1.73.0.0 was branch-internal and never landed on main), digest restamped via --regen-digest. Co-Authored-By: Claude Fable 5 * fix(test-runner): duration-packed walls keep the per-file floor — predictions don't transfer across machines The committed duration seed is recorded on fast CI; a syscall-supervised sandbox replays the same files 2-4x slower. Observed post-merge: a 253-file shard predicted ~242s was wall-killed at its predicted-x3 725s wall while genuinely progressing (the old count heuristic guaranteed 1265s). Packed walls may be looser than the count floor, never tighter. Co-Authored-By: Claude Fable 5 --------- Co-authored-by: Claude Fable 5 --- AGENTS.md | 2 +- CHANGELOG.md | 62 + CONTRIBUTING.md | 12 +- README.md | 33 +- TODOS.md | 65 + VERSION | 2 +- agents-digest/gstack-AGENTS.md | 35 + autoplan/SKILL.md | 116 +- autoplan/SKILL.md.tmpl | 85 +- autoplan/sections/ceo-phase.md | 13 +- autoplan/sections/ceo-phase.md.tmpl | 13 +- autoplan/sections/dx-phase.md | 8 +- autoplan/sections/dx-phase.md.tmpl | 8 +- autoplan/sections/eng-phase.md | 5 +- autoplan/sections/eng-phase.md.tmpl | 5 +- autoplan/sections/manifest.json | 6 +- bin/gstack-next-version | 54 +- bin/gstack-version-bump | 57 +- browse/src/path-security.ts | 8 +- browse/src/platform.ts | 21 + browse/test/commands.test.ts | 94 +- browse/test/cookie-import-browser.test.ts | 8 +- browse/test/temp-dirs.test.ts | 129 ++ canary/SKILL.md | 17 +- codex/SKILL.md | 27 +- context-restore/SKILL.md | 17 +- context-save/SKILL.md | 17 +- cso/SKILL.md | 17 +- design-consultation/SKILL.md | 27 +- design-html/SKILL.md | 17 +- design-review/SKILL.md | 27 +- design-shotgun/SKILL.md | 17 +- devex-review/SKILL.md | 27 +- docs/PROJECT_STRUCTURE.md | 6 +- docs/TESTING_INTERNALS.md | 22 + docs/skills.md | 8 +- document-generate/SKILL.md | 17 +- document-release/SKILL.md | 17 +- health/SKILL.md | 17 +- hosts/hermes.ts | 7 + hosts/openclaw.ts | 7 + investigate/SKILL.md | 17 +- ios-clean/SKILL.md | 17 +- ios-design-review/SKILL.md | 17 +- ios-fix/SKILL.md | 17 +- ios-qa/SKILL.md | 27 +- ios-sync/SKILL.md | 17 +- land-and-deploy/SKILL.md | 27 +- land-and-deploy/sections/readiness-gate.md | 2 +- .../sections/readiness-gate.md.tmpl | 2 +- landing-report/SKILL.md | 17 +- learn/SKILL.md | 17 +- office-hours/SKILL.md | 27 +- package.json | 2 +- pair-agent/SKILL.md | 17 +- plan-ceo-review/SKILL.md | 27 +- plan-design-review/SKILL.md | 27 +- plan-devex-review/SKILL.md | 27 +- plan-eng-review/SKILL.md | 27 +- plan-tune/SKILL.md | 17 +- qa-only/SKILL.md | 27 +- qa/SKILL.md | 27 +- retro/SKILL.md | 48 +- retro/SKILL.md.tmpl | 31 + review/SKILL.md | 27 +- review/checklist.md | 9 +- review/sections/review-army.md | 31 +- review/specialists/simplification.md | 49 + scripts/gen-agents-digest.ts | 95 ++ scripts/gen-skill-docs.ts | 16 + scripts/host-config.ts | 7 + .../preamble/generate-ask-user-format.ts | 12 +- .../generate-search-before-building.ts | 10 + .../preamble/generate-voice-directive.ts | 7 +- scripts/resolvers/review-army.ts | 31 +- scripts/resolvers/types.ts | 6 +- scripts/sandbox-doctor.sh | 126 ++ scripts/test-free-shards.ts | 111 +- setup | 19 +- setup-deploy/SKILL.md | 17 +- setup-gbrain/SKILL.md | 17 +- ship/SKILL.md | 39 +- ship/SKILL.md.tmpl | 12 +- ship/sections/review-army.md | 31 +- skillify/SKILL.md | 17 +- spec/SKILL.md | 27 +- sync-gbrain/SKILL.md | 17 +- test/agents-digest.test.ts | 112 ++ test/arm-benchmark-selftest.test.ts | 235 ++++ test/autoplan-phase-order.test.ts | 70 + .../arm-benchmark/bugfix-decoys/README.md | 8 + .../arm-benchmark/bugfix-decoys/package.json | 7 + .../arm-benchmark/bugfix-decoys/run-tests.js | 8 + .../arm-benchmark/bugfix-decoys/src/config.js | 7 + .../bugfix-decoys/src/format-price.js | 8 + .../arm-benchmark/crud-endpoint/app.js | 26 + .../arm-benchmark/crud-endpoint/package.json | 7 + .../arm-benchmark/crud-endpoint/run-tests.js | 17 + .../arm-benchmark/crud-endpoint/server.js | 22 + .../arm-benchmark/native-overbuild/app.js | 9 + .../arm-benchmark/native-overbuild/index.html | 20 + .../arm-benchmark/native-overbuild/styles.css | 14 + .../arm-benchmark/reference/bad-diff.patch | 116 ++ .../arm-benchmark/reference/good-diff.patch | 29 + .../auq-pre-cut-plan-ceo-review-SKILL.md | 1127 +++++++++++++++++ test/fixtures/context-budget.json | 80 +- test/fixtures/golden/claude-ship-SKILL.md | 39 +- test/fixtures/golden/codex-ship-SKILL.md | 39 +- test/fixtures/golden/factory-ship-SKILL.md | 70 +- test/fixtures/review-army-lean-complete.js | 28 + test/fixtures/review-army-overbuild.js | 68 + test/gen-skill-docs.test.ts | 27 + test/gstack-next-version.test.ts | 105 +- test/gstack-version-bump.test.ts | 95 +- test/helpers/arm-benchmark-harness.ts | 235 ++++ test/helpers/carve-guards.ts | 38 +- test/helpers/e2e-helpers.ts | 1 + test/helpers/eval-store.test.ts | 2 +- test/helpers/eval-store.ts | 22 +- test/helpers/llm-judge.ts | 138 +- test/helpers/observability.test.ts | 2 +- test/helpers/touchfiles-data.ts | 44 + test/redact-engine.test.ts | 9 + test/sandbox-doctor-shell.test.ts | 34 + test/shortcut-debt-ledger.test.ts | 105 ++ test/skill-e2e-arm-benchmark.test.ts | 241 ++++ test/skill-e2e-auq-repetition-cut-ab.test.ts | 124 ++ test/skill-e2e-autoplan-chain.test.ts | 20 +- test/skill-e2e-review-army.test.ts | 125 ++ test/test-free-shards-sandbox-knobs.test.ts | 164 +++ test/test-free-shards.test.ts | 15 + test/touchfiles.test.ts | 6 +- 132 files changed, 5535 insertions(+), 549 deletions(-) create mode 100644 agents-digest/gstack-AGENTS.md create mode 100644 browse/test/temp-dirs.test.ts create mode 100644 review/specialists/simplification.md create mode 100644 scripts/gen-agents-digest.ts create mode 100755 scripts/sandbox-doctor.sh create mode 100644 test/agents-digest.test.ts create mode 100644 test/arm-benchmark-selftest.test.ts create mode 100644 test/autoplan-phase-order.test.ts create mode 100644 test/fixtures/arm-benchmark/bugfix-decoys/README.md create mode 100644 test/fixtures/arm-benchmark/bugfix-decoys/package.json create mode 100644 test/fixtures/arm-benchmark/bugfix-decoys/run-tests.js create mode 100644 test/fixtures/arm-benchmark/bugfix-decoys/src/config.js create mode 100644 test/fixtures/arm-benchmark/bugfix-decoys/src/format-price.js create mode 100644 test/fixtures/arm-benchmark/crud-endpoint/app.js create mode 100644 test/fixtures/arm-benchmark/crud-endpoint/package.json create mode 100644 test/fixtures/arm-benchmark/crud-endpoint/run-tests.js create mode 100644 test/fixtures/arm-benchmark/crud-endpoint/server.js create mode 100644 test/fixtures/arm-benchmark/native-overbuild/app.js create mode 100644 test/fixtures/arm-benchmark/native-overbuild/index.html create mode 100644 test/fixtures/arm-benchmark/native-overbuild/styles.css create mode 100644 test/fixtures/arm-benchmark/reference/bad-diff.patch create mode 100644 test/fixtures/arm-benchmark/reference/good-diff.patch create mode 100644 test/fixtures/auq-pre-cut-plan-ceo-review-SKILL.md create mode 100644 test/fixtures/review-army-lean-complete.js create mode 100644 test/fixtures/review-army-overbuild.js create mode 100644 test/helpers/arm-benchmark-harness.ts create mode 100644 test/sandbox-doctor-shell.test.ts create mode 100644 test/shortcut-debt-ledger.test.ts create mode 100644 test/skill-e2e-arm-benchmark.test.ts create mode 100644 test/skill-e2e-auq-repetition-cut-ab.test.ts create mode 100644 test/test-free-shards-sandbox-knobs.test.ts diff --git a/AGENTS.md b/AGENTS.md index cef8c05f8..7d802490e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,7 +19,7 @@ Invoke them by name (e.g., `/office-hours`). | `/plan-design-review` | Rate each design dimension 0-10, explain what a 10 looks like. | | `/plan-devex-review` | DX-mode review: TTHW, magical moments, friction points, persona traces. | | `/plan-tune` | Self-tune AskUserQuestion sensitivity per question. | -| `/autoplan` | One command runs CEO → design → eng → DX review. | +| `/autoplan` | One command runs CEO → design → DX → eng review (eng always last). | | `/design-consultation` | Build a complete design system from scratch. | | `/spec` | Turn vague intent into a precise, executable spec in five phases. Files a GitHub issue, optionally spawns a Claude Code agent in a fresh worktree, and lets `/ship` close the source issue on merge. | diff --git a/CHANGELOG.md b/CHANGELOG.md index 316624c15..6c5b26322 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,67 @@ # Changelog +## [1.75.0.0] - 2026-08-29 + +**Your review now hunts over-built code, not just broken code.** +**And every skill's advice starts with "reuse before you build."** + +This release imports the best of ponytail, the code-minimalism ruleset, without importing its build-less posture. /review gains an eighth lens: a simplification specialist that flags unrequested structure (hand-rolled stdlib, one-implementation abstractions, dead flexibility, dependencies duplicating platform features) in a closed five-tag vocabulary. It is advisory only. It cannot dent your quality score, its fixes are never auto-applied, and on a lean diff it tells you something no reviewer ever says: "lean already — nothing to cut." Every tier-2+ skill also gains the reuse ladder (stop at the first rung that holds: this repo, stdlib, native platform, an installed dependency... then build the complete version of what remains) and a bounded closer, so completion reports stop touring every edit. Accepted shortcuts now leave a durable trail: a decision-ledger entry plus a `gstack-shortcut(dec-)` marker in code, harvested into a debt ledger by /retro. Agent hosts without a full install (Zed, Amp, Cursor side projects) get a 1.8KB rules digest to copy into their own rules file. And /autoplan now runs the Eng review last, always, so the required shipping gate reviews the final amended plan instead of a stale one. + +### The numbers that matter + +Source: this branch's own runs, recorded under `~/.gstack/projects//evals/` and the commit receipts. + +| Metric | Before | After | Δ | +|---|---|---|---| +| /review lenses | 7 | 8 (simplification, advisory) | +1 | +| Simplification lens on this branch's own 5,190-line diff | n/a | `net: -37 lines possible` | dogfooded | +| AskUserQuestion preamble section, per skill | baseline | -236 B (~9.7 KB across 41 skills) | gated by a live A/B: post-cut 7/7 format elements, substance equal to pre-cut | +| Instruction-tier artifact for rules-reading hosts | none | 1,765 B committed digest (2,048 B budget) | new | +| Skills-earn-their-tokens benchmark | none | 3 tasks x 2 arms (with/without skill), judged on the diff left behind | new | +| /autoplan phase order | CEO, Design, Eng, DX | CEO, Design, DX, Eng always last | the gate sees the final plan | + +The A/B receipt is the one to trust: the AskUserQuestion cut only landed because a two-arm eval on real SDK captures showed the shorter render lost nothing (the gate outranked the approval, by design). + +### What this means for your workflow + +Run /review on a branch you suspect is over-built and read the `[ADVISORY]` rows plus the `net: -N lines possible` footer; nothing blocks, nothing auto-applies, you decide. Take a shortcut in an AskUserQuestion and it stops rotting silently: /retro reads the ledger back to you with its upgrade trigger. If you work in a rules-reading editor without a gstack install, copy `agents-digest/gstack-AGENTS.md` into your rules file and the ethos rides along. + +### Itemized changes + +### Added + +- **Simplification review specialist** (`review/specialists/simplification.md`): closed tag vocabulary (`delete:` / `stdlib:` / `native:` / `speculative:` / `shrink:`), dispatched on diffs over 100 lines, `--simplification` force flag. Advisory carve-out end to end: excluded from the quality score and findings-count header, ASK-only in Fix-First, `[ADVISORY]` labels, parent-printed `net: -N lines possible` footer, and a `Simplification: lean already — nothing to cut.` zero-findings line. Precision guarded by a false-flag fixture (a complete-but-lean diff must yield NO FINDINGS) and coverage-vs-structure boundary text (tests, error paths, and edge cases are never deletion targets). +- **Reuse ladder in Search Before Building** (every tier-2+ skill): before writing new code, stop at the first rung that holds — a helper already in the repo, the stdlib, a native platform feature, an already-installed dependency — then build the complete version of what remains. Root-cause rule included: one guard in the shared function beats a guard in every caller. +- **Bounded closer** (every tier-2+ skill): after completing work, report what changed, what was skipped, what to watch — a few short lines, with report-shaped skills (/qa-only, /plan-*-review, /retro, /document-generate) explicitly exempt because their report IS the work. +- **Shortcut debt ledger**: accepting a Completeness ≤ 7 option on a durable-scope call now logs the ceiling and upgrade trigger to the decision ledger and marks each cut corner with `gstack-shortcut(dec-): , upgrade when `; /retro Step 11.5 harvests the markers, joins them on decision ids, and tags `unlinked` and `no-trigger` rot risks. Markers survive the redaction engine (pinned by test). +- **Instruction-only host tier**: `agents-digest/gstack-AGENTS.md`, a committed, generated, budget-capped (2,048 B) digest of the ethos, reuse ladder, and voice rules. Setup's openclaw/hermes explainer arms print its path for copy-in; setup never writes a user's AGENTS.md (tripwire-tested, including laundered write shapes). README's host table now matches what setup actually does. +- **With/without-skill arm benchmark** (periodic eval): three build-shaped tasks (a native-platform overbuild trap, a CRUD endpoint, a bugfix with planted decoys) run through real `claude -p` sessions twice — with the behavioral-layer skill installed and without — and the staged diff each arm leaves is judged for over-engineering on a 0-3 rubric with a full failure taxonomy (judge_error cells excluded from aggregates but surfaced; zero-diff arms are valid cells). Each cell also runs the fixture's own functional oracle (`checks=pass|fail|none`), so a refusal, a broken implementation, and working code stay distinguishable — correctness before LOC. A research instrument, not a gate. +- **/autoplan runs Eng last, always**: mandatory order is now CEO → Design (if UI scope) → DX (if developer-facing scope) → Eng, with a single final approval gate; clearly-wrong premises queue as User-Challenge items instead of stopping mid-run, and accepting one at the gate amends the plan and re-runs Eng on the amended plan. Static test pins the Eng-terminal order. + +### Changed + +- **AskUserQuestion preamble section slimmed** (-236 B per skill, ~9.7 KB across the corpus): duplicate statements of the completeness rule, auto-decide marker, and tool-not-prose rule removed while keeping every verbosity floor and all 14 format pins. Landed only after a live NOT-WORSE A/B (pre-cut vs post-cut render, identical prompt, SDK capture) showed zero format-element loss and equal recommendation substance. +- **Terse-mode label tells the truth**: the claimed savings is now the measured 2.6 KB, not "~3-5 KB". +- `/review` checklist knows Completeness Gaps and Simplification are orthogonal (coverage up, structure down), and a `gstack-shortcut` marker downgrades a would-be gap finding to acknowledged debt — but only when its decision id resolves in the ledger; an orphan marker is reported as a forged suppression (cross-model adversarial catch). + +### Fixed + +- **Version bumps no longer strand the agents digest**: `gstack-version-bump write --regen-digest` reruns the repo's digest generator in the same mutation (explicit opt-in — a plain `write` never executes repo files it merely finds), and both ship's and land-and-deploy's evidence gates allow-list the digest alongside VERSION. Without this, every release commit of this repo would have failed the freshness CI check. +- **The free-suite flaky retry can no longer mask real failures**: the retry pass vetoes on ANY unattributable failure evidence (headerless failures, unhandled errors between tests, truncated runs), an empty shard carries an empty failing-files list instead of crashing the retry, and a dead conditional was removed. +- **Version allocation distrusts laundered git**: `gstack-next-version` consults `ls-remote` only when origin is actually configured, and a configured origin that "successfully" advertises zero heads (the Conductor git shim's failure shape) now falls back to local refs with a loud warning instead of reading an empty queue and reallocating a taken version. Both shim shapes are pinned by regression tests. +- **Browse temp paths are portable**: local file serving accepts both the browse TEMP_DIR and the OS tmpdir (`TEMP_DIRS` allowlist), while remote serving stays pinned to TEMP_DIR only (the security asymmetry is test-enforced). An untrustable TMPDIR (`/`, `$HOME`, an ancestor of the daemon's cwd) is ignored rather than trusted for the daemon's lifetime. +- Setup's instruction-tier pointer prints a script-anchored digest path instead of a cwd-relative one that broke when invoked from another directory. +- /retro's shortcut harvest no longer reports phantom debt from files that merely document the marker convention (placeholder filter + judgment prose). +- The arm benchmark harvests against a recorded seed commit (immune to agents that commit and push), ignores node_modules, survives multi-megabyte patches, names its judge-diff cap and reports truncation loudly, and wraps untrusted diffs in per-call random sentinels so a faked closing marker cannot steer the judge. +- The AUQ A/B eval treats a judge failure on either side as inconclusive instead of coercing it to a fake degradation-or-mask, and reads its pre-cut arm from a vendored fixture instead of a branch-local SHA that dies with the branch. + +### For contributors + +- `bun run test` gains sandbox knobs: `GSTACK_FREE_JOBS` overrides shard count (digits-only, loud on garbage) and `GSTACK_FREE_RETRY_FLAKY=1` opts into one serial retry pass for syscall-supervised sandboxes (default stays OFF — dev boxes should see flakes). `scripts/sandbox-doctor.sh` makes a Vercel/Conductor cloud sandbox run the suite green in one idempotent command (documented in docs/TESTING_INTERNALS.md): atomic git-shim patching with a backup, loud on patch-pattern drift, :99-socket Xvfb detection, dnf-gated installs, and it survives a missing /dev/shm. A failed digest regen now fails `bun run gen:skill-docs` locally instead of deferring the red to CI. +- The arm-benchmark selftest (fixture integrity, judge plumbing, install asymmetry) now runs FREE in `bun run test` on every PR via `test/arm-benchmark-selftest.test.ts` — the paid periodic instrument can no longer burn money on broken fixtures. +- Eval-store schema v2: harvest records carry `{insertions, deletions, net}`; `recordE2E` now populates `tokens_used`. +- Touchfiles dep lists closed gaps (fixtures, judge helper, harness, ship render) and the context-budget ratchet fixture was re-captured, locking the AskUserQuestion reduction so it cannot silently regress. +- New coverage: TEMP_DIRS widening + remote-serving asymmetry, shortcut-marker writer/harvester grammar joint, sandbox-doctor shell guards, GSTACK_FREE_JOBS parsing, laundered-ls-remote shims, digest freshness/budget/writer tripwires, and a real generator round-trip through the version bump. ## [1.74.0.0] - 2026-08-29 **Green now means green: every test runs somewhere, provably.** diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a301a1ff8..f81afc0b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -166,6 +166,12 @@ concurrent shard processes under a strict output contract — a shard that exits without bun's own terminal summary line, or a crashed worker, fails the run, so silent truncation can never report green. Pass `--verbose` to forward the full child stream; `--wall-timeout ` overrides the per-shard kill deadline. +`GSTACK_FREE_JOBS=` overrides the shard count (digits only, loud on garbage), +and `GSTACK_FREE_RETRY_FLAKY=1` opts into one serial retry pass for +syscall-supervised sandboxes (off by default — dev boxes should see flakes). +Working in a cloud sandbox? Run `scripts/sandbox-doctor.sh` once per boot to +make the suite run green (details in +[docs/TESTING_INTERNALS.md](docs/TESTING_INTERNALS.md)). Don't type bare `bun test` for the suite: it walks the whole repo, loads paid eval files, and misses the strict classifier. No API keys needed. @@ -353,11 +359,11 @@ worth the review overhead. ## Multi-host development -gstack generates SKILL.md files for 8 hosts from one set of `.tmpl` templates. +gstack generates SKILL.md files for 10 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). -**Supported hosts:** Claude (primary), Codex, Factory, Kiro, OpenCode, Slate, Cursor, OpenClaw. +**Supported hosts:** Claude (primary), Codex, Factory, Kiro, OpenCode, Slate, Cursor, OpenClaw, Hermes, GBrain. ### Generating for all hosts @@ -366,7 +372,7 @@ to produce host-appropriate output (different frontmatter, paths, tool names). bun run gen:skill-docs # Claude (default) bun run gen:skill-docs --host codex # Codex bun run gen:skill-docs --host opencode # OpenCode -bun run gen:skill-docs --host all # All 8 hosts +bun run gen:skill-docs --host all # All 10 hosts # Or use build, which does all hosts + compiles binaries bun run build diff --git a/README.md b/README.md index 7b2b9305e..cb76f65a8 100644 --- a/README.md +++ b/README.md @@ -111,16 +111,23 @@ cd ~/gstack && ./setup Or target a specific agent with `./setup --host `: -| Agent | Flag | Skills install to | -|-------|------|-------------------| -| OpenAI Codex CLI | `--host codex` | `${CODEX_HOME:-~/.codex}/skills/gstack-*/` | -| OpenCode | `--host opencode` | `~/.config/opencode/skills/gstack-*/` | -| Cursor | `--host cursor` | `~/.cursor/skills/gstack-*/` | -| Factory Droid | `--host factory` | `~/.factory/skills/gstack-*/` | -| Slate | `--host slate` | `~/.slate/skills/gstack-*/` | -| Kiro | `--host kiro` | `~/.kiro/skills/gstack-*/` | -| Hermes | `--host hermes` | `~/.hermes/skills/gstack-*/` | -| GBrain (mod) | `--host gbrain` | `~/.gbrain/skills/gstack-*/` | +| Agent | Flag | What you get | +|-------|------|--------------| +| OpenAI Codex CLI | `--host codex` | Full install → `${CODEX_HOME:-~/.codex}/skills/gstack-*/` | +| OpenCode | `--host opencode` | Full install → `~/.config/opencode/skills/gstack-*/` | +| Cursor | `--host cursor` | Full install → `~/.cursor/skills/gstack-*/` | +| Factory Droid | `--host factory` | Full install → `~/.factory/skills/gstack-*/` | +| Kiro | `--host kiro` | Full install → `~/.kiro/skills/gstack-*/` | +| Slate | `--host slate` | Pointer to the Claude install (Slate reads `.claude/skills` as a fallback) | +| OpenClaw | `--host openclaw` | ACP spawn pointers + methodology artifacts via `gen:skill-docs --host openclaw` + the instruction-only digest below (full guide: [docs/OPENCLAW.md](docs/OPENCLAW.md)) | +| Hermes | `--host hermes` | Methodology artifacts via `gen:skill-docs --host hermes` + the instruction-only digest below | +| GBrain (mod) | `--host gbrain` | Brain-aware skill variants, shipped from the GBrain repo | + +**Instruction-only tier (any rules-reading agent — Zed, Amp, Jules, side projects):** +copy the 2KB digest at [`agents-digest/gstack-AGENTS.md`](agents-digest/gstack-AGENTS.md) +into a location your agent reads (for example, append it to your project's `AGENTS.md`). +It carries gstack's ethos, reuse ladder, and voice rules — no install required. The +digest's first line shows its gstack version; re-copy it after upgrading. For Codex, setup reads the top-level `model` from `${CODEX_HOME:-~/.codex}/config.toml` and generates the matching behavioral @@ -195,7 +202,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan- | `/plan-design-review` | **Senior Designer** | Rates each design dimension 0-10, explains what a 10 looks like, then edits the plan to get there. AI Slop detection. Interactive — one AskUserQuestion per design choice. | | `/plan-devex-review` | **Developer Experience Lead** | Interactive DX review: explores developer personas, benchmarks against competitors' TTHW, designs your magical moment, traces friction points step by step. Three modes: DX EXPANSION, DX POLISH, DX TRIAGE. 20-45 forcing questions. | | `/design-consultation` | **Design Partner** | Build a complete design system from scratch. Researches the landscape, proposes creative risks, generates realistic product mockups. | -| `/review` | **Staff Engineer** | Find the bugs that pass CI but blow up in production. Auto-fixes the obvious ones. Flags completeness gaps. | +| `/review` | **Staff Engineer** | Find the bugs that pass CI but blow up in production. Auto-fixes the obvious ones. Flags completeness gaps. Advisory simplification lens flags over-built code — never blocks, never auto-applies. | | `/investigate` | **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. | | `/design-review` | **Designer Who Codes** | Same audit as /plan-design-review, then fixes what it finds. Atomic commits, before/after screenshots. | | `/devex-review` | **DX Tester** | Live developer experience audit. Actually tests your onboarding: navigates docs, tries the getting started flow, times TTHW, screenshots errors. Compares against `/plan-devex-review` scores — the boomerang that shows if your plan matched reality. | @@ -214,7 +221,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan- | `/retro` | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. `/retro global` runs across all your projects and AI tools (Claude Code, Codex, Gemini). | | `/browse` | **QA Engineer** | Give the agent eyes. Real Chromium browser, real clicks, real screenshots. ~100ms per command. `/open-gstack-browser` launches GStack Browser with sidebar, anti-bot stealth, and auto model routing. | | `/setup-browser-cookies` | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. | -| `/autoplan` | **Review Pipeline** | One command, fully reviewed plan. Runs CEO → design → eng review automatically with encoded decision principles. Surfaces only taste decisions for your approval. | +| `/autoplan` | **Review Pipeline** | One command, fully reviewed plan. Runs CEO → design → DX → eng review automatically (eng always last, so the shipping gate reviews the final amended plan) with encoded decision principles. Surfaces only taste decisions for your approval. | | `/spec` | **Spec Author** | Turn vague intent into a precise, executable spec in five phases (why, scope, technical with mandatory code-reading, draft, file). Codex quality gate before file (blocks below 7/10), fail-closed secret redaction, dedupe against existing issues, archive to `$GSTACK_STATE_ROOT/projects/$SLUG/specs/` for team-corpus recall. `--execute` spawns `claude -p` in a fresh worktree; `/ship` auto-closes the source issue on merge. Plan-mode aware. | | `/learn` | **Memory** | Manage what gstack learned across sessions. Review, search, prune, and export project-specific patterns, pitfalls, and preferences. Learnings compound across sessions so gstack gets smarter on your codebase over time. | | `/make-pdf` | **Publisher** | Markdown in, publication-quality document out. Mermaid and excalidraw fences render as vector diagrams, fully offline. Images scale to the page and never truncate; wide diagrams get their own landscape page. `--to html` emits one self-contained file, `--to docx` a Word doc. | @@ -227,7 +234,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan- | **End users** (UI, web app, mobile) | `/plan-design-review` | `/design-review` | | **Developers** (API, CLI, SDK, docs) | `/plan-devex-review` | `/devex-review` | | **Architecture** (data flow, perf, tests) | `/plan-eng-review` | `/review` | -| **All of the above** | `/autoplan` (runs CEO → design → eng → DX, auto-detects which apply) | — | +| **All of the above** | `/autoplan` (runs CEO → design → DX → eng, auto-detects which apply; eng always last) | — | ### Power tools diff --git a/TODOS.md b/TODOS.md index 71e8ab974..7be847dde 100644 --- a/TODOS.md +++ b/TODOS.md @@ -491,6 +491,71 @@ audit trail lives in Aside. ## Test infrastructure +### P1: skillify gate test red — HOME-override sessions never discover project skills (pre-existing) + +**What:** `test/skill-e2e-skillify.test.ts` `skillify-provenance-refusal` fails +on BOTH this branch and origin/main @ b5a951e6 (proven 2026-08-29: identical +2-turn `Unknown skill: skillify` transcripts). Every test in that file passing +`env: { HOME: workDir }` gets ZERO seeded project skills in the session init +(claude CLI 2.1.237); the passing siblings recover by Reading the SKILL.md +directly, the refusal test's agent stops at the Skill error. Fix the harness +(seed skills wherever HOME-overridden discovery looks, or drop the HOME +override and pass the write target another way), or report upstream if +project-scope `.claude/skills` discovery genuinely keys off HOME. + +**Why:** A gate-tier safety test that is red for environmental reasons trains +people to ignore gate reds. + +**Effort:** S-M (harness). **Priority:** P1 (gate hygiene). + +### P2: auq-verbose-vs-carved-ab PRE arm reads a branch-local ref (same fragility class the repetition-cut A/B just fixed) + +**What:** `test/helpers/auq-sdk-capture.ts` `verboseSkill()` defaults to git ref +`ab66193e^`, reachable only from the token-usage-reduction branch — shallow +clones fail today, all clones fail after that branch is pruned. Vendor the +pre-carve render as a fixture the way `auq-pre-cut-plan-ceo-review-SKILL.md` +was vendored for the repetition-cut A/B (v1.75.0.0), or repoint at a +main-reachable commit. + +**Effort:** S. **Priority:** P2 (weekly periodic breaks silently later). + +### P3: eval-store harvest as a discriminated union + +**What:** `EvalTestEntry.harvest` went all-optional in schema v2 (worktree +harvests carry patchPath/isDuplicate, arm-benchmark diff-stats carry +insertions/deletions/net) — compile-time safety for the two writer shapes now +rests on a comment. Model as `{kind:'worktree',...} | {kind:'diff-stat',...}`. +Filed from the v1.73 review army (maintainability); deferred at ship time to +avoid schema churn mid-release. + +**Effort:** S. **Priority:** P3. + +### P2: WS6-2 dead-frontmatter strip — needs a live host, not a sandbox + +**What:** `bin/gstack-context-bill` warns about 14 frontmatter keys "the router +never reads" (ROUTER_KEYS in lib/context-bill.ts is a hand-maintained guess). +The approved ponytail-import plan mandates EMPIRICAL verification before +stripping: remove the keys in a scratch install on a LIVE Claude Code host, +confirm skill discovery/routing/hooks unchanged, then land via the +hosts/claude.ts denylist (keys stay in templates for gen tooling). Deferred at +v1.73 implementation time with a decision-ledger entry (2026-08-28) because the +cloud sandbox cannot exercise live-host discovery. Savings are hundreds of +always-on bytes; growth is already capped by the ratchet regardless. + +**Effort:** S (once on a live host). **Priority:** P2. + +### P3: scope the evidence-gate digest allow-path + +**What:** `agents-digest/gstack-AGENTS.md` rides `--allow-paths` in ship's and +land-and-deploy's evidence checks in EVERY repo, and unlike CHANGELOG/VERSION +it is instruction-bearing for rules-reading hosts. Scope the exemption to +"the bump actually regenerated it" (e.g. gstack-evidence learns a +--allow-if-regenerated flag, or the check compares the digest bytes to a fresh +generator run). Filed from the v1.73 Claude adversarial pass; the gate is +advisory and gstack's freshness CI covers the drift case, so P3. + +**Effort:** S-M. **Priority:** P3. + ### 2026-08-29 test-infra overhaul — follow-ups (filed at implementation) The overhaul landed: green-means-green fixes (make-pdf gates in the required diff --git a/VERSION b/VERSION index e8df5e2eb..2fbbd2a2f 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.74.0.0 +1.75.0.0 diff --git a/agents-digest/gstack-AGENTS.md b/agents-digest/gstack-AGENTS.md new file mode 100644 index 000000000..3054cd1ee --- /dev/null +++ b/agents-digest/gstack-AGENTS.md @@ -0,0 +1,35 @@ +# gstack digest v1.75.0.0 — regenerate/re-copy after upgrading gstack + +Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed +for agent hosts without a full skill install. The full skills add workflows, +reviews, and evals on top of these rules. + +## Ethos + +- **Boil the Ocean** — AI makes completeness cheap, so do the complete thing: tests, edge cases, error paths. Shortcuts need an explicit, recorded decision. +- **Search Before Building** — know what exists before deciding what to build. Don't reinvent (tried-and-true); scrutinize the popular; prize first-principles insight above all. +- **User Sovereignty** — models recommend, the user decides. Cross-model agreement is signal, never permission. Ask before changing the user's stated direction. +- **Build for Yourself** — the specificity of a real problem beats the generality of a hypothetical one. + +## The reuse ladder + +Before writing new code, stop at the first rung that holds: +1. A helper, util, or pattern already in this repo. +2. The standard library. +3. A native platform feature (CSS over JS, DB constraint over app code). +4. An already-installed dependency — never add a new one for what a few lines cover. + +Then build the complete version of what remains. Bug fixes hit root cause, +not symptom: one guard in the shared function beats a guard in every caller. + +## Voice + +Direct, concrete, builder-to-builder. Name the file, function, command, and +user-visible impact. Short paragraphs; end with what to do. No filler, no +corporate tone, no AI vocabulary. + +## Full gstack + +Clone https://github.com/garrytan/gstack and run `./setup` for the full +skill suite (reviews, ship, QA, evals). This digest is generated — edit +scripts/gen-agents-digest.ts, not this file. diff --git a/autoplan/SKILL.md b/autoplan/SKILL.md index 0cc6c8dca..6e90fd372 100644 --- a/autoplan/SKILL.md +++ b/autoplan/SKILL.md @@ -79,7 +79,7 @@ If `SKILL_PREFIX` is `"true"`, suggest/invoke `/gstack-*` names. Disk paths stay Branch on the skill-start STATUS lines, in this order: -1. **`CONDUCTOR_SESSION: true` echoed** → do NOT call AskUserQuestion at all (neither native nor any `mcp__*__AskUserQuestion` variant): render EVERY decision brief as the **prose form** below and STOP. Proactive, not a failure reaction — Conductor disables native AUQ and its MCP variant is flaky (`[Tool result missing due to internal error]`). **Auto-decide preferences still apply first:** a surfaced `[plan-tune auto-decide] →