@opengsd/gsd-core 1.7.0 → 1.8.0

package/hooks/dist/gsd-statusline.js

@@ -11,6 +11,7 @@ const os = require('os');
 const childProcess = require('child_process');
 const { isSemverNewer } = require('../gsd-core/bin/lib/semver-compare.cjs');
 const { PACKAGE_NAME, updateCacheFileName } = require('../gsd-core/bin/lib/package-identity.cjs');
+const { normalizeStateStatus } = require('../gsd-core/bin/lib/state-document.cjs');
 
 // --- Config + last-command readers ------------------------------------------
 
@@ -319,6 +320,78 @@ function contextTokenSuffix(currentUsage) {
   return total > 0 ? ` (${formatTokens(total)})` : '';
 }
 
+// --- Compact state format (opt-in) ---------------------------------------------
+
+/**
+ * Collapse GSD's free-text status (often a multi-sentence narrative) to a
+ * single keyword, built on the canonical normalizer (#2162 approval
+ * condition): normalizeStateStatus() in state-document.cjs owns the status
+ * vocabulary (discussing / planning / executing / verifying / completed /
+ * paused) so the two can't drift. "paused" — the canonical stuck state — is
+ * uppercased to PAUSED, the one state worth shouting about. Statuses the
+ * normalizer passes through unrecognized fall back to their first word,
+ * capped at 16 chars so a rogue STATE.md can't blow up the line.
+ * Returns null for empty input.
+ */
+const CANONICAL_STATUSES = ['discussing', 'planning', 'executing', 'verifying', 'completed', 'paused'];
+
+function shortGsdStatus(status) {
+  if (!status) return null;
+  const norm = normalizeStateStatus(status, null);
+  if (CANONICAL_STATUSES.includes(norm)) {
+    return norm === 'paused' ? 'PAUSED' : norm;
+  }
+  // Unrecognized free text passes through normalizeStateStatus verbatim —
+  // fall back to the first word, capped.
+  const first = String(norm).trim().split(/[\s\u2014\u2013-]+/)[0] || '';
+  return first ? first.slice(0, 16) : null;
+}
+
+/**
+ * Compact alternative to formatGsdState, selected via
+ * `statusline.state_format: "compact"`:
+ *
+ *   "v1.12 · P7/12 · executing"     (phase active)
+ *   "v2.0 · P4.5 · BLOCKED"         (no total known)
+ *   "v2.0 · complete"               (milestone done)
+ *   "v2.0 · next execute-phase 4.5" (idle with a queued action)
+ *
+ * Drops the milestone name and progress bar — the biggest width costs in the
+ * default format — and collapses narrative statuses via shortGsdStatus().
+ * The default "full" format is untouched.
+ */
+function formatGsdStateCompact(s) {
+  const parts = [];
+
+  if (s.milestone) parts.push(s.milestone);
+
+  const phaseId = s.activePhase || s.phaseNum;
+  if (phaseId) {
+    parts.push(s.phaseTotal ? `P${phaseId}/${s.phaseTotal}` : `P${phaseId}`);
+  }
+
+  // Scene exclusivity mirrors formatGsdState's if/else chain: an in-flight
+  // phase (Scene 1, gated on activePhase ONLY — the legacy phaseNum shape
+  // still completes) wins over milestone-complete (Scene 3), even if a
+  // non-atomic STATE.md edit leaves percent=100 alongside a lifecycle phase.
+  const done = !s.activePhase && (Number(s.percent) === 100 ||
+    (s.completedPhases && s.totalPhases && s.completedPhases === s.totalPhases));
+
+  if (done) {
+    parts.push('complete');
+  } else {
+    const st = shortGsdStatus(s.status);
+    if (st) {
+      parts.push(st);
+    } else if (!phaseId && s.nextAction) {
+      const phasesStr = (s.nextPhases && s.nextPhases.length > 0) ? s.nextPhases.join('/') : '';
+      parts.push(`next ${s.nextAction}${phasesStr ? ' ' + phasesStr : ''}`);
+    }
+  }
+
+  return parts.join(' \u00b7 ');
+}
+
 // --- Model name --------------------------------------------------------------
 
 /**
@@ -529,8 +602,9 @@ function runStatusline() {
       }
     }
 
-    // GSD state (milestone · status · phase) — shown when no todo task
-    const gsdStateStr = task ? '' : formatGsdState(readGsdState(dir) || {});
+    // GSD state (milestone · status · phase) — shown when no todo task.
+    // Format resolved below once config is read (statusline.state_format).
+    let gsdStateStr = '';
 
     // GSD update available?
     // Read only the per-package shared cache file (#607). The legacy
@@ -558,6 +632,7 @@ function runStatusline() {
     // Failure here must never break the statusline — wrap the entire lookup.
     let lastCmdSuffix = '';
     let position = 'end';
+    let stateFormat = 'full';
     let gitSuffix = '';
     try {
       if (getConfigValue(cfg, 'statusline.show_last_command') === true) {
@@ -569,6 +644,7 @@ function runStatusline() {
       }
       const cfgPos = getConfigValue(cfg, 'statusline.context_position');
       if (cfgPos != null) position = cfgPos;
+      if (getConfigValue(cfg, 'statusline.state_format') === 'compact') stateFormat = 'compact';
       if (getConfigValue(cfg, 'statusline.show_git') === true) {
         gitSuffix = buildGitSegment(parseGitStatus(readGitStatus(dir)));
       }
@@ -576,6 +652,11 @@ function runStatusline() {
       // Never break the statusline on config/transcript/git errors
     }
 
+    if (!task) {
+      const state = readGsdState(dir) || {};
+      gsdStateStr = stateFormat === 'compact' ? formatGsdStateCompact(state) : formatGsdState(state);
+    }
+
     // Output
     const dirname = path.basename(dir);
     const middle = task
@@ -675,6 +756,7 @@ module.exports = {
   evaluateUpdateCache,
   formatTokens,
   contextTokenSuffix,
+  shortGsdStatus, formatGsdStateCompact,
   compactModelName,
   readGitStatus, parseGitStatus, buildGitSegment,
 };
@@ -690,6 +772,7 @@ function renderStatusline(data) {
 
   let lastCmdSuffix = '';
   let position = 'end';
+  let stateFormat = 'full';
   let gitSuffix = '';
   try {
     const cfg = readGsdConfig(dir);
@@ -701,12 +784,14 @@ function renderStatusline(data) {
     }
     const cfgPos = getConfigValue(cfg, 'statusline.context_position');
     if (cfgPos != null) position = cfgPos;
+    if (getConfigValue(cfg, 'statusline.state_format') === 'compact') stateFormat = 'compact';
     if (getConfigValue(cfg, 'statusline.show_git') === true) {
       gitSuffix = buildGitSegment(parseGitStatus(readGitStatus(dir)));
     }
   } catch (e) { /* swallow */ }
 
