Skip to content

Commit 2cc432e

Browse files
authored
Merge pull request #5168 from open-gsd/refactor/5164-eval-scope-resolver
refactor(#5164): one evaluation-scope resolver for every gate and workflow step
2 parents 6eeaf87 + a6c1e85 commit 2cc432e

57 files changed

Lines changed: 2965 additions & 1380 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.changeset/kind-koalas-dance.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
type: Fixed
3+
pr: 5168
4+
---
5+
**Gates and workflows evaluate a phase, plan or quick task through one scope resolver** — code review, the UI safety and TDD checkpoint gates, decision-coverage verify, schema-drift, quick and the execute workflows no longer scope their work with `HEAD~1..HEAD`, `base..HEAD` ranges or any-branch commit lookups, so unrelated interleaved commits and commits that live only on another branch stop appearing in a phase's scope; a scope the resolver had to widen or could not read is reported by name instead of passing as empty. (#5164)

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -286,6 +286,7 @@ build/
286286
/gsd-core/bin/lib/gate-config.cjs
287287
/gsd-core/bin/lib/gate-decision-coverage-plan.cjs
288288
/gsd-core/bin/lib/gate-decision-coverage-verify.cjs
289+
/gsd-core/bin/lib/gate-evaluation-scope.cjs
289290
/gsd-core/bin/lib/gate-api-coverage-verify-pre.cjs
290291
/gsd-core/bin/lib/gate-gap-analysis-plan-post.cjs
291292
/gsd-core/bin/lib/gate-predicate.cjs

‎CONTEXT.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,12 @@ Module owning the value a `gsd-tools check <gate>` module returns (ADR-5057 §4,
4141
`SEAM.gate-verdict.owns=GateVerdict / GateResult (src/gate-verdict.cts) is the single value a check gate module returns; only the command router formats it (ADR-5057 §4, #5139)`
4242
`SEAM.gate-verdict.enforced-by=test:tests/gate-verdict.test.cjs`
4343

44+
### Evaluation Scope Module
45+
Module owning the answer to "which commits and which files does this gate or workflow step evaluate for this phase, plan or quick task?" (ADR-5057 §4, epic #5056, #5164). `resolveEvaluationScope(projectDir, unit, options) → EvaluationScope` (`src/gate-evaluation-scope.cts`, reached as `gsd_run check evaluation-scope`) returns the UNION of the unit's own commits' file sets — a phase's commits are the `## Task Commits` rows of its SUMMARY files, a plan's are the branch-reachable commits whose subject is `<type>(<phase>-<plan>):` — never a range, and only commits reachable from the evaluated ref. `status` is a closed set: `resolved`, `degraded` (the union was empty, so `files` come from the phase-directory range and `reason` says why) or `unresolvable` (git or the phase could not be read). What the union drops is named by path, not counted: `outsideUnion`, `unreachable`, `missingOnDisk`. It is a resolver, not a policy: it never blocks. `scripts/lint-evaluation-scope-drift.cjs` fails CI on a bespoke `git log --all`, `..HEAD` range, `HEAD~N` anchor, hand-rolled phase-start anchor or commit-message lookup in a gate module, `verify`, a workflow or an agent.
46+
47+
`SEAM.evaluation-scope.owns=resolveEvaluationScope(projectDir, unit, options) (src/gate-evaluation-scope.cts) is the single owner of which commits and files a gate or workflow step evaluates (ADR-5057 §4, #5164)`
48+
`SEAM.evaluation-scope.enforced-by=test:tests/evaluation-scope-drift-lint.test.cjs`
49+
4450
### Verification Module
4551
Module owning the canonical phase-verification status projection shared by phase transition, progress, manager, autonomous, and closeout readiness paths. `readVerificationStatus(phaseDir, opts?)` reads the phase's `*-VERIFICATION.md` frontmatter `status` and projects every answer through `VERIFICATION_ROUTES` — the ONE routing table, keyed by the closed enum `VERIFICATION_STATUS` (`passed`, `gaps_found`, `human_needed`, `stale`, `missing`, `unparseable`, `phase_dir_not_found`; #5118, ADR-5057 Phase 4) — adding the bare command it routes to as `route`. It fail-closes — only `{passed}` satisfies the canonical gate; every other member routes away from "complete" (#1522). A report may carry only the writer subset `VERIFIER_STATUSES` (`passed`, `gaps_found`, `human_needed`); any other value (a case variant, `verified`, a reader-only member, a non-string) throws `VerificationStatusError`, which the CLI reports once, centrally, as ERROR_REASON `verification_status_invalid` and `isPhaseComplete` maps to its UNREADABLE scope. A path with no phase directory behind it reads `phase_dir_not_found` (a usage error, no next command), never `missing`. `stale` has one route, `execute-phase`, whose regenerating action is the shared step `execute-phase/steps/verify-phase-goal.md` that verify-work's stale arm also runs. Staleness is one of TWO mutually exclusive checks, selected by whether the report DECLARES a fingerprint (#4155, i.e. either `covered_files` or `covered_digest` is present — a report that declares only one, or an empty/malformed pair, fails closed to `stale` rather than silently downgrading to the weaker legacy check): a report with a well-formed pair is checked by `computeCoveredDigest(projectRoot, coveredFiles)` — a deterministic sha256-of-sha256s over the SORTED, de-duplicated, `./`/`..`-canonicalized covered set, hashed by file BYTES always through the real `node:fs`, never a caller-injected `opts.fs` seam (`covered_files` spans the whole `projectRoot`, not just `.planning/`, so a caller-scoped containment wrapper narrower than `projectRoot` would reject legitimate covered files; the per-file re-check inside `computeCoveredDigest`/`deriveCoveredDigest` is the actual confinement boundary: an implementation path against `projectRoot`, a `.planning`-spelled one against the LONGEST-prefix ANCHORED planning scope `bestPlanningScopeForRel` selects — see the v3 entry below, #5095 R7 — OR `projectRoot`) — recomputed and compared to the stored digest. Fingerprint **v2** (#4623) leaves repo-wide planning documents — any DIRECT child of a planning root: `.planning/` itself, and the phase's own planning root (the parent of its `phases/`, so the `.planning/<project>/` and `workstreams/<ws>/` layouts of `planningDir` are covered without the digest knowing what a workstream is; `sharedPlanningRoots` / `isSharedPlanningDoc`, defined by position so the set cannot drift as new top-level documents appear) — OUT OF THE HASH while still validating them exactly as every other covered path (confined to `projectRoot`, present, a regular file — the fail-closed contract is unchanged; only the bytes are ignored): every phase rewrites them as ordinary bookkeeping, and the closing phase's own `phase.complete` / `requirements mark-complete` writes them AFTER the verifier ran, so under v1 a phase staled itself and every sibling that had declared them. A declaration consisting ONLY of shared documents hashes nothing and is `null` (stale), like an empty one. A stored digest names its version (`v<N>:sha256:…`) and is recomputed under THAT version (`parseFingerprintVersion`, `KNOWN_FINGERPRINT_VERSIONS`), never the current constant, so a legacy v1/v2 report keeps its own semantics until it is re-fingerprinted, an upgrade alone stales nothing, and a version this build cannot recompute fails closed to `stale`. For a **v1/v2** stored digest, `allCurrentArtifactsCovered` additionally re-scans the LIVE phase directory (via `scanPhasePlans`, short-circuited so it only runs once the digest itself has matched, and fails closed to `false` on any scope other than `SCOPE.COMPLETE`) for every current `*-PLAN.md`/`*-SUMMARY.md` and requires each to be represented in `covered_files`: a plan or summary added to the phase AFTER verification, never declared, would otherwise pass the digest check untouched. Fingerprint **v3** (#5095, ADR-5057 Phase 2, the current default `FINGERPRINT_VERSION`) closes that input set instead of patching around it: (1) a report path (basename `VERIFICATION.md` or `*-VERIFICATION.md`) is NEVER an input to its own digest — filtered by `canonicalizeCoveredFiles`/`isVerificationReportPath` one function above `computeCoveredDigest`, since that function never receives the report's own path to compare against; (2) the hashed set is `canonicalize(declared ∪ phaseArtifactPaths(phaseDir))` — the phase's own live `*-PLAN.md`/`*-SUMMARY.md` (mapped to the root they actually live in) are UNIONED into the digest on both the emit (`cmdVerificationFingerprint`) and check (`readVerificationStatus`) sides, so `allCurrentArtifactsCovered` is not consulted for v3 — a plan/summary added after fingerprinting moves the digest itself; (3) containment additionally admits a `.planning`-spelled path whose realpath sits in one of the ANCHORED planning scopes `resolveContainmentRoots` enumerates from the project root alone (`.planning`, `.planning/<project>`, `.planning/workstreams/<ws>`, `.planning/<project>/workstreams/<ws>` — never derived from a caller's `phaseDir`, #5095 R7) — a symlinked `.planning/workstreams/<ws>/phases`, `.planning/<project>/phases`, or a whole `.planning/<project>`/`.planning/workstreams/<ws>` store maps to that SAME scope's spelling, never collapsing onto (or being dropped from) the top-level `.planning/phases/<phase>/…` shape a single scope root could only recognise; a scope whose realpath is the filesystem root or an ancestor of the checkout root is refused outright, never admitted; this containment widening applies to every version, never just v3. ANY mismatch — digest, an uncovered current artifact (v1/v2 only), or a covered path that is missing, unreadable, or escapes every known root (`resolveProjectRoot(phaseDir)` — the operator's validated `--project-dir` when one was given (#4894), otherwise `findProjectRoot(phaseDir)`; the fingerprint CLI resolves its root through the same call, so a digest is always recomputed under the root it was emitted under — canonicalized via real `fs`, never the injected seam — it is a trusted caller-derived anchor, not attacker-influenced covered-input data) — routes to `stale`, fail-closed (`computeCoveredDigest` returns `null` for the whole set rather than a partial digest). A report with no fingerprint metadata at all (every report predating #4155) falls back to the legacy `findStaleVerificationSummary`, which flags a SUMMARY newer than the VERIFICATION file — unchanged. The verifier computes `covered_digest` via the CLI (`verification.fingerprint <phaseDir> <file>...`, routed in `verification-command-router.cjs`; since #4623 the covered files are bare positionals or `--files a[,b]`, repeatable and mixable, the phase dir must be an existing directory — an omitted one used to hash the wrong set at exit 0 — and any other `--flag` is a usage error rather than a covered path), never by hand — this is deterministic math, not an LLM-estimated value. The legacy path alone keeps the module's original no-throw, degrade-to-safe contract (any FS error → `missing` / not-stale); the fingerprint path's contract is stricter (any FS error → `stale`), matching #4155's fail-closed design. `isPhaseComplete(phaseDir, deps?)` is the single canonical owner of "is phase P complete?" (ADR-3180 §7.4, issue #3186, disk-strict per #2957): it wraps `readVerificationStatus`, calling it UNCONDITIONALLY — plan count is never a precondition, so a zero-plan phase with a passing `*-VERIFICATION.md` is complete (#3168) — and returns `{ value: { complete, verification }, scope }`; `complete` is exactly `verification.status === 'passed'`. A ROADMAP checkbox carries no machine authority and is never consulted. `cmdPhaseComplete`, `buildPhaseCompletionProjection`, and `buildStateFrontmatter` all route through it. Source of truth: `gsd-core/bin/lib/verification.cjs` (generated from `src/verification.cts`).
4652

‎agents/gsd-code-reviewer.compact.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -84,12 +84,14 @@ files:
8484
```
8585
Present and non-empty → use directly, skip fallback below.
8686
87-
**Fallback (safety net only, when invoked directly without workflow context — `/gsd:code-review` always passes `files`):** if `files` absent/empty, compute DIFF_BASE from `diff_base` if provided; otherwise **fail closed**: "Cannot determine review scope. Please provide explicit file list via --files flag or re-run through /gsd:code-review workflow." Do NOT invent a heuristic (e.g. HEAD~5) — silent mis-scoping is worse than failing loudly.
87+
**Fallback (safety net only, when invoked directly without workflow context — `/gsd:code-review` always passes `files`):** if `files` absent/empty, ask the evaluation-scope resolver (#5164) for the phase named by `phase_dir`; otherwise **fail closed**: "Cannot determine review scope. Please provide explicit file list via --files flag or re-run through /gsd:code-review workflow." Do NOT invent a heuristic (e.g. HEAD~5) or a `base..HEAD` range — silent mis-scoping is worse than failing loudly.
8888

89-
If DIFF_BASE set:
89+
Resolver call (phase number = the leading digits of the `phase_dir` basename; add `--since "$diff_base"` when `diff_base` is provided):
9090
```bash
91-
git diff --name-only ${DIFF_BASE}..HEAD -- . ':!.planning/' ':!ROADMAP.md' ':!STATE.md' ':!*-SUMMARY.md' ':!*-VERIFICATION.md' ':!*-PLAN.md' ':!package-lock.json' ':!yarn.lock' ':!Gemfile.lock' ':!poetry.lock'
91+
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; _gsd_id_ok() { case "$("$1" runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') return 0;; *) return 1;; esac; }; _gsd_homes() { _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif _gsd_homes; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; [ -n "$_G" ] && _gsd_id_ok "$_G"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and no identity-proving gsd_run is on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; _gsd_id_ok gsd_run && GSD_IDENTITY_STATUS=ok; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
92+
gsd_run check evaluation-scope --phase "<phase number>" --raw
9293
```
94+
Use its `files`. A `status` of `unresolvable`, or empty `files`, is the fail-closed case above; `degraded` is usable but say so in REVIEW.md.
9395

9496
**4. Parse structural findings when present:** `<structural_findings>...</structural_findings>` → parse JSON, cache as `STRUCTURAL_FINDINGS`. Include in `## Structural Findings (fallow)` section of REVIEW.md during `write_review` (verbatim if small; concise summary if large). Optional block — absence means no structural pre-pass.
9597

0 commit comments

Comments
 (0)