@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/commands/observability/cost.js

@@ -1,32 +1,5 @@
-/**
- * `morph-spec cost [feature] [--by phase] [--all-trees] [--metrics [--top n]] [--json]`
- *
- * A cost-facing view over the same harness event stream `telemetry` reads
- * (.morph/logs/events.jsonl): how many context bytes were re-ingested (grouped by kind: rubric/standard/skill/agents/plan-artifact/
- * code), and how many sub-agent dispatches happened (with total prompt
- * chars). When the stream has `SessionUsage` events (real, hook-observed
- * token counts), those are summed and shown too — see the sessionUsage
- * caveat below.
- *
- * IMPORTANT: bytes re-ingested is a DETERMINISTIC PROXY for cost, not a
- * token count. Hooks only see what tools read off disk — never the model's
- * actual token usage — so this measures re-ingestion pressure, not spend.
- * `sessionUsage` (when present) is the exception: real tokens, observed
- * directly, not a proxy — see aggregateCost's docstring for the contract.
- *
- * `--all-trees` widens the source from "just the current tree" to every git
- * worktree that has its own events.jsonl plus the logs `finish` saved before
- * removing a worktree, deduplicated by eventId.
- *
- * `--metrics` measures the loop instead: turns, tool calls by orchestrator and
- * sub-agent, time per command class, identical reruns and why, rereads, how
- * many verifies each feature ran, git calls and whether
- * the reuse validator ran in root and worktree (see lib/telemetry/metrics.js).
- *
- * Read-only, always exits 0 on a normal (even empty) run — fail-open, an
- * empty stream is an answer, not an error. Only `--by` with an unknown value
- * is a usage error (exit 1).
- */
+// Bytes re-ingested is a deterministic proxy for cost, not a token count: hooks only see what
+// tools read off disk. `sessionUsage` is the exception, real hook-observed tokens.
 
 import chalk from 'chalk';
 import { loadTelemetry, loadTelemetryAllTrees, aggregateCost, dedupeEvents } from '../../lib/telemetry/telemetry-reader.js';
@@ -79,10 +52,6 @@ function tokenLine(u) {
     + `cacheRead=${u.cacheReadTokens}  cacheCreation=${u.cacheCreationTokens}`;
 }
 
