murmur8 4.7.6 → 4.7.8

package/.blueprint/features/feature_display-version-number/FEATURE_SPEC.md

@@ -0,0 +1,159 @@
+---
+featureId: d480be2b-5d31-4a87-bbaa-2a564cd38c52
+---
+# Feature Specification — Display Version Number
+
+**Feature slug:** `display-version-number`
+**System Spec:** `.blueprint/system_specification/SYSTEM_SPEC.md`
+
+---
+
+## 1. Feature Intent
+
+**Why this feature exists.**
+
+- **Problem:** Users running `murmur8` have no way to quickly confirm which version of the package is installed. When filing bug reports or sharing configurations, they cannot state the version in use.
+- **User need:** Developers need a fast, standard CLI affordance (`--version` / `-V`) to retrieve the installed murmur8 version without reading `package.json` directly.
+- **System alignment:** murmur8 is distributed as an npm package (`murmur8`); version transparency is a baseline quality-of-life expectation for CLI tooling. This supports the system purpose of providing a dependable, professional workflow framework.
+
+---
+
+## 2. Scope
+
+### In Scope
+- A `--version` flag (and `-V` short alias) handled at the CLI entry point (`bin/cli.js`) that prints the version string from `package.json` and exits.
+- A `version` sub-command (`murmur8 version`) as an alias for discoverability, listed in `help`.
+- The version string format: plain semver with no decoration (e.g., `4.7.6`), printed to stdout, followed by a newline.
+- The `help` output updated to reference the version command/flag.
+
+### Out of Scope
+- Version checking against a remote registry (update notifications) — deferred.
+- Structured output formats (e.g., `--format=json`) — not needed for a version command.
+- Displaying versions of peer dependencies (Node.js, Claude Code) — not in scope.
+- Changelog or release notes output.
+
+---
+
+## 3. Actors Involved
+
+### Human User (Developer)
+- **Can do:** Run `murmur8 --version`, `murmur8 -V`, or `murmur8 version` to retrieve the installed version number.
+- **Cannot do:** Modify the version via this command; this is read-only.
+
+### CLI Entry Point (`bin/cli.js`)
+- **Can do:** Intercept `--version` / `-V` flags and the `version` sub-command before any other command routing, read `package.json` version, print it, and exit 0.
+- **Cannot do:** Spawn agents or modify queue state.
+
+---
+
+## 4. Behaviour Overview
+
+**What the feature does, conceptually.**
+
+- **Happy path — flag form:** User runs `murmur8 --version` or `murmur8 -V`. The CLI reads `version` from `package.json`, prints it to stdout (e.g., `4.7.6`), and exits with code 0.
+- **Happy path — command form:** User runs `murmur8 version`. Behaviour is identical to flag form.
+- **Help integration:** `murmur8 help` lists `version` and `--version` so the affordance is discoverable.
+- **No side effects:** Running the version command does not read queue state, start agents, or write any files.
+- **Exit behaviour:** Process exits immediately after printing; no banner, no decorative output beyond the version string.
+
+---
+
+## 5. State & Lifecycle Interactions
+
+This feature is **state-constraining** (does not create or transition pipeline state) and **read-only**.
+
+- No pipeline stages are entered.
+- No queue state is read or modified.
+- No `.claude/` files are touched.
+- The feature activates before command routing, so it cannot conflict with any pipeline state.
+
+---
+
+## 6. Rules & Decision Logic
+
+### Rule 1 — Flag intercept priority
+- **Description:** `--version` and `-V` are checked before alias resolution and before command routing.
+- **Inputs:** `process.argv`
+- **Output:** Prints semver string, exits 0.
+- **Deterministic:** Yes.
+
+### Rule 2 — Command routing
+- **Description:** If the first argument is `version` (after alias resolution), route to the version handler.
+- **Inputs:** `args[0] === 'version'`
+- **Output:** Prints semver string, exits 0.
+- **Deterministic:** Yes.
+
+### Rule 3 — Version source
+- **Description:** Version is read from `package.json` at the project root (same directory as `bin/cli.js`'s parent). This ensures the displayed version always matches the installed package — no hardcoded strings.
+- **Inputs:** `../package.json` relative to `bin/cli.js`
+- **Output:** `version` field value.
+- **Deterministic:** Yes.
+
+### Rule 4 — Output format
+- **Description:** Output is the bare semver string followed by a single newline. No prefix (e.g., no `murmur8 v4.7.6`), to support scripting and `grep`.
+- **Inferred interpretation:** Bare version (e.g., `4.7.6`) is preferred over prefixed (`v4.7.6`) for scripting compatibility. This is an explicit assumption — see §9.
+
+---
+
+## 7. Dependencies
+
+- `package.json` (root) — source of truth for the version string.
+- `bin/cli.js` — entry point where flag/command intercept is added.
+- `src/commands/help.js` — must be updated to document the new flag and command.
+- No external systems or network dependencies.
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Performance:** Must execute and exit in under 100 ms; reading `package.json` via `require()` (sync, cached) is sufficient.
+- **Reliability:** If `package.json` cannot be read, exit with a non-zero code and a descriptive error message. This is an edge case (malformed install) but must not silently fail.
+- **Security:** No user input is echoed; no risk of injection.
+- **Scripting compatibility:** Output must be machine-parseable (plain semver, no ANSI colour codes, no banner).
+
+---
+
+## 9. Assumptions & Open Questions
+
+### Assumptions
+- A1: The preferred output format is bare semver (e.g., `4.7.6`), not prefixed (e.g., `v4.7.6`), to maximise scripting compatibility. **If the team prefers a `v` prefix, this is easily changed.**
+- A2: `murmur8 version` (sub-command) is added as an alias for discoverability; this is consistent with tools like `node --version` / `node version`.
+- A3: No existing `version` command conflicts with this slug (confirmed: not present in `src/commands/`).
+- A4: The flag intercept should happen before `require()` of any command module, to avoid side effects on a simple version query.
+
+### Open Questions
+- OQ1: Should the version command also display the Node.js version (e.g., `murmur8 4.7.6 (node 20.x)`)? Deferred — not in scope for this iteration.
+- OQ2: Should a future `--check-update` flag compare against the npm registry? Deferred.
+
+---
+
+## 10. Impact on System Specification
+
+- **Reinforces:** The system spec notes CLI tooling (`init`, `update`, `queue`, etc.) as in scope. A `version` command is a standard CLI affordance that reinforces the professional quality of the tooling.
+- **No contradiction:** The system spec does not preclude this feature. It does not touch pipeline, queue, or agent concerns.
+- **No system spec change required.** This feature is a straightforward CLI quality-of-life addition within existing boundaries.
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Story themes:**
+1. As a developer, I want to run `murmur8 --version` so that I can confirm the installed version.
+2. As a developer, I want `murmur8 version` as an alternative sub-command so the version is discoverable from help.
+3. As a developer, I want the output to be machine-parseable so I can use it in scripts.
+
+**Expected story boundaries:**
+- One story per invocation path (`--version`/`-V` flag; `version` sub-command) is sufficient, or they can be collapsed into one if acceptance criteria covers both.
+- A story for help discoverability (the `help` output update) may be folded into the above or treated as a separate concern.
+
+**Areas needing careful story framing:**
+- The output format assumption (bare semver vs. `v`-prefixed) should be explicit in acceptance criteria so Nigel can write a deterministic assertion.
+- Error path (unreadable `package.json`) should be a separate AC, not a separate story.
+
+---
+
+## 12. Change Log (Feature-Level)
+
+| Date | Change | Reason | Raised By |
+|------|--------|--------|-----------|
+| 2026-06-01 | Initial feature specification | New feature | Alex |

package/.blueprint/features/feature_display-version-number/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,59 @@
+# Implementation Plan: display-version-number
+
+## Summary
+
+Add `--version` / `-V` flag interception and a `version` sub-command to the
+murmur8 CLI. Version is read from `package.json` resolved relative to
+`bin/cli.js` (not `cwd`) so the error path test (DVN-8) works correctly.
+Help output is updated to list the sub-command and both flags.
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/commands/version.js` | Create | Reads `package.json`, writes bare semver to stdout, handles error path |
+| `bin/cli.js` | Modify | Intercept `--version`/`-V` before command routing; add `version` alias |
+| `src/commands/help.js` | Modify | Add `version`, `--version`, and `-V` entries to help text |
+
+## Implementation Steps
+
+1. **Create `src/commands/version.js`**
+   - Accept `pkgRoot` option (defaults to `path.join(__dirname, '../../')`) so
+     the path is always resolved relative to `bin/cli.js` via `__dirname` logic.
+   - In `run()`: read `package.json` with `fs.readFileSync`; on success write
+     `version + '\n'` to stdout and exit 0; on error write a descriptive message
+     to stderr and exit 1 (no stdout output).
+   - Export `{ run, description }`.
+
+2. **Intercept `--version` and `-V` in `bin/cli.js`**
+   - Before the `if (!command || command === 'help' …)` block, add:
+     `if (command === '--version' || command === '-V') { require version cmd, run, return; }`
+   - Pass the resolved `pkgRoot` (`path.join(__dirname, '../package.json')`) so
+     `version.js` knows where to look.
+
+3. **Add `version` sub-command alias in `bin/cli.js`**
+   - Add `'version': 'version'` to the `aliases` map (or simply ensure
+     `src/commands/version.js` is found by the existing dynamic loader since the
+     file name matches the sub-command name — no alias entry needed).
+
+4. **Update `src/commands/help.js`**
+   - Add a `version` line to the Commands block (e.g. next to `help`):
+     `version               Print the installed murmur8 version`
+   - Add a flags section or inline note:
+     `--version, -V         Print version and exit`
+   - Both strings must appear literally in the output (DVN-9, DVN-10, DVN-11).
+
+5. **Verify test coverage incrementally**
+   - Steps 1–2 make DVN-1 through DVN-8 pass.
+   - Step 3 makes DVN-3 pass (version sub-command).
+   - Step 4 makes DVN-9, DVN-10, DVN-11 pass.
+
+## Risks / Questions
+
+- **DVN-8 destructive rename**: the test temporarily deletes `package.json`
+  from the project root. `version.js` must NOT cache `require('../package.json')`
+  at module load time — it must use `fs.readFileSync` inside `run()` so the
+  missing-file error is triggered at invocation, not at `require` time.
+- **`process.exit` in version.js**: calling `process.exit` directly is fine for
+  the CLI handler; ensure error branch uses exit code 1 and writes nothing to
+  stdout before exiting.

package/.blueprint/features/feature_display-version-number/handoff-alex.md

@@ -0,0 +1,20 @@
+## Handoff Summary
+**For:** Cass
+**Feature:** display-version-number
+
+### Key Decisions
+- Version is read from `package.json` at runtime (no hardcoded string) to guarantee accuracy
+- Output format is bare semver (e.g., `4.7.6`) with no prefix or decoration, for scripting compatibility — this is an explicit assumption (A1 in spec)
+- Both `--version`/`-V` flags and a `version` sub-command are in scope; flag intercept happens before command routing
+- `help` output must be updated to document the new flag and command
+- No remote registry check, no Node.js version display — deferred out of scope
+
+### Files Created
+- .blueprint/features/feature_display-version-number/FEATURE_SPEC.md
+
+### Open Questions
+- OQ1: Should output include a `v` prefix (e.g., `v4.7.6`) or remain bare (`4.7.6`)? Spec assumes bare; AC should encode whichever is decided
+- OQ2: Should error path (unreadable `package.json`) be covered by a separate story or an AC on the primary story?
+
+### Critical Context
+This is a small, read-only CLI affordance. The key behavioural detail that Cass must make explicit in stories is the **output format** (bare semver, no ANSI codes, single newline) because Nigel's tests will assert on exact stdout. The two invocation paths (`--version` flag vs. `version` sub-command) can be one story with two ACs or two stories — either works, but the flag intercept priority (before command routing) should be captured as an AC to ensure Codey implements it correctly.

package/.blueprint/features/feature_display-version-number/handoff-cass.md

@@ -0,0 +1,20 @@
+## Handoff Summary
+**For:** Nigel
+**Feature:** display-version-number
+
+### Key Decisions
+- Output is bare semver only (e.g., `4.7.6`) — no `v` prefix, no ANSI codes, single trailing newline; assert on exact stdout
+- All three invocations (`--version`, `-V`, `version` sub-command) must produce identical output
+- Flag intercept occurs before command routing — no queue state touched, no agents spawned
+- Version string is read from root `package.json` at runtime; test should verify it matches that file
+- Error path (unreadable `package.json`) exits non-zero with stderr message — no stdout version string
+
+### Files Created
+- .blueprint/features/feature_display-version-number/story-version-invocation.md
+- .blueprint/features/feature_display-version-number/story-version-help-discoverability.md
+
+### Open Questions
+- None
+
+### Critical Context
+AC assertions on stdout must be exact: bare semver string + newline, nothing else. The three invocation paths and the error path are the highest-priority test cases. Help discoverability story (AC1–AC2) only requires checking that `murmur8 help` stdout contains the strings `version` and `--version`/`-V`.

package/.blueprint/features/feature_display-version-number/handoff-nigel.md

@@ -0,0 +1,20 @@
+## Handoff Summary
+**For:** Codey
+**Feature:** display-version-number
+
+### Key Decisions
+- 11 tests (DVN-1–DVN-11) covering all story ACs across both stories
+- `--version`, `-V`, and `version` sub-command must produce identical output: bare semver + `\n`, no prefix, no ANSI
+- Version must be read from `package.json` at runtime (resolved relative to `bin/cli.js`, not `cwd`)
+- DVN-8 tests the error path by temporarily removing `package.json` — CLI must catch read errors, write to stderr, exit non-zero, emit no stdout
+- Help discoverability tests assert `murmur8 help` stdout contains `version`, `--version`, and `-V`
+
+### Files Created
+- test/artifacts/feature_display-version-number/test-spec.md
+- test/feature_display-version-number.test.js
+
+### Open Questions
+- None
+
+### Critical Context
+Implement version handling in `bin/cli.js` (flag intercept before command routing) and add a `src/commands/version.js` handler. Help output (`src/commands/help.js`) must list both `version` and `--version`/`-V`. The `package.json` must be resolved via `path.join(__dirname, '../package.json')` from `bin/cli.js` so DVN-8's rename-based error test works correctly.

package/.blueprint/features/feature_display-version-number/story-version-help-discoverability.md

@@ -0,0 +1,39 @@
+# Story: Version Help Discoverability
+
+**Feature:** display-version-number
+**Story slug:** version-help-discoverability
+
+---
+
+## User Story
+
+As a developer using murmur8,
+I want the `--version` flag and `version` command to appear in `murmur8 help` output
+so that I can discover how to check the installed version without consulting external documentation.
+
+---
+
+## Acceptance Criteria
+
+**AC1 — `help` output lists the `version` sub-command**
+- Given the murmur8 CLI is installed
+- When the user runs `murmur8 help` (or `murmur8 --help`)
+- Then stdout includes a reference to the `version` sub-command
+
+**AC2 — `help` output documents the `--version` flag**
+- Given the murmur8 CLI is installed
+- When the user runs `murmur8 help` (or `murmur8 --help`)
+- Then stdout includes a reference to the `--version` flag (and `-V` short alias)
+
+**AC3 — Help output is not affected by version invocations**
+- Given the murmur8 CLI is installed
+- When the user runs `murmur8 help` after previously running `murmur8 --version`
+- Then the help output is unchanged (no side effects from version invocation)
+
+---
+
+## Out of Scope
+
+- Displaying version output within the help text itself
+- Adding a dedicated `murmur8 help version` sub-help page
+- Any changes to help output unrelated to the version flag/command

package/.blueprint/features/feature_display-version-number/story-version-invocation.md

@@ -0,0 +1,70 @@
+# Story: Version Invocation
+
+**Feature:** display-version-number
+**Story slug:** version-invocation
+
+---
+
+## User Story
+
+As a developer using murmur8,
+I want to run `murmur8 --version`, `murmur8 -V`, or `murmur8 version`
+so that I can quickly confirm which version of the package is installed without reading `package.json` directly.
+
+---
+
+## Acceptance Criteria
+
+**AC1 — `--version` flag prints bare semver and exits**
+- Given the murmur8 CLI is installed
+- When the user runs `murmur8 --version`
+- Then stdout contains exactly the bare semver string (e.g., `4.7.6`) followed by a single newline, with no `v` prefix, no banner, and no ANSI colour codes
+- And the process exits with code 0
+
+**AC2 — `-V` short alias behaves identically to `--version`**
+- Given the murmur8 CLI is installed
+- When the user runs `murmur8 -V`
+- Then stdout is identical to the output of `murmur8 --version`
+- And the process exits with code 0
+
+**AC3 — `version` sub-command behaves identically to the flag form**
+- Given the murmur8 CLI is installed
+- When the user runs `murmur8 version`
+- Then stdout is identical to the output of `murmur8 --version`
+- And the process exits with code 0
+
+**AC4 — Flag intercept happens before command routing**
+- Given the murmur8 CLI is installed
+- When the user runs `murmur8 --version`
+- Then the CLI intercepts the flag before any command module is loaded or executed
+- And no queue state is read or modified, and no agents are spawned
+
+**AC5 — Version is read from `package.json` at runtime**
+- Given the murmur8 CLI is installed
+- When any version invocation is run
+- Then the printed version string matches the `version` field in the root `package.json` exactly
+- And the output is not a hardcoded string
+
+**AC6 — Error path: unreadable `package.json`**
+- Given the root `package.json` cannot be read (e.g., missing or malformed)
+- When the user runs any version invocation
+- Then the process exits with a non-zero exit code
+- And a descriptive error message is written to stderr
+- And no version string is printed to stdout
+
+**AC7 — No side effects**
+- Given any version invocation is run
+- When the command completes
+- Then no files under `.claude/` are created or modified
+- And no pipeline stages are entered
+
+---
+
+## Out of Scope
+
+- Displaying the Node.js version alongside the murmur8 version
+- Displaying versions of peer dependencies
+- `v`-prefixed output (e.g., `v4.7.6`) — output is always bare semver
+- Remote registry version checking or update notifications
+- Structured output formats (e.g., `--format=json`)
+- Changelog or release notes output

package/REFINE_SKILL.md

@@ -2,6 +2,11 @@
 
 Refine an existing feature by conversing with Alex, then propagating changes through stories, tests, and implementation.
 
+## Execution Contract
+
+**You MUST execute ALL steps in sequence through to Step 8 (telemetry + commit).**
+Do not stop after implementation. The pipeline is not complete until Step 8 runs.
+
 ## Invocation
 
 ```bash

package/SKILL.md

@@ -5,6 +5,11 @@ description: Run the Alex → Cass → Nigel → Codey pipeline using Task tool
 
 # Implement Feature Skill
 
+## Execution Contract
+
+**You MUST execute ALL steps in sequence through to Step 12 (telemetry + summary).**
+Do not stop after implementation or commit. The pipeline is not complete until Step 12 runs.
+
 ## Paths
 
 | Var | Path |

package/bin/cli.js

@@ -18,6 +18,13 @@ const resolvedCommand = aliases[command] || command;
 
 // Dynamic command loading
 async function main() {
+  // Handle --version / -V flags
+  if (command === '--version' || command === '-V') {
+    const version = require('../src/commands/version');
+    version.run(args, { pkgRoot: path.join(__dirname, '../') });
+    return;
+  }
+
   // Handle help/no command
   if (!command || command === 'help' || command === '--help' || command === '-h') {
     const help = require('../src/commands/help');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "murmur8",
-  "version": "4.7.6",
+  "version": "4.7.8",
   "description": "Multi-agent workflow framework for automated feature development",
   "main": "src/index.js",
   "bin": {

package/src/commands/help.js

@@ -62,11 +62,16 @@ Commands:
   murm-config           View murmuration pipeline configuration
   murm-config set <key> <value>  Modify config (cli, skill, skillFlags, etc.)
   murm-config reset     Reset murmuration configuration to defaults
+  version               Print the installed murmur8 version
   help                  Show this help message
 
   Aliases: parallel, murmuration (same as murm)
            parallel-config (same as murm-config)
 
+Flags:
+  --version, -V         Print version and exit
+  --help, -h            Show this help message
+
 Examples:
   npx murmur8 init
   npx murmur8 update

package/src/commands/version.js

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * version command - Print the installed murmur8 version
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const description = 'Print the installed murmur8 version';
+
+function run(args, options = {}) {
+  const pkgRoot = options.pkgRoot || path.join(__dirname, '../../');
+  const pkgPath = path.join(pkgRoot, 'package.json');
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  } catch (err) {
+    process.stderr.write(`Error: could not read package.json: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(pkg.version + '\n');
+  process.exit(0);
+}
+
+module.exports = { run, description };

package/src/telemetry.js

@@ -168,7 +168,9 @@ function sendTelemetry(payload, config) {
   if (!url) return Promise.resolve();
 
   return new Promise((resolve) => {
-    const body = JSON.stringify(payload);
+    // Portal expects flat fields — unwrap the { runId, run } envelope if present
+    const data = (payload && payload.run) ? payload.run : payload;
+    const body = JSON.stringify(data);
     const parsedUrl = new URL(url);
     const isHttps = parsedUrl.protocol === 'https:';
     const transport = isHttps ? require('https') : require('http');
@@ -181,7 +183,7 @@ function sendTelemetry(payload, config) {
       headers: {
         'Content-Type': 'application/json',
         'Content-Length': Buffer.byteLength(body),
-        'X-API-Key': key || '',
+        'Authorization': `Bearer ${key || ''}`,
       },
     };