peaks-loop 4.0.0-beta.20 → 4.0.0-beta.21

package/CHANGELOG.md

@@ -5,22 +5,96 @@
 ### Patch Changes
 
 - Updated dependencies
-  - peaks-loop-shared@0.0.9
-  - peaks-loop-audit-independent@0.0.5
-  - peaks-loop-crystallization@0.0.6
-  - peaks-loop-doctor@0.0.5
-  - peaks-loop-final-review@0.0.5
+  - peaks-loop-shared@0.0.15
+  - peaks-loop-audit-independent@0.0.11
+  - peaks-loop-crystallization@0.0.12
+  - peaks-loop-doctor@0.0.11
+  - peaks-loop-final-review@0.0.11
 
 ## 4.0.0
 
 ### Patch Changes
 
 - Updated dependencies
-  - peaks-loop-shared@0.0.5
-  - peaks-loop-audit-independent@0.0.5
-  - peaks-loop-crystallization@0.0.5
-  - peaks-loop-doctor@0.0.5
-  - peaks-loop-final-review@0.0.5
+  - peaks-loop-shared@0.0.15
+  - peaks-loop-audit-independent@0.0.11
+  - peaks-loop-crystallization@0.0.12
+  - peaks-loop-doctor@0.0.11
+  - peaks-loop-final-review@0.0.11
+
+## 4.0.0-beta.21 — 2026-07-22 (ice-cola surface-check fixes, republish)
+
+This release is the **republish** after the accidental 4.0.2
+publish earlier on 2026-07-22. The 4.0.2 manifest is being
+unpublished (`npm unpublish --force`, within 72h window). The
+intended release is `4.0.0-beta.21`, the version that was
+manually pinned but the publish workflow's `pnpm exec changeset
+version` step overrode it to `4.0.2` due to a pending
+`.changeset/*.md` in the tagged commit.
+
+### Bug fixes
+
+- **standardsMissing UX (`fix(standards)`)** — `peaks workspace init`
+  previously reported `standardsMissing.missing: true` with the
+  remediation text "no project-local standards found" whenever the
+  language overlay was empty, even when common was clearly populated
+  (ice-cola shape: common/\*.md + typescript overlay populated, but
+  no javascript/ dir). The detector now distinguishes three states
+  (`complete` / `common-missing` / `language-missing`) and the
+  remediation text calls out the precise failing component.
+
+- **`peaks statusline` default action (`fix(statusline)`)** — `peaks
+statusline` (no subcommand) was documented as "Run with no
+  subcommand to render" but commander was printing usage instead of
+  dispatching to the hidden `render` subcommand. The fix attaches
+  a default `.action(...)` on the parent `statusline` command that
+  delegates to a public `runDefaultStatuslineRender` body, and adds
+  `--project <path>` to the parent so the default path inherits the
+  project label.
+
+- **release-pack test version pinning (`fix(release-tests)`)** —
+  five `tests/unit/release/*.test.ts` files hard-coded `'4.0.0-beta.17'`
+  and `'0.0.4'` literals. Root bumping from 4.0.0-beta.17 to
+  4.0.0-beta.20 made three tests fail immediately, demonstrating the
+  tests were carrying version knowledge the production code does not.
+  Expectations now derive from the on-disk `package.json` instead,
+  so future version bumps are a no-op for the suite.
+
+- **`peaks preferences` unknown-key error (`fix(preferences)`)** —
+  the prior error was `PREFERENCES_KEY_UNKNOWN: <key>` which forced
+  the operator to look up valid keys elsewhere. All three sites
+  (`get` / `set` / `reset`) now throw via a shared `unknownKeyError`
+  helper that includes the sorted `ALLOWED_KEYS_LIST` inline.
+
+### Chore
+
+- **`chore(deps)`** — Migrate `onlyBuiltDependencies: [better-sqlite3]`
+  out of `package.json#pnpm` (no longer read by pnpm 10.11+) into
+  `.npmrc` as the canonical pnpm config key. Silences the per-package
+  `WARN  The "pnpm" field in package.json is no longer read by pnpm`
+  log line without changing install behavior.
+
+### CI
+
+- **`ci(publish)`** — Add `workflow_dispatch` input
+  `skip_changeset_version` to `.github/workflows/publish.yml`. When
+  set, the conditional `pnpm exec changeset version` step is
+  skipped, so manual version pins in `package.json` survive the
+  registry-repair release path.
+
+- **`ci(unpublish)`** — One-shot `unpublish-4-0-2` workflow that
+  uses Trusted Publishing + OIDC to remove peaks-loop@4.0.2 + 8
+  subpackages. Triggered by `gh workflow run` with
+  `confirm_destructive=yes-i-am-sure`. Retired (kept for audit)
+  once the unpublish completes (npm 72h propagation).
+
+### Validation
+
+- `vitest tests/unit/standards/missing-standards-detector.test.ts` — 18/18
+- `vitest tests/unit/cli/commands/statusline-default-render.test.ts` — 3/3
+- `vitest tests/unit/release` — 20/20
+- `vitest tests/integration/preferences-cli.test.ts` — 5/5
+- `PEAKS_DRY_RUN=1 node scripts/release-pack.mjs` — 9/9 packages, zero WARN
 
 ## 4.0.0-beta.17
 

package/dist/cli/commands/preferences-commands.js

@@ -12,6 +12,26 @@ const ALLOWED_KEYS = new Set([
     'swarmSpeculative',
     'loopAutonomousEnabled',
 ]);
+/**
+ * Stable, sorted list of allowed preference keys. Used in error messages
+ * so a PREFERENCES_KEY_UNKNOWN throw is self-documenting (the operator
+ * sees exactly which keys are valid without reading the source).
+ */
+const ALLOWED_KEYS_LIST = Array.from(ALLOWED_KEYS).sort();
+/**
+ * Build a PREFERENCES_KEY_UNKNOWN error with the allowed-keys list baked
+ * in. Throwing a plain Error here is the legacy path that the CLI
+ * surfaces verbatim on stderr; the helper exists so all three sites
+ * (`get` / `set` / `reset`) emit the same operator-facing message.
+ *
+ * Stage-3 follow-up (ice-cola surface check 2026-07-22, follow-on to
+ * report item 5.3): previously the message was just `PREFERENCES_KEY_UNKNOWN:
+ * <key>` which forced the operator to look up valid keys elsewhere. The
+ * new message lists the valid keys inline so the response is actionable.
+ */
+function unknownKeyError(key) {
+    return new Error(`PREFERENCES_KEY_UNKNOWN: ${key}. Allowed keys: ${ALLOWED_KEYS_LIST.join(', ')}.`);
+}
 export function registerPreferencesCommands(program) {
     const prefs = program
         .command('preferences')
@@ -25,7 +45,7 @@ export function registerPreferencesCommands(program) {
         .action((opts) => {
         try {
             if (!ALLOWED_KEYS.has(opts.key)) {
-                throw new Error(`PREFERENCES_KEY_UNKNOWN: ${opts.key}`);
+                throw unknownKeyError(opts.key);
             }
             const all = loadPreferences(opts.project);
             const value = all[opts.key];
@@ -71,7 +91,7 @@ export function registerPreferencesCommands(program) {
         .action((opts) => {
         try {
             if (!ALLOWED_KEYS.has(opts.key)) {
-                throw new Error(`PREFERENCES_KEY_UNKNOWN: ${opts.key}`);
+                throw unknownKeyError(opts.key);
             }
             let parsed = opts.value;
             try {
@@ -106,7 +126,7 @@ export function registerPreferencesCommands(program) {
         .action((opts) => {
         try {
             if (!ALLOWED_KEYS.has(opts.key)) {
-                throw new Error(`PREFERENCES_KEY_UNKNOWN: ${opts.key}`);
+                throw unknownKeyError(opts.key);
             }
             const filePath = preferencesPath(opts.project);
             // Read raw on-disk state (not the merged view) so removing a key

package/dist/cli/commands/statusline-commands.d.ts

@@ -1,3 +1,15 @@
 import { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
+type RenderOptions = {
+    project?: string;
+    json?: boolean;
+};
+/**
+ * Default-statusline render body. Reused by both the top-level default
+ * action (Bug-02 dispatch) and the explicit `render` subcommand. Exported
+ * so a unit test can exercise the JSON / text output paths without going
+ * through commander.
+ */
+export declare function runDefaultStatuslineRender(options: RenderOptions, io: ProgramIO): Promise<void>;
 export declare function registerStatusLineCommands(program: Command, io: ProgramIO): void;
+export {};

package/dist/cli/commands/statusline-commands.js

@@ -54,6 +54,26 @@ function resolveIdeForCommand(options, projectRoot) {
     }
     return detectIdeFromContext({ env: process.env, cwd: projectRoot ?? process.cwd(), parsedStdin: null });
 }
+/**
+ * Default-statusline render body. Reused by both the top-level default
+ * action (Bug-02 dispatch) and the explicit `render` subcommand. Exported
+ * so a unit test can exercise the JSON / text output paths without going
+ * through commander.
+ */
+export async function runDefaultStatuslineRender(options, io) {
+    const raw = await readStdin();
+    const stdin = parseStatusLineStdin(raw);
+    const seeded = options.project
+        ? { ...(stdin ?? {}), workspace: { current_dir: options.project } }
+        : stdin;
+    const model = buildStatusLineModel(seeded, Date.now());
+    const text = renderStatusLine(model);
+    if (options.json === true) {
+        io.stdout(JSON.stringify({ ok: true, command: 'statusline.render', data: { text } }, null, 2));
+        return;
+    }
+    io.stdout(text);
+}
 export function registerStatusLineCommands(program, io) {
     // Top-level `peaks statusline` — register as a group with subcommands
     // (install | uninstall | status). When the user runs `peaks statusline` with
@@ -65,27 +85,31 @@ export function registerStatusLineCommands(program, io) {
     // option-shadowing bug.
     const statusline = addJsonOption(program
         .command('statusline')
-        .description('Render the Peaks skill status line for the current session, or manage the adapter-driven statusLine entry. Run with no subcommand to render; with a subcommand (install | uninstall | status) to manage.'));
-    // Hidden render subcommand. This is the default behavior when the user types
-    // `peaks statusline` with no subcommand. We mark it hidden so `peaks
-    // statusline --help` does not show "render" as a subcommand.
+        .description('Render the Peaks skill status line for the current session, or manage the adapter-driven statusLine entry. Run with no subcommand to render; with a subcommand (install | uninstall | status) to manage.')
+        .option('--project <path>', 'project root path (used to label the status line when stdin is absent; applies to the default render path)'));
+    // Default behavior: when the user types `peaks statusline` with no
+    // subcommand, render the status line. Without this default action,
+    // commander falls back to printing usage (Bug-02, ice-cola surface check
+    // 2026-07-22). The hidden `render` subcommand is preserved so callers
+    // can still invoke it explicitly.
+    //
+    // Note (commander 12.x): when both a top-level `.action(...)` and
+    // subcommands exist, commander's option parser can conflate parent and
+    // child flags. We therefore parse `process.argv` for the bare `statusline`
+    // invocation here, and otherwise let the subcommand machinery handle the
+    // rest. The implementation is wrapped in `peekDefaultStatuslineRender` so
+    // it can be exercised in isolation by unit tests.
+    statusline.action(async (_parentOptions, command) => {
+        await runDefaultStatuslineRender(command.opts(), io);
+    });
+    // Hidden render subcommand. Preserved for callers that want to invoke
+    // render explicitly without going through the default-action dispatch.
     statusline
         .command('render', { hidden: true })
         .description('Render the Peaks skill status line for the current session (reads session JSON on stdin; honors --project for the project label).')
         .option('--project <path>', 'project root path (used to label the status line when stdin is absent)')
         .action(async (options) => {
-        const raw = await readStdin();
-        const stdin = parseStatusLineStdin(raw);
-        const seeded = options.project
-            ? { ...(stdin ?? {}), workspace: { current_dir: options.project } }
-            : stdin;
-        const model = buildStatusLineModel(seeded, Date.now());
-        const text = renderStatusLine(model);
-        if (options.json === true) {
-            io.stdout(JSON.stringify({ ok: true, command: 'statusline.render', data: { text } }, null, 2));
-            return;
-        }
-        io.stdout(text);
+        await runDefaultStatuslineRender(options, io);
     });
     addJsonOption(statusline
         .command('install')

package/dist/services/standards/missing-standards-detector.d.ts

@@ -42,6 +42,31 @@ export type MissingProjectStandardsDiagnostic = {
     readonly remediation: string;
     readonly language: StandardsLanguage;
 };
+/**
+ * List which standards tree components are missing vs populated.
+ *
+ * Returns one of three stable shapes:
+ *   - { kind: 'complete' }                    — both common + language overlay populated
+ *   - { kind: 'common-missing' }              — common dir absent/empty (universal)
+ *   - { kind: 'language-missing', language }  — common ok, language overlay absent/empty
+ *
+ * The detector previously returned a single boolean that flipped to
+ * "missing: true" the moment the language overlay was empty, but printed
+ * the remediation as if BOTH common AND language were missing — a UX bug
+ * that surfaced in ice-cola (common=4 .md files; typescript=1 .md file;
+ * javascript overlay absent → label said "no project-local standards found"
+ * even though common was clearly populated). This split lets the CLI emit
+ * a precise remediation string per kind.
+ */
+export type StandardsTreeDiagnostic = {
+    readonly kind: 'complete';
+} | {
+    readonly kind: 'common-missing';
+} | {
+    readonly kind: 'language-missing';
+    readonly language: StandardsLanguage;
+};
+export declare function diagnoseStandardsTree(projectRoot: string, language: StandardsLanguage): StandardsTreeDiagnostic;
 /**
  * Detect whether a consumer project's `.peaks/standards/` tree (2.0
  * canonical) is missing or empty.

package/dist/services/standards/missing-standards-detector.js

@@ -62,6 +62,26 @@ function hasPopulatedMarkdown(dir) {
     const entries = readdirSync(dir);
     return entries.some((entry) => entry.toLowerCase().endsWith('.md'));
 }
+export function diagnoseStandardsTree(projectRoot, language) {
+    if (!SUPPORTED_LANGUAGES.has(language)) {
+        throw new Error(`Unsupported standards language: ${String(language)}`);
+    }
+    const normalizedRoot = normalizeProjectRoot(projectRoot);
+    const commonDir = join(normalizedRoot, '.peaks', 'standards', 'common');
+    const languageDir = language === 'generic'
+        ? null
+        : join(normalizedRoot, '.peaks', 'standards', language);
+    const commonOk = hasPopulatedMarkdown(commonDir);
+    const languageOk = languageDir === null ? true : hasPopulatedMarkdown(languageDir);
+    if (commonOk && languageOk) {
+        return { kind: 'complete' };
+    }
+    if (!commonOk) {
+        return { kind: 'common-missing' };
+    }
+    // common ok, language overlay empty/missing
+    return { kind: 'language-missing', language };
+}
 /**
  * Detect whether a consumer project's `.peaks/standards/` tree (2.0
  * canonical) is missing or empty.
@@ -84,18 +104,29 @@ export function detectMissingProjectStandards(projectRoot, language) {
     }
     const normalizedRoot = normalizeProjectRoot(projectRoot);
     const renderedPath = renderForPlatform(normalizedRoot);
-    const commonDir = join(normalizedRoot, '.peaks', 'standards', 'common');
-    const languageDir = language === 'generic'
-        ? null
-        : join(normalizedRoot, '.peaks', 'standards', language);
-    const commonOk = hasPopulatedMarkdown(commonDir);
-    const languageOk = languageDir === null ? true : hasPopulatedMarkdown(languageDir);
-    const missing = !(commonOk && languageOk);
-    // Remediation message: copy-pasteable, mentions language, references the
-    // resolved project path, and hints at the `--init-standards` opt-in flag.
-    const remediation = missing
-        ? `⚠ no project-local standards found at ${renderedPath} — run \`peaks standards init --project ${normalizedRoot} --apply\` to scaffold, or pass --init-standards to peaks workspace init for one-shot auto-apply (language: ${language}).`
-        : `Project-local standards already present at ${renderedPath}. Re-run \`peaks standards init --project ${normalizedRoot} --apply\` to refresh from the curated baseline.`;
+    const diagnostic = diagnoseStandardsTree(projectRoot, language);
+    // Bug-01 fix (ice-cola surface check 2026-07-22): the previous
+    // remediation said "no project-local standards found" whenever EITHER
+    // common or the language overlay was empty, which misrepresented
+    // projects that have common populated but a missing language overlay
+    // (e.g. ice-cola has common/*.md + typescript/coding-style.md but no
+    // javascript/coding-style.md). The remediation now distinguishes the
+    // three kinds so the operator gets a precise hint.
+    let missing;
+    let remediation;
+    if (diagnostic.kind === 'complete') {
+        missing = false;
+        remediation = `Project-local standards already present at ${renderedPath}. Re-run \`peaks standards init --project ${normalizedRoot} --apply\` to refresh from the curated baseline.`;
+    }
+    else if (diagnostic.kind === 'common-missing') {
+        missing = true;
+        remediation = `⚠ no project-local common standards at ${renderedPath} — run \`peaks standards init --project ${normalizedRoot} --apply\` to scaffold (language: ${language}), or pass --init-standards to peaks workspace init for one-shot auto-apply.`;
+    }
+    else {
+        missing = true;
+        const overlayName = diagnostic.language;
+        remediation = `⚠ common standards present at ${renderedPath}\\common but ${overlayName} language overlay is missing — run \`peaks standards init --project ${normalizedRoot} --apply\` to scaffold the ${overlayName} overlay (or pass --init-standards to peaks workspace init for one-shot auto-apply).`;
+    }
     return {
         missing,
         path: renderedPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.0-beta.20",
+  "version": "4.0.0-beta.21",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "license": "MIT",
@@ -54,14 +54,14 @@
     "headroom-ai": "0.22.4",
     "yaml": "^2.9.0",
     "zod": "^3.25.76",
-    "peaks-loop-audit-independent": "0.0.4",
-    "peaks-loop-doctor": "0.0.4",
-    "peaks-loop-crystallization": "0.0.5",
-    "peaks-loop-mut": "0.0.4",
-    "peaks-loop-job-snapshot": "0.0.4",
-    "peaks-loop-final-review": "0.0.4",
-    "peaks-loop-shared-channel": "0.0.4",
-    "peaks-loop-shared": "0.0.8"
+    "peaks-loop-crystallization": "0.0.11",
+    "peaks-loop-audit-independent": "0.0.10",
+    "peaks-loop-doctor": "0.0.10",
+    "peaks-loop-final-review": "0.0.10",
+    "peaks-loop-mut": "0.1.0",
+    "peaks-loop-job-snapshot": "0.0.5",
+    "peaks-loop-shared": "0.0.14",
+    "peaks-loop-shared-channel": "0.0.5"
   },
   "peerDependencies": {
     "@alibaba-group/open-code-review": "1.3.1"