-/**
- * Real (hook-observed) token counts — the non-proxy sibling of the bytes
- * above: the main sessions and, separately, the sub-agents.
- */
 function printSessionUsage(summary) {
   const { sessionUsage, agentUsage, sessionUsageLegacySamples } = summary;
   if (sessionUsage) {
@@ -178,10 +147,6 @@ function printMetricsBody(m) {
   for (const [reason, n] of Object.entries(m.reuse.skipReasons)) console.log(chalk.gray(`    pulou ${n}×: ${reason}`));
 }
 
-/**
- * `--metrics`: the loop measurements over the current tree (and, with
- * `--all-trees`, every tree plus the finish backups, deduplicated).
- */
 function printMetrics(feature, options, cwd) {
   const events = options.allTrees
     ? dedupeEvents(loadTelemetryAllTrees(cwd).flatMap((t) => t.events))
@@ -202,16 +167,6 @@ function printMetrics(feature, options, cwd) {
   printMetricsBody(metrics);
 }
 
-/**
- * `--all-trees` rendering: a short line per tree (so a fleet operator can
- * spot which tree is expensive) followed by the COMBINED aggregate — full
- * detail (the phase breakdown honors `--by` here too, same as the
- * single-tree path; a typeable flag combination is never a silent no-op).
- *
- * @param {string} [feature]
- * @param {{ json?: boolean, by?: 'phase' }} options
- * @param {string} cwd
- */
 function printAllTrees(feature, options, cwd) {
   const treesData = loadTelemetryAllTrees(cwd);
   const perTree = treesData.map(({ tree, path, events }) => ({
@@ -254,10 +209,6 @@ function printAllTrees(feature, options, cwd) {
   }
 }
 
-/**
- * @param {string} [feature] - narrow to a single feature
- * @param {{ json?: boolean, by?: 'phase', allTrees?: boolean, cwd?: string }} [options]
- */
 export function costCommand(feature, options = {}) {
   if (options.by && !BY_MODES.includes(options.by)) {
     console.error(chalk.red(`\n❌ Invalid --by: "${options.by}"`));
@@ -274,8 +225,7 @@ export function costCommand(feature, options = {}) {
   }
 
   if (options.allTrees) {
-    // Same fail-open + Windows-flush discipline as the single-tree path
-    // below — no forced process.exit(), --json included.
+    // No process.exit() here either, --json included.
     printAllTrees(feature, options, cwd);
     return;
   }
@@ -284,10 +234,8 @@ export function costCommand(feature, options = {}) {
   const summary = aggregateCost(events, { feature });
 
   if (options.json) {
-    // No forced process.exit() here: on Windows a piped stdout write is
-    // async, and exit()ing right after a large console.log can race the
-    // flush and truncate output. Letting the event loop drain naturally
-    // (nothing else keeps it alive in this command) exits 0 without risk.
+    // No process.exit(): on Windows a piped stdout write is async, and exiting right after a
+    // large console.log can truncate the output.
     console.log(JSON.stringify(summary));
     return;
   }

package/src/commands/observability/telemetry.js

@@ -1,14 +1,3 @@
-/**
- * `morph-spec telemetry [--json] [--feature <name>] [--limit <n>]`
- *
- * The reader surface over the harness event stream (.morph/logs/events.jsonl,
- * written by the telemetry-log hook). Reconstructs the whole execution path of
- * an NLH session: top skills, personas dispatched, standards (knowledge base)
- * read, the tool mix, and the recent prompts (user + sub-agent).
- *
- * Read-only, always exits 0 (fail-open — an empty stream is an answer).
- */
-
 import chalk from 'chalk';
 import { loadTelemetry, aggregateTelemetry } from '../../lib/telemetry/telemetry-reader.js';
 
@@ -23,9 +12,7 @@ function section(title, rows, fmt) {
   for (const r of rows) console.log('  ' + fmt(r));
 }
 
-/**
- * @param {{ json?: boolean, feature?: string, limit?: number, cwd?: string }} [options]
- */
+// Read-only and always exits 0: an empty stream is an answer.
 export function telemetryCommand(options = {}) {
   const events = loadTelemetry(options.cwd || process.cwd());
   const summary = aggregateTelemetry(events, { feature: options.feature });

package/src/commands/project/branch.js

@@ -1,23 +1,3 @@
-/**
- * branch.js — `morph-spec branch prune`.
- *
- * The gap this closes: after a few features close by squash-merge, the local
- * repo accumulates branches git considers unmerged. `git branch --merged` lists
- * none of them, `git branch -d` refuses each one, and the only command left is
- * `git branch -D` — which is EXACTLY the command for throwing away real work.
- * Once a user has typed `-D` on five safe branches, the sixth (an actual
- * unintegrated feature) gets the same keystroke.
- *
- * So this command never asks the user to make that distinction: it makes it
- * itself, prints the evidence for each branch, and deletes only what it PROVED
- * is already integrated (see branch-classifier.js for the five classes and
- * their order). Everything else is listed with the reason it survives.
- *
- * The remote is a separate decision: `--remote` is required to touch
- * `origin/<branch>`, because a local branch is a local artifact while the remote
- * one may be what someone else, or an open review, is looking at.
- */
-
 import { execFileSync } from 'child_process';
 import chalk from 'chalk';
 import { isGitRepo, resolvePrimaryRoot } from './worktree.js';
@@ -25,15 +5,8 @@ import { detectDefaultBranch } from '../../lib/git/default-branch.js';
 import { buildPrIndex } from '../../lib/git/pr-index.js';
 import { classifyBranches } from '../../lib/git/branch-classifier.js';
 
-/**
- * Delete one local branch.
- *
- * `-D`, not `-d`, and that is the whole point of the classifier: `-d` refuses
- * every squash-merged branch, so a command that used it would be unable to do
- * its one job. The safety does not come from git's own check (which cannot see
- * a squash-merge) — it comes from only ever reaching this function with a
- * branch whose integration was positively proven.
- */
+// `-D`, not `-d`: `-d` refuses every squash-merged branch. Safety comes from only
+// reaching here with integration positively proven.
 function deleteLocal(name, cwd) {
   try {
     execFileSync('git', ['branch', '-D', name], { cwd, stdio: 'pipe' });
@@ -52,7 +25,6 @@ function deleteRemote(name, cwd) {
   }
 }
 
-/** Does `origin/<name>` exist locally as a remote-tracking ref? */
 function remoteRefExists(name, cwd) {
   try {
     execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/remotes/origin/${name}`], { cwd, stdio: 'pipe' });
@@ -62,15 +34,6 @@ function remoteRefExists(name, cwd) {
   }
 }
 
-/**
- * Command handler for `morph-spec branch prune [--remote] [--dry-run] [--json]`.
- *
- * Fail-open outside a git repo (exit 0, empty result) — the same discipline the
- * rest of the worktree suite follows: a housekeeping command must never be the
- * reason a script dies.
- *
- * @param {{ remote?: boolean, dryRun?: boolean, json?: boolean, cwd?: string }} [options]
- */
 export function branchPruneCommand(options = {}) {
   const cwd = options.cwd || process.cwd();
   const emit = (payload, code = 0) => {
@@ -85,9 +48,7 @@ export function branchPruneCommand(options = {}) {
   }
   const root = resolvePrimaryRoot(cwd);
   const defaultBranch = detectDefaultBranch(root);
-  // null = UNKNOWN, never "no PR" — the classifier treats a branch with no
-  // positive evidence as unmerged, so a missing `gh` costs conservatism, not
-  // safety. Reported so the user can tell "no PR" from "could not ask".
+  // null = UNKNOWN, never "no PR": a missing `gh` costs conservatism, not safety.
   const prIndex = buildPrIndex(root);
 
   const classified = classifyBranches({ cwd: root, defaultBranch, prIndex });
@@ -139,9 +100,7 @@ function printReport(payload, options) {
   const verb = payload.dryRun ? 'seriam apagadas' : 'apagadas';
   console.log(chalk.bold(`\nbranch prune — default: ${payload.defaultBranch || chalk.red('não resolvida')}`));
   if (!payload.prIndexAvailable) {
-    // Load-bearing caveat, not noise: without `gh` a squash-merge is only
-    // detectable by the tree comparison, so branches that WERE merged may
-    // legitimately show up as unmerged here.
+    // Without `gh`, squash-merged branches may legitimately show as unmerged.
     console.log(chalk.gray('  (sem `gh`/GitHub: squash-merge só é detectado por árvore idêntica)'));
   }
 

package/src/commands/project/claim.js

@@ -1,24 +1,3 @@
-/**
- * `morph-spec claim [feature] [--release] [--list]` — the manual half of
- * advisory feature ownership (B1).
- *
- * Claims are acquired and heartbeaten AUTOMATICALLY (SessionStart hook +
- * telemetry hook), so the operator never has to remember anything. This command
- * exists for the two cases automation cannot cover:
- *   - a session that died without releasing, leaving a claim that keeps
- *     warning everyone until its TTL expires (`--release`);
- *   - an operator switching this SAME session/tree to a different feature
- *     mid-task. `morph-spec claim <feature>` (no flags) ACQUIRES it, moving
- *     the tree's previous claim in the same step — a manual release-then-
- *     reclaim was observed to just not happen mid-task, and the silent no-op
- *     this used to be (any unclaimed feature name printed "nothing here" and
- *     changed nothing) was worse: it looked like a query, not a skipped write.
- *
- * `--list` forces the read-only view even when a feature is named. `--release`
- * is the only other mutation. Always exits 0 except on a genuine misuse — the
- * claim system is advisory and must never become a source of hard failures.
- */
-
 import chalk from 'chalk';
 import { execSync } from 'child_process';
 import { resolve } from 'path';
@@ -31,7 +10,6 @@ import {
   claimAge,
 } from '../../../framework/hooks/shared/claim-registry.js';
 
-/** Resolve the repo's shared git common dir — where claims live. */
 function gitCommonDirOf(cwd) {
   const root = resolvePrimaryRoot(cwd);
   const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
@@ -41,15 +19,8 @@ function gitCommonDirOf(cwd) {
 const norm = (p) => String(p ?? '').replace(/\\/g, '/');
 
 /**
- * Acquire `feature`'s claim, moving it in the same step if this tree already
- * holds a live claim on a different feature.
- *
- * "This tree's own claim" is identified by PATH, not session id: the CLI has
- * no access to the Claude Code session id SessionStart stamps (that only
- * reaches hooks, via stdin JSON) — path is the one honest signal a manual
- * invocation shares with the automatic claim it may be replacing. Re-using
- * that claim's session id when re-acquiring keeps the move from reading as a
- * takeover of a stranger.
+ * Moves this tree's live claim, identified by PATH: the CLI never sees the session id
+ * SessionStart stamps. Reusing that claim's session id keeps the move from reading as a takeover.
  */
 function acquireOrMove(feature, { cwd, gitCommonDir, json }) {
   const here = norm(cwd);
@@ -84,10 +55,6 @@ function acquireOrMove(feature, { cwd, gitCommonDir, json }) {
   process.exit(0);
 }
 
-/**
- * @param {string|undefined} feature
- * @param {{ release?: boolean, list?: boolean, json?: boolean, cwd?: string }} [options]
- */
 export function claimCommand(feature, options = {}) {
   const cwd = options.cwd || process.cwd();
   if (!isGitRepo(cwd)) {
@@ -120,27 +87,16 @@ export function claimCommand(feature, options = {}) {
     process.exit(0);
   }
 
-  // `morph-spec claim <feature>` (no --release, no --list) is the manual
-  // acquire/move half of B1 — automation (SessionStart + heartbeat) covers the
-  // common case; this covers switching this session to a different feature
-  // mid-task without a release-then-reclaim dance. `--list` forces the
-  // read-only view below even when a feature is named.
   if (feature && !options.list) {
     acquireOrMove(feature, { cwd, gitCommonDir, json: options.json });
     return;
   }
 
-  // No feature (or explicit --list): the read-only board, whole or filtered.
   const all = listClaims(gitCommonDir);
   const scoped = feature ? all.filter((c) => c.feature === feature) : all;
 
-  // Um claim morto NÃO é limpo do registro — ele só para de avisar (o TTL de
-  // 30 min o mata, `live` é computado na leitura). O efeito colateral é que o
-  // board acumula: features encerradas há 20h e 73h apareciam no `--list` como
-  // se fossem informação. Um quadro de avisos onde quase nada é aviso ensina a
-  // não olhar o quadro. Por padrão mostramos só o que ainda avisa; `--all`
-  // devolve o registro inteiro, e o rodapé conta o que ficou de fora para a
-  // omissão nunca ser silenciosa.
+  // Claim morto segue no registro (`live` é computado na leitura): por padrão só o que ainda
+  // avisa; `--all` devolve tudo e o rodapé conta o que ficou de fora.
   const rows = options.all ? scoped : scoped.filter((c) => c.live);
   const hidden = scoped.length - rows.length;