-  const gsdStateStr = formatGsdState(readGsdState(dir) || {});
+  const state = readGsdState(dir) || {};
+  const gsdStateStr = stateFormat === 'compact' ? formatGsdStateCompact(state) : formatGsdState(state);
   const middle = gsdStateStr ? `\x1b[2m${gsdStateStr}\x1b[0m` : null;
   return composeStatusline({ model, ctx: '', middle, dirname, lastCmdSuffix, gitSuffix, position });
 }

package/hooks/gsd-context-monitor.js

@@ -180,15 +180,33 @@ process.stdin.on('end', () => {
           'starting new complex work.';
     }
 
-    const output = {
-      hookSpecificOutput: {
-        hookEventName: (data.hook_event_name && data.hook_event_name.trim())
-          || (process.env.GEMINI_API_KEY ? "AfterTool" : "PostToolUse"),
-        additionalContext: message
-      }
-    };
-
-    process.stdout.write(JSON.stringify(output));
+    // #2289: the hookSpecificOutput.additionalContext envelope is only a valid
+    // output shape for the context-injection events (PostToolUse, and AfterTool
+    // for the Gemini dialect). This hook is also wired to other lifecycle events
+    // on some hosts — Codex registers it under Stop / SubagentStart /
+    // SubagentStop / PreCompact (#772) — and those reject the envelope
+    // ("hook returned invalid stop hook JSON output"). Use a POSITIVE allowlist:
+    // emit only for injection-capable events; every other event, and a
+    // missing/unrecognized name, exits 0 with no stdout. A Stop-only blacklist is
+    // not enough — a missing name would still fall through to the injection path.
+    // All side effects above (debounce counter, one-time critical-session
+    // recording) have already run regardless of whether output is emitted.
+    const eventName = (data.hook_event_name && data.hook_event_name.trim()) || "";
+    // Preserve the pre-#2289 Gemini fallback: a missing event name under a
+    // Gemini-dialect runtime (GEMINI_API_KEY set) still means AfterTool, so its
+    // advisory output is unchanged. A missing name on any other host is silent.
+    const geminiFallback = eventName === "" && !!process.env.GEMINI_API_KEY;
+    const injectionSupported = eventName === "PostToolUse" || eventName === "AfterTool" || geminiFallback;
+
+    if (injectionSupported) {
+      const output = {
+        hookSpecificOutput: {
+          hookEventName: eventName || "AfterTool",
+          additionalContext: message
+        }
+      };
+      process.stdout.write(JSON.stringify(output));
+    }
   } catch (e) {
     // Silent fail -- never block tool execution
     process.exit(0);

package/hooks/gsd-statusline.js

@@ -11,6 +11,7 @@ const os = require('os');
 const childProcess = require('child_process');
 const { isSemverNewer } = require('../gsd-core/bin/lib/semver-compare.cjs');
 const { PACKAGE_NAME, updateCacheFileName } = require('../gsd-core/bin/lib/package-identity.cjs');
+const { normalizeStateStatus } = require('../gsd-core/bin/lib/state-document.cjs');
 
 // --- Config + last-command readers ------------------------------------------
 
@@ -319,6 +320,78 @@ function contextTokenSuffix(currentUsage) {
   return total > 0 ? ` (${formatTokens(total)})` : '';
 }
 
+// --- Compact state format (opt-in) ---------------------------------------------
+
+/**
+ * Collapse GSD's free-text status (often a multi-sentence narrative) to a
+ * single keyword, built on the canonical normalizer (#2162 approval
+ * condition): normalizeStateStatus() in state-document.cjs owns the status
+ * vocabulary (discussing / planning / executing / verifying / completed /
+ * paused) so the two can't drift. "paused" — the canonical stuck state — is
+ * uppercased to PAUSED, the one state worth shouting about. Statuses the
+ * normalizer passes through unrecognized fall back to their first word,
+ * capped at 16 chars so a rogue STATE.md can't blow up the line.
+ * Returns null for empty input.
+ */
+const CANONICAL_STATUSES = ['discussing', 'planning', 'executing', 'verifying', 'completed', 'paused'];
+
+function shortGsdStatus(status) {
+  if (!status) return null;
+  const norm = normalizeStateStatus(status, null);
+  if (CANONICAL_STATUSES.includes(norm)) {
+    return norm === 'paused' ? 'PAUSED' : norm;
+  }
+  // Unrecognized free text passes through normalizeStateStatus verbatim —
+  // fall back to the first word, capped.
+  const first = String(norm).trim().split(/[\s\u2014\u2013-]+/)[0] || '';
+  return first ? first.slice(0, 16) : null;
+}
+
+/**
+ * Compact alternative to formatGsdState, selected via
+ * `statusline.state_format: "compact"`:
+ *
+ *   "v1.12 · P7/12 · executing"     (phase active)
+ *   "v2.0 · P4.5 · BLOCKED"         (no total known)
+ *   "v2.0 · complete"               (milestone done)
+ *   "v2.0 · next execute-phase 4.5" (idle with a queued action)
+ *
+ * Drops the milestone name and progress bar — the biggest width costs in the
+ * default format — and collapses narrative statuses via shortGsdStatus().
+ * The default "full" format is untouched.
+ */
+function formatGsdStateCompact(s) {
+  const parts = [];
+
+  if (s.milestone) parts.push(s.milestone);
+
+  const phaseId = s.activePhase || s.phaseNum;
+  if (phaseId) {
+    parts.push(s.phaseTotal ? `P${phaseId}/${s.phaseTotal}` : `P${phaseId}`);
+  }
+
+  // Scene exclusivity mirrors formatGsdState's if/else chain: an in-flight
+  // phase (Scene 1, gated on activePhase ONLY — the legacy phaseNum shape
+  // still completes) wins over milestone-complete (Scene 3), even if a
+  // non-atomic STATE.md edit leaves percent=100 alongside a lifecycle phase.
+  const done = !s.activePhase && (Number(s.percent) === 100 ||
+    (s.completedPhases && s.totalPhases && s.completedPhases === s.totalPhases));
+
+  if (done) {
+    parts.push('complete');
+  } else {
+    const st = shortGsdStatus(s.status);
+    if (st) {
+      parts.push(st);
+    } else if (!phaseId && s.nextAction) {
+      const phasesStr = (s.nextPhases && s.nextPhases.length > 0) ? s.nextPhases.join('/') : '';
+      parts.push(`next ${s.nextAction}${phasesStr ? ' ' + phasesStr : ''}`);
+    }
+  }
+
+  return parts.join(' \u00b7 ');
+}
+
 // --- Model name --------------------------------------------------------------
 
 /**
@@ -529,8 +602,9 @@ function runStatusline() {
       }
     }
 
-    // GSD state (milestone · status · phase) — shown when no todo task
-    const gsdStateStr = task ? '' : formatGsdState(readGsdState(dir) || {});
+    // GSD state (milestone · status · phase) — shown when no todo task.
+    // Format resolved below once config is read (statusline.state_format).
+    let gsdStateStr = '';
 
     // GSD update available?
     // Read only the per-package shared cache file (#607). The legacy
@@ -558,6 +632,7 @@ function runStatusline() {
     // Failure here must never break the statusline — wrap the entire lookup.
     let lastCmdSuffix = '';
     let position = 'end';
+    let stateFormat = 'full';
     let gitSuffix = '';
     try {
       if (getConfigValue(cfg, 'statusline.show_last_command') === true) {
@@ -569,6 +644,7 @@ function runStatusline() {
       }
       const cfgPos = getConfigValue(cfg, 'statusline.context_position');
       if (cfgPos != null) position = cfgPos;
+      if (getConfigValue(cfg, 'statusline.state_format') === 'compact') stateFormat = 'compact';
       if (getConfigValue(cfg, 'statusline.show_git') === true) {
         gitSuffix = buildGitSegment(parseGitStatus(readGitStatus(dir)));
       }
@@ -576,6 +652,11 @@ function runStatusline() {
       // Never break the statusline on config/transcript/git errors
     }
 
+    if (!task) {
+      const state = readGsdState(dir) || {};
+      gsdStateStr = stateFormat === 'compact' ? formatGsdStateCompact(state) : formatGsdState(state);
+    }
+
     // Output
     const dirname = path.basename(dir);
     const middle = task
@@ -675,6 +756,7 @@ module.exports = {
   evaluateUpdateCache,
   formatTokens,
   contextTokenSuffix,
+  shortGsdStatus, formatGsdStateCompact,
   compactModelName,
   readGitStatus, parseGitStatus, buildGitSegment,
 };
@@ -690,6 +772,7 @@ function renderStatusline(data) {
 
   let lastCmdSuffix = '';
   let position = 'end';
+  let stateFormat = 'full';
   let gitSuffix = '';
   try {
     const cfg = readGsdConfig(dir);
@@ -701,12 +784,14 @@ function renderStatusline(data) {
     }
     const cfgPos = getConfigValue(cfg, 'statusline.context_position');
     if (cfgPos != null) position = cfgPos;
+    if (getConfigValue(cfg, 'statusline.state_format') === 'compact') stateFormat = 'compact';
     if (getConfigValue(cfg, 'statusline.show_git') === true) {
       gitSuffix = buildGitSegment(parseGitStatus(readGitStatus(dir)));
     }
   } catch (e) { /* swallow */ }
 
