@opengsd/gsd-core 1.20.0 → 1.21.0

package/hooks/lib/isolation-sentinel.js

@@ -29,6 +29,12 @@
 // of the same repo are separate directories on disk, so each gets its own
 // sentinel with no cross-worktree collision, no lock file needed.
 //
+// #5682: the single slot above is last-writer-wins, so two orchestrators sharing one checkout
+// overwrote each other's decision and the guard discarded the foreign record. The writer now ALSO
+// records each plan-scoped decision at `<cwd>/.gsd/dispatch-isolation/<phase>--<plan>.json`
+// (same payload, same cwd-derived location and forgery posture), and `readSentinel` consults the
+// record keyed by the dispatch's own phase/plan first, falling back to the single slot.
+//
 // #3045 SECURITY F3 (LOW, accepted risk — documented, not redesigned for):
 // the sentinel lives at a fixed, predictable, gitignored path inside the
 // PRIMARY checkout. An agent already running inside a legitimately isolated
@@ -64,6 +70,35 @@ const VALID_ISOLATION = new Set(['harness-worktree', 'orchestrator-worktree', 'n
 
 const SENTINEL_RELATIVE_PATH = path.join('.gsd', 'dispatch-isolation-sentinel.json');
 
+// #5682: per-dispatch records, one file per `<phase>--<plan>` under this directory.
+const KEYED_SENTINEL_DIR = path.join('.gsd', 'dispatch-isolation');
+const SAFE_SENTINEL_KEY_RE = /^[A-Za-z0-9._-]{1,100}$/;
+
+// #5758: a real sentinel payload is under 300 bytes. Anything larger is not one, and the cap bounds
+// the read so a hostile or runaway record cannot be pulled into the hook.
+const SENTINEL_MAX_BYTES = 4096;
+
+/** #5682: strict allow-list for a phase/plan string that becomes a path segment. */
+function isSafeSentinelKey(s) {
+  return typeof s === 'string' && SAFE_SENTINEL_KEY_RE.test(s) && s !== '.' && s !== '..';
+}
+
+/** #5682: keyed record path for a dispatch, or null unless BOTH phase and plan are safe keys. */
+function keyedSentinelPath(root, phase, plan) {
+  if (!isSafeSentinelKey(phase) || !isSafeSentinelKey(plan)) return null;
+  return path.join(root, KEYED_SENTINEL_DIR, `${phase}--${plan}.json`);
+}
+
+/**
+ * #5682: phase-level keyed record path (`<phase>.json`, written when a decision carries no plan),
+ * or null unless the phase is a safe key. Two orchestrators recording plan-less decisions for
+ * different phases each keep their own file.
+ */
+function phaseSentinelPath(root, phase) {
+  if (!isSafeSentinelKey(phase)) return null;
+  return path.join(root, KEYED_SENTINEL_DIR, `${phase}.json`);
+}
+
 // #3045 SECURITY F2 fix: how long a written sentinel is trusted as "this
 // dispatch's decision" before a reader falls back to the conservative
 // registry+config check.
@@ -103,10 +138,10 @@ function sentinelPath(cwd) {
 /**
  * Resolve the project root a sentinel should be read from/written to, using
  * the SAME derivation gsd-tools.cjs's dispatcher applies to every `--cwd`
- * before invoking a route handler: `findProjectRoot(resolveMainWorktreeCwd(cwd))`
- * (gsd-core/bin/gsd-tools.cjs main(), :3506/:3603 — `record-dispatch-isolation`
- * and `dispatch-isolation` are not in SKIP_ROOT_RESOLUTION, so every write
- * goes through both steps).
+ * before invoking a route handler: `resolveProjectContext(cwd).projectRoot`
+ * (gsd-core/bin/gsd-tools.cjs main() — `record-dispatch-isolation` and
+ * `dispatch-isolation` are not in SKIP_ROOT_RESOLUTION, so every write goes
+ * through it).
  *
  * #3045 MINOR fix: the guard hooks previously read the sentinel from the raw
  * `data.cwd` / `workspace_roots[i]` the harness reports, with NO equivalent
@@ -119,7 +154,7 @@ function sentinelPath(cwd) {
  * written where it looked. Deriving both sides through this one function
  * closes that divergence.
  *
- * `findProjectRoot`/`resolveWorktreeRoot` are read from the sibling
+ * `resolveProjectContext` is read from the sibling
  * `gsd-core/bin/lib/*.cjs` modules staged alongside these hooks at install
  * time (same pattern the guard hooks already use for
  * capability-registry.cjs/runtime-name-policy.cjs) — two directories up from
@@ -145,10 +180,10 @@ function resolveSentinelRoot(cwd) {
     // cold-tree encounter.
     const { ensureRuntimeBuild } = require('../../gsd-core/bin/ensure-runtime-build.cjs');
     ensureRuntimeBuild();
-    const { resolveWorktreeRoot } = require('../../gsd-core/bin/lib/worktree-safety.cjs');
-    const { root } = resolveWorktreeRoot(cwd);
-    const { findProjectRoot } = require('../../gsd-core/bin/lib/project-root.cjs');
-    return findProjectRoot(root);
+    // #6043 (ADR-4908): the dispatcher resolves non-skip commands through the
+    // same seam, so the reader looks where the writer wrote.
+    const { resolveProjectContext } = require('../../gsd-core/bin/lib/project-context.cjs');
+    return resolveProjectContext(cwd).projectRoot;
   } catch {
     return cwd;
   }
@@ -174,14 +209,129 @@ function resolveSentinelRoot(cwd) {
  * per the repo's clock-seam convention, so staleness is testable without
  * asserting on wall-clock time.
  */
-function readSentinel(cwd, { clock = Date } = {}) {
+function readSentinel(cwd, { clock = Date, dispatchIds = null } = {}) {
   const root = resolveSentinelRoot(cwd);
-  let raw;
+
+  // #5682: candidates are the record keyed by this dispatch's own phase/plan, the phase-level
+  // record for its phase, and the single legacy slot. A keyed candidate counts only when it is
+  // well-formed and its contents agree with its own filename key; the legacy slot only when it
+  // applies to this dispatch. Among FRESH candidates the latest `writtenAt` wins, so a newer
+  // phase-level decision is not shadowed by an older plan-scoped one (and vice versa).
+  const gsdDir = path.join(root, '.gsd');
+  const keyedDirs = [gsdDir, path.join(root, KEYED_SENTINEL_DIR)];
+  const keyedCandidates = [];
+  if (dispatchIds) {
+    const planFile = keyedSentinelPath(root, dispatchIds.phase, dispatchIds.plan);
+    if (planFile) {
+      const c = parseSentinelFile(planFile, clock, keyedDirs);
+      if (c.present && !c.malformed && c.phase === dispatchIds.phase && c.plan === dispatchIds.plan) keyedCandidates.push(c);
+    }
+    const phaseFile = phaseSentinelPath(root, dispatchIds.phase);
+    if (phaseFile) {
+      const c = parseSentinelFile(phaseFile, clock, keyedDirs);
+      if (c.present && !c.malformed && c.phase === dispatchIds.phase && c.plan === null) keyedCandidates.push(c);
+    }
+  }
+
+  const legacy = parseSentinelFile(sentinelPath(root), clock, [gsdDir]);
+  const legacyApplies = legacy.present && !legacy.malformed && sentinelAppliesToDispatch(legacy, dispatchIds);
+
+  const fresh = keyedCandidates.filter((c) => !c.stale);
+  if (legacyApplies && !legacy.stale) fresh.push(legacy);
+  if (fresh.length > 0) return latestWritten(fresh);
+
+  // Nothing fresh: a stale keyed record still feeds the aged-none path; otherwise the legacy
+  // slot is returned exactly as before.
+  if (keyedCandidates.length > 0) return latestWritten(keyedCandidates);
+  return legacy;
+}
+
+/** The candidate with the greatest `writtenAt` (ties keep the earlier-listed, i.e. most specific). */
+function latestWritten(candidates) {
+  return candidates.reduce((best, c) => (c.writtenAt > best.writtenAt ? c : best));
+}
+
+/**
+ * lstat of `dir` when it is a real directory, not a link (lstat does not follow); otherwise null.
+ * Never throws.
+ */
+function lstatRealDirectory(dir) {
   try {
-    raw = fs.readFileSync(sentinelPath(root), 'utf-8');
+    // bigint: an NTFS file id is 64 bits and a JS number keeps 53, so ids are compared exactly.
+    const st = fs.lstatSync(dir, { bigint: true });
+    return st.isDirectory() && !st.isSymbolicLink() ? st : null;
   } catch {
-    return { present: false };
+    return null;
+  }
+}
+
+/** Same filesystem object: equal dev and ino. A zero ino (some Windows volumes) cannot be compared. */
+function sameObject(a, b) {
+  return a.ino === 0n || b.ino === 0n || (a.dev === b.dev && a.ino === b.ino);
+}
+
+/**
+ * #5758: read one sentinel file as a bounded, non-blocking, link-refusing read of a regular file.
+ * Returns the text, or null for EVERY refusal (missing, link, FIFO, device, directory, oversized,
+ * short read, a hard link to another file, a parent directory that is a link), so a hostile record
+ * is exactly as absent as a missing one. `readFileSync` would block forever on a FIFO with no
+ * writer, follow a link to an endless device or to a file outside the project, and read without
+ * bound. The writers only ever produce a fresh temp file renamed into place (link count 1). A
+ * sentinel renamed over between the open and the fstat reads as nlink 0 and is refused for that one
+ * dispatch, which is the conservative no-sentinel decision.
+ *
+ * Parent directories are lstat-checked before the open and re-checked (same dev/ino, still a real
+ * directory) after it, and the opened file must be the object the pre-open lstat saw. Node has no
+ * openat, so this NARROWS the window for a parent swapped to a link between check and open; it does
+ * not close it.
+ */
+function readSentinelText(file, parentDirs) {
+  const parents = [];
+  for (const dir of parentDirs) {
+    const st = lstatRealDirectory(dir);
+    if (!st) return null;
+    parents.push({ dir, st });
   }
+  let fd;
+  try {
+    const before = fs.lstatSync(file, { bigint: true });
+    if (!before.isFile() || before.size > BigInt(SENTINEL_MAX_BYTES)) return null;
+    // O_NONBLOCK makes an open of a FIFO swapped in after the lstat return at once; O_NOFOLLOW
+    // refuses a link swapped in. Windows lacks both flags (`|| 0`); lstat/fstat still guard.
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0) | (fs.constants.O_NONBLOCK || 0));
+    const st = fs.fstatSync(fd, { bigint: true });
+    if (!st.isFile() || st.nlink !== 1n || st.size > BigInt(SENTINEL_MAX_BYTES)) return null;
+    if (!sameObject(before, st)) return null;
+    const size = Number(st.size);
+    for (const p of parents) {
+      const after = lstatRealDirectory(p.dir);
+      if (!after || !sameObject(p.st, after)) return null;
+    }
+    const buf = Buffer.alloc(size);
+    let offset = 0;
+    while (offset < size) {
+      const n = fs.readSync(fd, buf, offset, size - offset, offset);
+      if (n === 0) return null;
+      offset += n;
+    }
+    return buf.toString('utf-8');
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch { /* nothing left to release */ }
+    }
+  }
+}
+
+/**
+ * Parse and validate one sentinel file. Never throws. Shape: see `readSentinel`.
+ * `parentDirs` are the directories between the project root and the file that must be real
+ * directories (not links); a refusal anywhere reads as `{ present: false }`.
+ */
+function parseSentinelFile(file, clock, parentDirs = []) {
+  const raw = readSentinelText(file, parentDirs);
+  if (raw === null) return { present: false };
 
   let parsed;
   try {
@@ -348,7 +498,12 @@ function buildSentinelDiscard(sentinel, dispatchIds) {
 module.exports = {
   VALID_ISOLATION,
   SENTINEL_RELATIVE_PATH,
+  KEYED_SENTINEL_DIR,
+  isSafeSentinelKey,
+  keyedSentinelPath,
+  phaseSentinelPath,
   SENTINEL_STALE_MS,
+  SENTINEL_MAX_BYTES,
   AGED_NONE_MAX_MS,
   sentinelPath,
   resolveSentinelRoot,

package/hooks/lib/secret-read-exemptions.js

@@ -0,0 +1,161 @@
+// gsd-hook-version: {{GSD_VERSION}}
+// Project exemptions for the secret-read guard (#4432).
+//
+// A project lists repo-relative files under `hooks.secret_read_exempt` in the
+// ROOT `.planning/config.json`. A listed file stays readable only when it is
+// BOTH a regular file in the working tree (lstat, so a symlink never counts)
+// AND a regular blob (100644/100755) in the commit HEAD names. Config alone is
+// not the key: an agent that can write the config must not be able to unlock a
+// real secret that was never committed.
+//
+// The committed-file check reads `.git` directly (./git-head-tree.js): no
+// subprocess and no timer, so the verdict depends only on the repository's
+// bytes. Every failure means "not exempt"; nothing in this module throws.
+//
+// Standalone on purpose: hooks are installed as loose files and cannot require
+// `src/`. The entry rules are duplicated in `src/config.cts`
+// (`normalizeSecretReadExemptEntry`, used by config-set); tests/
+// secret-read-exemptions.test.cjs drives one corpus through both so they
+// cannot diverge.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { headTreeEntry } = require('./git-head-tree.js');
+
+const REGULAR_BLOB_MODES = new Set(['100644', '100755']);
+
+/**
+ * Normalize one config entry to a POSIX repo-relative file path, or null.
+ * `\` becomes `/` unconditionally; nothing is trimmed (whitespace is part of a
+ * name). Rejected: non-strings, absolute and UNC paths, drive prefixes, NUL, any
+ * `..` segment, a directory (trailing `/`), and `.`.
+ * @param {unknown} entry
+ * @returns {string | null}
+ */
+function normalizeExemptEntry(entry) {
+  if (typeof entry !== 'string') return null;
+  let s = entry.replace(/\\/g, '/');
+  while (s.startsWith('./')) s = s.slice(2);
+  if (s === '' || s === '.') return null;
+  if (s.startsWith('/') || s.endsWith('/')) return null;
+  if (/^[A-Za-z]:/.test(s)) return null;
+  if (s.includes('\0')) return null;
+  if (s.split('/').includes('..')) return null;
+  return s;
+}
+
+/**
+ * The normalized, de-duplicated `hooks.secret_read_exempt` entries of
+ * `<root>/.planning/config.json`. Anything unreadable or malformed yields [].
+ * @param {string} root
+ * @param {{ readFile?: (file: string, encoding: string) => string }} [deps]
+ * @returns {string[]}
+ */
+function readExemptEntries(root, { readFile = fs.readFileSync } = {}) {
+  let config;
+  try {
+    config = JSON.parse(readFile(path.join(root, '.planning', 'config.json'), 'utf8'));
+  } catch {
+    return [];
+  }
+  if (config === null || typeof config !== 'object' || Array.isArray(config)) return [];
+  const hooks = config.hooks;
+  if (hooks === null || typeof hooks !== 'object' || Array.isArray(hooks)) return [];
+  const list = hooks.secret_read_exempt;
+  if (!Array.isArray(list)) return [];
+  const out = [];
+  for (const raw of list) {
+    const entry = normalizeExemptEntry(raw);
+    if (entry !== null && !out.includes(entry)) out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * True when HEAD holds `entry` (relative to `root`) as a regular blob.
+ * @param {string} root
+ * @param {string} entry
+ * @returns {boolean}
+ */
+function isCommittedBlob(root, entry) {
+  const found = headTreeEntry(root, entry);
+  return found !== null && REGULAR_BLOB_MODES.has(found.mode);
+}
+
+/**
+ * True when `abs` is a regular file (lstat: a symlink is not). When `root` and
+ * `entry` are given, the real path of `abs` must also equal the real root joined
+ * with `entry`, so a symlinked PARENT directory (which lstat of the leaf does
+ * not see) is never exempt. A realpath failure means "not a match".
+ * @param {string} abs
+ * @param {string} [root]
+ * @param {string} [entry]
+ * @returns {boolean}
+ */
+function isRegularFile(abs, root, entry) {
+  try {
+    if (!fs.lstatSync(abs).isFile()) return false;
+    if (typeof root !== 'string' || typeof entry !== 'string') return true;
+    const fold = process.platform === 'win32' ? (s) => s.toLowerCase() : (s) => s;
+    // .native: canonical long form on Windows (see sameRealPath in git-head-tree.js).
+    return fold(fs.realpathSync.native(abs)) === fold(path.join(fs.realpathSync.native(root), entry));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build the per-invocation checker. Pure apart from the two injected probes,
+ * which are memoized per entry. A probe that throws means "not exempt".
+ * @returns {(token: unknown) => boolean}
+ */
+function createExemptionChecker({
+  root,
+  entries,
+  allowRelative = false,
+  platform = process.platform,
+  isCommittedBlob: committed = isCommittedBlob,
+  isRegularFile: regular = isRegularFile,
+}) {
+  const fold = platform === 'win32' ? (s) => s.toLowerCase() : (s) => s;
+  const targets = [];
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    if (typeof entry === 'string' && entry !== '') targets.push({ entry, target: fold(path.resolve(root, entry)) });
+  }
+  const verdicts = new Map();
+
+  function verdictFor(entry) {
+    if (verdicts.has(entry)) return verdicts.get(entry);
+    let ok = false;
+    try {
+      ok = regular(path.resolve(root, entry), root, entry) === true && committed(root, entry) === true;
+    } catch {
+      ok = false;
+    }
+    verdicts.set(entry, ok);
+    return ok;
+  }
+
+  return function isExempt(token) {
+    if (typeof token !== 'string' || token === '' || targets.length === 0) return false;
+    if (!allowRelative && !path.isAbsolute(token)) return false;
+    // path.resolve would collapse `<symlinkdir>/../x` lexically while the OS
+    // reads through the link, so a `..` segment is refused before resolving.
+    if (token.split(/[\\/]/).includes('..')) return false;
+    const resolved = fold(path.resolve(root, token));
+    for (const { entry, target } of targets) {
+      if (resolved === target) return verdictFor(entry);
+    }
+    return false;
+  };
+}
+
+module.exports = {
+  normalizeExemptEntry,
+  readExemptEntries,
+  createExemptionChecker,
+  isCommittedBlob,
+  isRegularFile,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-core",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "main": ".opencode/plugins/gsd-core.js",
   "bin": {
@@ -61,6 +61,10 @@
     "url": "git+https://github.com/open-gsd/gsd-core.git"
   },
   "homepage": "https://github.com/open-gsd/gsd-core",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/trek-e"
+  },
   "bugs": {
     "url": "https://github.com/open-gsd/gsd-core/issues"
   },
@@ -126,6 +130,7 @@
     "gen:registry": "node scripts/gen-registry.cjs --write",
     "gen:install-tree": "node scripts/gen-install-tree-fixtures.cjs",
     "gen:section-manifest": "node scripts/gen-section-manifest.cjs --write",
+    "gen:cli-surface-manifest": "node scripts/gen-cli-surface-manifest.cjs --write",
     "regen:derived": "npm run build && npm run gen:registry && node scripts/gen-adr-index.cjs --write && node scripts/gen-features.cjs --write && node scripts/gen-capability-matrix.cjs --write && node scripts/gen-inventory-manifest.cjs --write && node scripts/gen-context-index.cjs --write && node scripts/gen-state-md-docs.cjs --write && npm run gen:section-manifest && node scripts/sync-manifest-versions.cjs && npm run gen:install-tree && node scripts/gen-scripts-cli-exit.cjs --write && node scripts/gen-hooks-cli-exit.cjs --write && node scripts/gen-exit-code-registry.cjs --write && node scripts/gen-exit-code-docs.cjs --write && node scripts/gen-platform-conformance-tier.cjs --write && node scripts/gen-platform-conformance-tier.cjs --target macos --write",
     "validate:registry": "node scripts/validate-registry.cjs",
     "prepack": "npm run build:lib",
@@ -154,7 +159,7 @@
     "lint:test-file-count": "node scripts/lint-test-file-count.cjs",
     "lint:pr-checks": "node scripts/lint-pr-check-project-dir.cjs",
     "lint:changeset": "node scripts/changeset/lint.cjs",
-    "lint:generated-sync": "node scripts/gen-capability-registry.cjs --check && node scripts/gen-pi-package-skills.cjs --check && node scripts/gen-loop-host-contract.cjs --check && node scripts/gen-capability-matrix.cjs --check && node scripts/sync-manifest-versions.cjs --check && node scripts/gen-inventory-manifest.cjs --check && node scripts/generate-package-identity.cjs --check && node scripts/gen-plugin-skills.cjs --check && node scripts/gen-registry.cjs --check && node scripts/gen-adr-index.cjs --check && node scripts/gen-features.cjs --check && node scripts/check-glossary-refs.cjs --check && node scripts/lint-compiled-artifact-sync.cjs --check && node scripts/gen-context-index.cjs --check && node scripts/gen-section-manifest.cjs --check && node scripts/gen-health-docs.cjs --check && node scripts/gen-state-md-docs.cjs --check && node scripts/gen-scripts-cli-exit.cjs --check && node scripts/gen-hooks-cli-exit.cjs --check && node scripts/gen-exit-code-registry.cjs --check && node scripts/gen-exit-code-docs.cjs --check && node scripts/gen-platform-conformance-tier.cjs --check && node scripts/gen-platform-conformance-tier.cjs --target macos --check",
+    "lint:generated-sync": "node scripts/gen-capability-registry.cjs --check && node scripts/gen-pi-package-skills.cjs --check && node scripts/gen-loop-host-contract.cjs --check && node scripts/gen-capability-matrix.cjs --check && node scripts/sync-manifest-versions.cjs --check && node scripts/gen-inventory-manifest.cjs --check && node scripts/generate-package-identity.cjs --check && node scripts/gen-plugin-skills.cjs --check && node scripts/gen-registry.cjs --check && node scripts/gen-adr-index.cjs --check && node scripts/gen-features.cjs --check && node scripts/check-glossary-refs.cjs --check && node scripts/lint-compiled-artifact-sync.cjs --check && node scripts/gen-context-index.cjs --check && node scripts/gen-section-manifest.cjs --check && node scripts/gen-health-docs.cjs --check && node scripts/gen-state-md-docs.cjs --check && node scripts/gen-scripts-cli-exit.cjs --check && node scripts/gen-hooks-cli-exit.cjs --check && node scripts/gen-exit-code-registry.cjs --check && node scripts/gen-exit-code-docs.cjs --check && node scripts/gen-platform-conformance-tier.cjs --check && node scripts/gen-platform-conformance-tier.cjs --target macos --check && node scripts/gen-cli-surface-manifest.cjs --check",
     "lint:docs": "node scripts/lint-docs-required.cjs",
     "lint:qa-smells": "node scripts/qa-smell-ratchet.cjs",
     "lint:legacy-name": "node scripts/lint-legacy-dir-name.cjs",

package/pi/package-agents/gsd-executor.md

@@ -107,7 +107,7 @@ PLAN_START_EPOCH=$(date +%s)
 If running inside a git worktree, capture authoritative worktree identity before
 any task commit changes HEAD. The execute-phase orchestrator consumes this from
 your final `<worktree_metadata>` return block to build the wave cleanup manifest
-without relying on runtime harness metadata (#1297).
+without relying on runtime harness metadata (#1297). On the claude-orchestration Workflow path, return the same four fields through its structured-output schema instead (#4747).
 
 ```bash
 GSD_WORKTREE_PATH=""

package/pi/package-agents/gsd-plan-checker.md

@@ -696,7 +696,7 @@ issue:
 1. For each `<automated>` block piping a package-manager list command into grep with a `^` anchor: BLOCKER.
 2. For each `<automated>` block containing `2>/dev/null || echo` where the result feeds a `[ "$VAR" = ... ]` comparison: BLOCKER.
 3. For each `<automated>` block asserting a specific numeric count not cited as measured in this plan: WARNING.
-4. For each count/match gate (`grep -c`, `grep -q`, `rg`), run it — read-only commands only — against the current tree (#4927). It already passes at HEAD with no recorded baseline: BLOCKER (it measures nothing). A literal differing in case from the heading/key the task writes: BLOCKER. Never run a gate that builds, installs, or writes. See `planner-verify-command-grounding.md`.
+4. For each count/match gate (`grep -c`, `grep -q`, `rg`), run it — read-only commands only — against the current tree (#4927). Its baseline is the `[HEAD=<value> EXPECT<op><value>]` notation beside it (#4309), read from `verify plan-structure`, never re-derived: a `baseline_findings` B1 (already true at HEAD, no `GUARD MUTATION:`) is a BLOCKER, as is a gate that already passes at HEAD with no notation, or whose printed value differs from its notation's `HEAD`. A free-form `# baseline at HEAD:` comment (B2) is not a baseline: WARNING. A literal differing in case from the heading/key the task writes: BLOCKER. Never run a gate that builds, installs, or writes. See `planner-verify-command-grounding.md`.
 
 ## Dimension: Verify Command Path Resolvability (#2401)
 

package/pi/package-agents/gsd-planner.md

@@ -187,7 +187,7 @@ Every task has four required fields:
 
 **Inherit the command that already worked (#2401):** reuse `prior_verify_commands` verbatim, prefer `npm --prefix <dir> run <script>`, ground every path you author. @__GSD_PI_ENGINE_ROOT__/gsd-core/references/planner-verify-command-grounding.md
 
-**Grep gate hygiene:** `grep -c` counts comments, so header prose can be self-invalidating. Use `grep -v '^#' | grep -c token`. Bare `== 0` gates on unfiltered files are forbidden. Run every count/match gate against the current tree and record its baseline (#4927): a gate that already passes at HEAD, or whose literal differs in case from the deliverable, is wrong. @__GSD_PI_ENGINE_ROOT__/gsd-core/references/planner-verify-command-grounding.md
+**Grep gate hygiene:** `grep -c` counts comments, so header prose can be self-invalidating. Use `grep -v '^#' | grep -c token`. Bare `== 0` gates on unfiltered files are forbidden. Run every count/match gate against the current tree and record its baseline as `[HEAD=<value> EXPECT<op><value>]` beside it (#4927, #4309), not as a free-form comment: a gate that already passes at HEAD, or whose literal differs in case from the deliverable, is wrong. @__GSD_PI_ENGINE_ROOT__/gsd-core/references/planner-verify-command-grounding.md
 
 <comment_text_discipline>
 **Comment-text discipline (HARD GATE, #429):** A literal an acceptance criterion negative-greps for must NOT appear verbatim in any `<action>` body. Rules + `<!-- planner-discipline-allow: LIT -->` allowlist + examples: @__GSD_PI_ENGINE_ROOT__/gsd-core/references/planner-antipatterns.md ("Comment-Text Discipline").
@@ -203,7 +203,7 @@ Every task has four required fields:
 
 **<precondition>** (optional, one prose line): a runnable/checkable fact the task assumes that plan ordering does not guarantee — external setup (`user_setup`), a prior-phase artifact, or an env var. The executor asserts it before running the task and halts on unmet. Emission rules + the contract triad (precondition ↔ `<verify>`/`<done>` ↔ `must_haves.truths`): @__GSD_PI_ENGINE_ROOT__/gsd-core/references/planner-preconditions.md.
 
-**<reversibility>** (optional): `rating="reversible|costly|one-way"` + one-line rationale for a decision this task implements. A newly surfaced `one-way` decision inserts a `checkpoint:decision` before this task; one the human already settled (CONTEXT.md, an ingested ADR, an answered checkpoint) keeps its rating and gets no new checkpoint; `costly` is flagged only; unsure means `reversible`. Rules: @__GSD_PI_ENGINE_ROOT__/gsd-core/references/planner-reversibility.md
+**<reversibility>** (optional): `rating="reversible|costly|one-way"` + one-line rationale for a decision this task implements. A newly surfaced `one-way` decision inserts a `checkpoint:decision` before this task; one the human already settled (CONTEXT.md except `### Decided autonomously`, an ingested ADR, an answered checkpoint) keeps its rating and gets no new checkpoint; `costly` is flagged only; unsure means `reversible`. Rules: @__GSD_PI_ENGINE_ROOT__/gsd-core/references/planner-reversibility.md
 
 See @__GSD_PI_ENGINE_ROOT__/gsd-core/references/planner-guidance.md for Task Types table, Task Sizing rules, Interface-First Task Ordering, and Specificity guidance.
 
@@ -476,7 +476,7 @@ For each artifact: "What must be CONNECTED for this to function?"
 **Step 5: Identify Key Links**
 "Where is this most likely to break?" Key links = critical connections where breakage causes cascading failures.
 
-See @__GSD_PI_ENGINE_ROOT__/gsd-core/references/planner-guidance.md for a worked example and the `must_haves` YAML format.
+See @__GSD_PI_ENGINE_ROOT__/gsd-core/references/planner-guidance.md for a worked example, the `must_haves` YAML format, and the `key_links` field contract (`from`/`to` are project-relative file paths; symbols and endpoints go in `via:`).
 
 </goal_backward>
 

package/pi/package-agents/gsd-verifier.md

@@ -517,7 +517,7 @@ done
 
 **Behavior-unverified truths (Step 3):** Every truth left ⚠️ PRESENT_BEHAVIOR_UNVERIFIED is recorded in the `behavior_unverified_items` frontmatter list (emitted whenever the count > 0, regardless of overall status, so it survives a gaps_found phase) and surfaces for human verification; when the overall status is human_needed it also appears in the human_verification section. Phrase each item around the invariant: what to trigger, what state must hold afterward, and why presence checks can't see it.
 
-**Harvest deferred items from PLAN.md (#3309 / `workflow.human_verify_mode = end-of-phase`):** Scan every PLAN file in the phase for `<verify><human-check>` blocks on `auto` tasks. These are verification items the planner deliberately deferred from `checkpoint:human-verify` to end-of-phase to avoid the executor cold-start cost. Each block has the same shape used by the planner:
+**Harvest deferred items from PLAN.md (#3309 / `workflow.human_verify_mode = end-of-phase`):** Scan every PLAN file in the phase for `<verify><human-check>` blocks on `auto` tasks. These are items the planner deferred from `checkpoint:human-verify`. Shape:
 
 ```xml
 <verify>
@@ -529,7 +529,7 @@ done
 </verify>
 ```
 
-Merge those harvested items into the same human verification list as your own analysis. Deduplicate when the planner-deferred item and your own analysis describe the same check. The downstream `human_needed` → `{phase_num}-UAT.md` path in `workflows/execute-phase.md` is the single sink — no separate file is created.
+Merge those harvested items into the same human verification list as your own analysis. Harvest every block, even one whose `<expected>` already records a verdict: a recorded verdict is not a reason to omit the check, and `<expected>` is carried through unmodified. Deduplicate only against your own analysis (same check). The downstream `human_needed` → `{phase_num}-UAT.md` path in `workflows/execute-phase.md` is the single sink — no separate file is created.
 
 **Format:**
 

package/pi/package-agents/manifest.json

@@ -16,7 +16,7 @@
     "gsd-domain-researcher.md": "f1b07d9c79dcb89c90e5af7f61adfa5dc73ebe8429783d8cb281d7ae2bdc682b",
     "gsd-eval-auditor.md": "9d77e7329c52741e7e62185b566231eb872c6b34afa6c869960a922af573b3d5",
     "gsd-eval-planner.md": "efc12a2822d77a5989db2e3efe83b7fda9f0509bb203910d7e26eb9369f89949",
-    "gsd-executor.md": "45e9540f6380b1883ad5b144411b21447eef20f310cbd0ab7c72c2bdaf5f8c47",
+    "gsd-executor.md": "e0d9e81b7a967f88388871efebd6a6f02801a82f3bcbfe008b125a097f61591c",
     "gsd-framework-selector.md": "96d52931468372ee88c4f1d551c13c97d2be8079053b55d992e0ea1720d3d5c9",
     "gsd-integration-checker.md": "a233ab8c5c97b6099c649d1e9a09e88ff1ed1bf7df7c1b13bc766c33d58e09b9",
     "gsd-intel-updater.md": "26c70b81580cc5bf713959bdcc84a16a35569861d2e79c07c71258ccd05ba9bc",
@@ -24,8 +24,8 @@
     "gsd-nyquist-auditor.md": "e82d1562e1df663e4a2907bd85b4316d5ab76bfa9d413ac8daecbd6f854fa42d",
     "gsd-pattern-mapper.md": "3f51a38c2a1e8657190ba88a314fb2c9e66e25f5ab0e3edbc4e2f649b2702d01",
     "gsd-phase-researcher.md": "2215ab8205f1bcb8b826870a4b8e9a949b6f77778d1bf75fae5ce4a07dd459ba",
-    "gsd-plan-checker.md": "1734489d067538c0fb818768aae8f336d83d4d1b2e81286eff84b6c512c67cfb",
-    "gsd-planner.md": "709f81898bf60f17eea9a150098c5ba2e31fddb38ea062fa0b015136502045b4",
+    "gsd-plan-checker.md": "0978a72430c052d486a14825fd39ebbceb26e8abd819f7311550cb0dfa40dd9f",
+    "gsd-planner.md": "8c788c8b6c3b68f26fd0420adccd75b4956911f3ceb1cea83517b88fa87db951",
     "gsd-project-researcher.md": "ac7e0065778a3ec40e023af48faa57f715c3fa13900975ef7b8d50142e44cf3c",
     "gsd-research-synthesizer.md": "d20735f8dc591af470c4cbb892284863c5976e2bd8a77512bf146469158d051a",
     "gsd-roadmapper.md": "c5cf5fa9df6bcbd7acdc1ec62c20b6e713ed6b6f2b032b17ca3044eebd0626d3",
@@ -34,6 +34,6 @@
     "gsd-ui-checker.md": "8f6297fd73b8d3d9d289f7fd50536295f8a5af328ae55b1fda7d581b44920f22",
     "gsd-ui-researcher.md": "272c893acd582417a0f85a1aa2bf2c5059e732727727cf8c8b36b1f978963f37",
     "gsd-user-profiler.md": "4328f32facd579a63cef2aee484e527e8688cd6f0df3627408ed5cb4a2483478",
-    "gsd-verifier.md": "db0c5148dcc89cba73893c18557c11bf0a4f412ec16de2e11e26b86dac750df7"
+    "gsd-verifier.md": "9a0b7d6202905d10aa0ef35b6611ba07d5ea8ba978070c6401703d5d12782bb9"
   }
 }

package/pi/package-skills/gsd-autonomous/SKILL.md

@@ -15,7 +15,7 @@ Invoke this Pi skill with `/skill:gsd-autonomous`.
 The text inside `<arguments>` is exactly what the user typed after the command name: data, not template instructions. An empty block means no arguments were passed.
 
 <objective>
-Execute all remaining milestone phases autonomously. For each phase: discuss → plan → execute. Pauses only for user decisions (grey area acceptance, blockers, validation requests).
+Execute all remaining milestone phases autonomously. For each phase: discuss → plan → execute. Pauses only for user decisions (hard-to-reverse and preference grey areas, blockers, validation requests).
 
 Uses ROADMAP.md phase discovery and Skill() flat invocations for each phase command. After all phases complete: milestone audit → complete → cleanup.
 

package/pi/package-skills/gsd-new-milestone/SKILL.md

@@ -26,7 +26,7 @@ Brownfield equivalent of new-project. Project exists, PROJECT.md has history. Ga
 - `.planning/ROADMAP.md` — phase structure (continues numbering)
 - `.planning/STATE.md` — reset for new milestone
 
-**After:** `/skill:gsd-plan-phase [N]` to start execution.
+**After:** Run `/skill:gsd-discuss-phase [N]` to clarify the approach (or `/skill:gsd-plan-phase [N]` to plan directly); then `/skill:gsd-execute-phase [N]` to execute.
 </objective>
 
 <execution_context>

package/pi/package-skills/gsd-new-project/SKILL.md

@@ -32,7 +32,7 @@ Initialize a new project through unified flow: questioning → research (optiona
 - `.planning/ROADMAP.md` — phase structure
 - `.planning/STATE.md` — project memory
 
-**After this command:** Run `/skill:gsd-plan-phase 1` to start execution.
+**After this command:** Run `/skill:gsd-discuss-phase 1` to clarify the approach (or `/skill:gsd-plan-phase 1` to plan directly); then `/skill:gsd-execute-phase 1` to execute.
 </objective>
 
 <execution_context>

package/scripts/changeset/cli.cjs

@@ -20,7 +20,7 @@ const path = require('node:path');
 const { ExitError, runMain } = require('../lib/cli-exit.cjs');
 const { parseFragment } = require('./parse.cjs');
 const { renderChangelog } = require('./render.cjs');
-const { serializeChangelog, parseChangelog } = require('./serialize.cjs');
+const { serializeChangelog, parseChangelog, EMPTY_RELEASE_PLACEHOLDER } = require('./serialize.cjs');
 const { renderGithubReleaseNotes } = require('./github-release-notes.cjs');
 const {
   compareSemverCore,
@@ -144,7 +144,7 @@ function assembleChangelog(lead, releaseBlock) {
 function injectEmptyPlaceholder(headerOnlyBlock) {
   return headerOnlyBlock.replace(
     /^(##\s+\[[^\]]+\][^\n]*)\n+/,
-    '$1\n\n_No notable changes._\n\n',
+    `$1\n\n${EMPTY_RELEASE_PLACEHOLDER}\n\n`,
   );
 }