-  const gsdStateStr = formatGsdState(readGsdState(dir) || {});
+  const state = readGsdState(dir) || {};
+  const gsdStateStr = stateFormat === 'compact' ? formatGsdStateCompact(state) : formatGsdState(state);
   const middle = gsdStateStr ? `\x1b[2m${gsdStateStr}\x1b[0m` : null;
   return composeStatusline({ model, ctx: '', middle, dirname, lastCmdSuffix, gitSuffix, position });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-core",
-  "version": "1.7.0",
+  "version": "1.8.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": {
@@ -70,7 +70,9 @@
     "typescript-eslint": "^8.60.0"
   },
   "overrides": {
-    "qs": ">=6.15.2"
+    "qs": ">=6.15.2",
+    "body-parser": ">=2.3.0",
+    "@hono/node-server": ">=2.0.5"
   },
   "optionalDependencies": {
     "fallow": "^2.70.0"
@@ -101,7 +103,7 @@
     "lint": "eslint . --cache --cache-location node_modules/.cache/eslint/",
     "lint:fix": "eslint . --fix",
     "lint:table-schema-drift": "node scripts/lint-table-schema-drift.cjs",
-    "lint:ci": "npm run lint && npm run lint:skill-deps && npm run lint:generated-sync && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-allow-test-rule-refs.cjs && node scripts/lint-resolution-provenance.cjs && node scripts/validate-registry.cjs && node scripts/lint-table-schema-drift.cjs",
+    "lint:ci": "npm run lint && npm run lint:skill-deps && npm run lint:generated-sync && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-allow-test-rule-refs.cjs && node scripts/lint-resolution-provenance.cjs && node scripts/lint-portable-timeout.cjs && node scripts/validate-registry.cjs && node scripts/lint-table-schema-drift.cjs",
     "lint:allow-test-rule-refs": "node scripts/lint-allow-test-rule-refs.cjs",
     "lint:regression-names": "node scripts/lint-regression-test-names.cjs",
     "lint:descriptions": "node scripts/lint-descriptions.cjs",
@@ -109,7 +111,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-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",
+    "lint:generated-sync": "node scripts/gen-capability-registry.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/check-glossary-refs.cjs --check",
     "lint:docs": "node scripts/lint-docs-required.cjs",
     "lint:legacy-name": "node scripts/lint-legacy-dir-name.cjs",
     "ci:test-scope": "node scripts/ci-test-scope.cjs",

package/pi/gsd.cjs

@@ -9,8 +9,14 @@
  * This extension binds GSD's command surface to pi via the imperative adapter
  * path — the programmatic-CLI peer of the OpenCode worked binding.
  *
- * Installation: copy this file to ~/.pi/agent/extensions/gsd.cjs (pi loads
- * extensions via jiti from that dir). The engine is resolved from the installed
+ * Installation: copy this file to ~/.pi/agent/extensions/gsd.js — note the
+ * `.js` DEST suffix, not `.cjs`. pi auto-discovers extensions/ entries through
+ * `isExtensionFile()`, which accepts only `.ts`/`.js` and skips anything else
+ * SILENTLY (no error, no log line), so a `.cjs` dest installs fine and is then
+ * never loaded (#2470). This source file keeps its `.cjs` suffix on purpose —
+ * tests `require()` it directly and `.cjs` is unambiguous CommonJS — and pi
+ * loads the copied file via jiti, which handles CommonJS and ESM alike, so the
+ * suffix gates discovery, not parsing. The engine is resolved from the installed
  * GSD tree (walk-up like the OpenCode plugin). pi's shared hooks/ bundle
  * (hooks/*.js + hooks/lib/git-cmd.js) is installed alongside the extension —
  * capabilities/pi/capability.json does NOT set

package/scripts/changeset/lint.cjs

@@ -27,6 +27,7 @@ const OPT_OUT_LABEL = 'no-changelog';
 const USER_FACING_PREFIXES = [
   'bin/',
   'gsd-core/',
+  'src/',
   'agents/',
   'commands/',
   'hooks/',

package/scripts/changeset/parse.cjs

@@ -65,10 +65,23 @@ function extractDocsExempt(body) {
   // is CRLF-aware so Windows-authored fragments don't leave residual `\r`
   // characters that would shift the `(#NNNN)` PR suffix to a blank line in
   // the rendered CHANGELOG.md / GitHub release-notes bullet.
+  //
+  // Both leading AND trailing line terminators are stripped. `DOCS_EXEMPT_RE`
+  // removes the marker's own text but its `$` anchor (multiline mode) does
+  // not consume the `\n` that terminates the marker's line. When the marker
+  // is the FIRST line of the body, that leftover `\n` becomes the new first
+  // character of `body` — serializeChangelog then emits an empty `- ` bullet
+  // followed by an orphaned continuation paragraph, and parseChangelog's
+  // bullet-continuation check (which requires a leading `\s`) treats that
+  // non-indented paragraph as terminating the bullet, silently dropping the
+  // entry's content on re-parse. Stripping leading terminators here closes
+  // that gap the same way the trailing strip already does for the opposite
+  // (marker-last) position.
   const cleaned = body
     .replace(DOCS_EXEMPT_RE, '')
     .replace(/[ \t\r]+$/gm, '')             // strip trailing \r/spaces on each line
     .replace(/(?:\r?\n){3,}/g, '\n\n')      // collapse 3+ blank lines (CRLF-aware)
+    .replace(/^[\r\n]+/, '')                // strip terminators left by a first-line marker
     .replace(/[\r\n]+$/, '');               // strip every trailing line terminator
   return { docsExempt: reason, body: cleaned };
 }
@@ -105,6 +118,19 @@ function parseFragment(src) {
   if (body.endsWith('\r\n')) verbatimBody = body.slice(0, -2);
   else if (body.endsWith('\n')) verbatimBody = body.slice(0, -1);
   else verbatimBody = body;
+  // Some fragments have a blank line between the closing frontmatter `---`
+  // and the first line of actual content (purely a stylistic authoring
+  // choice — the blank line carries no significant content, unlike
+  // indentation inside a code block). Strip any such leading blank line(s)
+  // here, mirroring the trailing-terminator strip above. Without this,
+  // `body` starts with `\n`/`\r\n`, serializeChangelog emits an empty `- `
+  // bullet followed by an orphaned paragraph, and parseChangelog's
+  // continuation check (requires a leading `\s` on the line) treats that
+  // non-indented paragraph as terminating the bullet — silently dropping
+  // the fragment's content on re-parse. This is the same downstream failure
+  // mode as a first-line docs-exempt marker (see extractDocsExempt below);
+  // it just arises from plain authoring whitespace instead of a marker.
+  verbatimBody = verbatimBody.replace(/^(?:[ \t]*\r?\n)+/, '');
   const { docsExempt, body: visibleBody } = extractDocsExempt(verbatimBody);
   if (!visibleBody.trim()) return { ok: false, reason: FRAGMENT_ERROR.EMPTY_BODY };