@pmelab/gtd 38.1.0 → 39.0.0

package/src/cli/Cli.test.ts

@@ -1021,14 +1021,21 @@ describe("parseArgv — gtd history", () => {
     expect(parse("history", "fetch", "upstream")).toMatchObject({
       command: { kind: "historyFetch", remote: "upstream" },
     })
+    expect(parse("history", "metrics")).toMatchObject({
+      command: { kind: "historyMetrics", refs: [] },
+    })
+    expect(parse("history", "metrics", "a", "feat/b")).toMatchObject({
+      command: { kind: "historyMetrics", refs: ["a", "feat/b"] },
+    })
   })
 
-  it("bare history and an unknown subcommand are usage errors naming list, show, fetch", () => {
+  it("bare history and an unknown subcommand are usage errors naming list, show, metrics, fetch", () => {
     for (const args of [["history"], ["history", "nope"]]) {
       const message = usage(parse(...args))
       expect(message).toContain("list")
       expect(message).toContain("show")
       expect(message).toContain("fetch")
+      expect(message).toContain("metrics")
     }
   })
 
@@ -1039,19 +1046,23 @@ describe("parseArgv — gtd history", () => {
     expect(usage(parse("history", "fetch", "a", "b"))).toContain("too many arguments")
   })
 
-  it("--json is accepted for list and show, rejected for fetch", () => {
+  it("--json is accepted for list, show and metrics, rejected for fetch", () => {
     expect(parse("history", "list", "--json")).toMatchObject({ json: { kind: "document" } })
     expect(parse("history", "show", "x", "--json=ended")).toMatchObject({
       json: { kind: "select", path: "ended" },
     })
+    expect(parse("history", "metrics", "--json=total.refactorFirstRate")).toMatchObject({
+      json: { kind: "select", path: "total.refactorFirstRate" },
+    })
     expect(parse("history", "fetch", "--json").kind).toBe("usage")
   })
 
-  it("help lists the three history rows", () => {
+  it("help lists the four history rows", () => {
     const help = renderHelp()
     expect(help).toMatch(/^ {2}history list\b/m)
     expect(help).toContain("history show <ref>")
     expect(help).toContain("history fetch [remote]")
+    expect(help).toContain("history metrics [ref...]")
   })
 })
 
@@ -1136,6 +1147,7 @@ describe("standaloneKinds / needsOf", () => {
       "slices",
       "historyList",
       "historyShow",
+      "historyMetrics",
       "historyFetch",
     ] as const) {
       expect(needsOf(kind)).toBe("state")

package/src/cli/Cli.ts

@@ -97,29 +97,33 @@ const share = (raw: string, flag: string): Either.Either<number, string> => {
     : Either.left(`gtd: ${flag} must be a share of the context window in (0, 1] — got "${raw}"`)
 }
 
+const JSON_KINDS: ReadonlySet<Command["kind"] | undefined> = new Set<Command["kind"]>([
+  "next",
+  "land",
+  "judge",
+  "judgeAnswer",
+  "doors",
+  "slices",
+  "historyList",
+  "historyShow",
+  "historyMetrics",
+  "strays",
+])
+
 const FLAGS: readonly FlagRow[] = [
   {
     name: "--json",
     arity: "optional",
     repeatable: false,
-    scope: (kind) =>
-      kind === "next" ||
-      kind === "land" ||
-      kind === "judge" ||
-      kind === "judgeAnswer" ||
-      kind === "doors" ||
-      kind === "slices" ||
-      kind === "historyList" ||
-      kind === "historyShow" ||
-      kind === "strays",
+    scope: (kind) => JSON_KINDS.has(kind),
     decode: ([raw]) => Either.right(raw ?? ""),
     scopeError:
-      "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors`/`gtd slices`/`gtd history list`/`gtd history show`/`gtd strays` — " +
+      "gtd: --json is only valid for `gtd next`/`gtd land`/`gtd judge`/`gtd judge answer`/`gtd doors`/`gtd slices`/`gtd history list`/`gtd history show`/`gtd history metrics`/`gtd strays` — " +
       "every other command prints plain text; see `gtd install` for the driver protocol briefing",
     valueHint: "<path>",
     help: [
       "(gtd next/gtd land/gtd judge/gtd judge answer/gtd doors/gtd slices/gtd history",
-      "list/gtd history show/gtd strays only) output structured JSON. Bare --json prints the whole document;",
+      "list/gtd history show/gtd history metrics/gtd strays only) output structured JSON. Bare --json prints the whole document;",
       "--json=<path> (a dotted key path into that document, e.g.",
       "kind, content, session.id) prints just that value: a",
       "scalar raw and unquoted, a boolean as true/false, a list",
@@ -445,6 +449,8 @@ type Arity =
   | { readonly name: string; readonly variadic: string }
   // At most one trailing positional.
   | { readonly name: string; readonly optional: true }
+  // Any number of positionals, none included.
+  | { readonly name: string; readonly many: true }
 
 interface CommandRow {
   readonly token: string
@@ -824,6 +830,23 @@ const COMMAND_ROWS: readonly CommandRow[] = [
       "prints the trail as one document; writes nothing",
     ],
   },
+  {
+    token: "history metrics",
+    kind: "historyMetrics",
+    arity: { name: "ref", many: true },
+    details: [
+      "Report how the kept processes went: slices whose naive pass",
+      "landed or was rebuilt (the refactor-first rate), continuations",
+      "per phase, Gtd-Cost by model and phase with the double work of",
+      "a rebuild, quality-lap findings per lens, and red checks that",
+      "passed on their re-check — per process and in total. Each <ref>",
+      "is read as by history show, but a branch name means every",
+      "process kept from it; none means every ref.",
+      "Reads commit subjects and trailers, never replays, so a",
+      "changed config is no refusal. --json prints { processes, total",
+      "} as one document; writes nothing",
+    ],
+  },
   {
     token: "history fetch",
     kind: "historyFetch",
@@ -883,7 +906,9 @@ export const renderHelp = (): string => {
             ? `${row.token} <${row.arity.name}> [${row.arity.variadic}...]`
             : "optional" in row.arity
               ? `${row.token} [${row.arity.name}]`
-              : `${row.token} <${row.arity.name}>`
+              : "many" in row.arity
+                ? `${row.token} [${row.arity.name}...]`
+                : `${row.token} <${row.arity.name}>`
     return renderBlock(header, row.details)
   })
   const commands = [
@@ -1051,23 +1076,23 @@ const conflictViolation = (present: ReadonlySet<string>): string | undefined =>
   return undefined
 }
 
+const tooMany = (
+  cmd: string,
+  rest: readonly string[],
+  expected: string,
+  max: number,
+): string | undefined =>
+  rest.length > max
+    ? `gtd ${cmd}: too many arguments — expected ${expected}, got: ${rest.join(", ")}`
+    : undefined
+
 const arityError = (cmd: string, rest: readonly string[], arity: Arity): string | undefined => {
-  if (arity === "none") {
-    return rest.length > 0
-      ? `gtd ${cmd}: too many arguments — expected none, got: ${rest.join(", ")}`
-      : undefined
-  }
+  if (arity === "none") return tooMany(cmd, rest, "none", 0)
   if ("names" in arity) return pairArityError(cmd, rest, arity.names)
-  if ("optional" in arity) {
-    return rest.length > 1
-      ? `gtd ${cmd}: too many arguments — expected at most one ${arity.name}, got: ${rest.join(", ")}`
-      : undefined
-  }
+  if ("many" in arity) return undefined
+  if ("optional" in arity) return tooMany(cmd, rest, `at most one ${arity.name}`, 1)
   if (rest.length === 0) return `gtd ${cmd}: missing ${arity.name} argument`
-  if (!("variadic" in arity) && rest.length > 1) {
-    return `gtd ${cmd}: too many arguments — expected one ${arity.name}, got: ${rest.join(", ")}`
-  }
-  return undefined
+  return "variadic" in arity ? undefined : tooMany(cmd, rest, `one ${arity.name}`, 1)
 }
 
 const pairArityError = (
@@ -1138,7 +1163,7 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
 
   if (isHistory && row === undefined) {
     return usagePlan(
-      "gtd history: expected a subcommand — list, show <ref> or fetch [remote]",
+      "gtd history: expected a subcommand — list, show <ref>, metrics [ref...] or fetch [remote]",
       jsonSeen,
     )
   }
@@ -1381,6 +1406,15 @@ export const parseArgv = (argv: readonly string[]): CliPlan => {
     }
   }
 
+  if (kind === "historyMetrics") {
+    return {
+      kind: "command",
+      command: { kind: "historyMetrics", refs: restPositionals },
+      json,
+      verbose,
+    }
+  }
+
   if (kind === "historyFetch") {
     return {
       kind: "command",

package/src/cli/History.ts

@@ -3,12 +3,7 @@ import { historyTrail } from "../edge/index.js"
 import { combinedScript, fetchHistoryRefs } from "../emit/index.js"
 import { GitService, Narrator, PROCESS_HISTORY_PREFIX } from "../platform/index.js"
 import { parseCommitMessage } from "../replay/index.js"
-import {
-  writeSelection,
-  type ArtifactOut,
-  type CommandRequirements,
-  type JsonMode,
-} from "./Output.js"
+import { writeJson, type ArtifactOut, type CommandRequirements, type JsonMode } from "./Output.js"
 
 export interface HistoryEntry {
   readonly ref: string
@@ -80,19 +75,6 @@ export const resolveHistoryRef = (
 
 const seven = (hash: string): string => hash.slice(0, 7)
 
-/** Writes `document` per `json` (bare → whole, `=path` → one value); returns false for `off`. */
-const writeJson = (
-  json: JsonMode,
-  out: ArtifactOut,
-  document: unknown,
-): Effect.Effect<boolean, Error> =>
-  Effect.gen(function* () {
-    if (json.kind === "off") return false
-    if (json.kind === "document") out.write(`${JSON.stringify(document)}\n`)
-    else yield* writeSelection(out, document, json.path)
-    return true
-  })
-
 export const runHistoryListCommand = (
   json: JsonMode,
   out: ArtifactOut,

package/src/cli/Metrics.test.ts

@@ -0,0 +1,255 @@
+import { Effect } from "effect"
+import { describe, expect, it } from "vitest"
+import { applyEmittedScript, InMemRepo, makeCapturingCliIo, testLayers } from "../testkit/index.js"
+import { runCli } from "./index.js"
+import { processMetrics, readProcessMetrics, totalMetrics, type MetricCommit } from "./Metrics.js"
+
+const turn = (subject: string, opts: { cost?: string; findings?: number } = {}): MetricCommit => ({
+  message: opts.cost === undefined ? subject : `${subject}\n\nGtd-Cost: ${opts.cost}`,
+  findings: opts.findings ?? 0,
+})
+
+describe("processMetrics", () => {
+  it("counts a naive pass applied as it is as a landed slice", () => {
+    const m = processMetrics([
+      turn("gtd(human): idle → seam.naive"),
+      turn("gtd(agent): seam.naive → seam.check", { cost: "0.4 coder" }),
+      turn("gtd(check): seam.check → implement.applying"),
+      turn("gtd(check): implement.applying → idle"),
+    ])
+    expect(m.slices).toEqual({ decided: 1, landed: 1, rebuilt: 0, refactored: 0 })
+    expect(m.refactorFirstRate).toBe(0)
+    expect(m.cost.byPhase).toEqual({ naive: 0.4, refactor: 0, implement: 0, other: 0 })
+    expect(m.cost.doubleWork).toEqual({ naive: 0, rebuild: 0, total: 0 })
+  })
+
+  it("charges a rebuilt slice's naive pass and rebuild as double work, refactor apart", () => {
+    const m = processMetrics([
+      turn("gtd(human): idle → seam.naive"),
+      turn("gtd(agent): seam.naive → seam.continue.naive", { cost: "0.4 coder" }),
+      turn("gtd(agent): seam.continue.naive → seam.judge", { cost: "0.2 coder" }),
+      turn("gtd(judge): seam.judge → seam.note", { cost: "0.01 judge" }),
+      turn("gtd(agent): seam.note → refactor.deriving", { cost: "0.05 coder" }),
+      turn("gtd(check): refactor.deriving → refactor.building"),
+      turn("gtd(agent): refactor.building → refactor.closing", { cost: "0.3 coder" }),
+      turn("gtd(check): refactor.closing → implement.building"),
+      turn("gtd(agent): implement.building → implement.continue.building", { cost: "0.5 coder" }),
+      turn("gtd(agent): implement.continue.building → idle", { cost: "0.25 coder" }),
+    ])
+    expect(m.slices).toEqual({ decided: 1, landed: 0, rebuilt: 1, refactored: 1 })
+    expect(m.refactorFirstRate).toBe(1)
+    expect(m.continuations).toEqual({ "seam.naive": 1, "implement.building": 1 })
+    expect(m.cost.total).toBe(1.71)
+    expect(m.cost.byModel).toEqual({ coder: 1.7, judge: 0.01 })
+    expect(m.cost.byPhase).toEqual({ naive: 0.6, refactor: 0.35, implement: 0.75, other: 0.01 })
+    expect(m.cost.doubleWork).toEqual({ naive: 0.6, rebuild: 0.75, total: 1.35 })
+  })
+
+  it("rebuilds without a refactor when the slice leaves the seam for a build turn", () => {
+    const m = processMetrics([
+      turn("gtd(judge): seam.judge → implement.building"),
+      turn("gtd(agent): implement.building → idle"),
+    ])
+    expect(m.slices).toEqual({ decided: 1, landed: 0, rebuilt: 1, refactored: 0 })
+  })
+
+  it("keeps each slice's decision apart", () => {
+    const m = processMetrics([
+      turn("gtd(agent): seam.naive → seam.check", { cost: "1" }),
+      turn("gtd(check): seam.check → implement.applying"),
+      turn("gtd(agent): implement.building → implement.health.check", { cost: "1" }),
+      turn("gtd(check): implement.closing → seam.naive"),
+      turn("gtd(agent): seam.naive → seam.note", { cost: "2" }),
+      turn("gtd(agent): seam.note → refactor.deriving"),
+      turn("gtd(agent): refactor.continue.building → refactor.closing", { cost: "1" }),
+      turn("gtd(check): refactor.closing → implement.building"),
+      turn("gtd(agent): implement.building → idle", { cost: "3" }),
+    ])
+    expect(m.slices).toEqual({ decided: 2, landed: 1, rebuilt: 1, refactored: 1 })
+    expect(m.refactorFirstRate).toBe(0.5)
+    expect(m.continuations).toEqual({ "refactor.building": 1 })
+    expect(m.cost.byModel).toEqual({ unspecified: 8 })
+    expect(m.cost.doubleWork).toEqual({ naive: 2, rebuild: 3, total: 5 })
+  })
+
+  it("counts a naive retry in a fresh conversation as naive cost", () => {
+    const m = processMetrics([
+      turn("gtd(agent): seam.continue.naive → seam.judge", { cost: "1" }),
+      turn("gtd(judge): seam.judge → seam.fresh.naive"),
+      turn("gtd(agent): seam.fresh.naive → seam.judge", { cost: "2" }),
+      turn("gtd(judge): seam.judge → implement.building"),
+    ])
+    expect(m.cost.byPhase.naive).toBe(3)
+    expect(m.cost.doubleWork.naive).toBe(3)
+  })
+
+  it("turns a landed slice whose naive pass fails to apply into a rebuild", () => {
+    const m = processMetrics([
+      turn("gtd(agent): seam.naive → seam.check", { cost: "1" }),
+      turn("gtd(check): seam.check → implement.applying"),
+      turn("gtd(check): implement.applying → implement.building"),
+      turn("gtd(agent): implement.building → implement.health.check", { cost: "2" }),
+    ])
+    expect(m.slices).toEqual({ decided: 1, landed: 0, rebuilt: 1, refactored: 0 })
+    expect(m.cost.doubleWork).toEqual({ naive: 1, rebuild: 2, total: 3 })
+  })
+
+  it("keeps the refactor lap's lens findings apart from the feature lap's", () => {
+    const m = processMetrics([
+      turn("gtd(agent): refactor.build.quality.correctness.reviewing → refactor.closing", {
+        findings: 3,
+      }),
+      turn("gtd(agent): build.quality.correctness.reviewing → idle", { findings: 2 }),
+    ])
+    expect(m.findings.byLens).toEqual({
+      "refactor.build.quality.correctness": 3,
+      "build.quality.correctness": 2,
+    })
+  })
+
+  it("ends a rebuild's double work at the slice's closing", () => {
+    const m = processMetrics([
+      turn("gtd(judge): seam.judge → implement.building"),
+      turn("gtd(agent): implement.building → implement.closing", { cost: "1" }),
+      turn("gtd(check): implement.closing → build.quality.correctness.reviewing"),
+      turn("gtd(agent): implement.building → idle", { cost: "2" }),
+    ])
+    expect(m.cost.doubleWork.rebuild).toBe(1)
+    expect(m.cost.byPhase.implement).toBe(3)
+  })
+
+  it("keeps a model named like an Object member a plain key", () => {
+    const m = processMetrics([
+      turn("gtd(agent): seam.naive → seam.check", { cost: "0.4 constructor" }),
+      turn("gtd(agent): seam.naive → seam.check", { cost: "0.1 __proto__" }),
+    ])
+    expect(m.cost.total).toBe(0.5)
+    expect(Object.entries(m.cost.byModel)).toEqual([
+      ["constructor", 0.4],
+      ["__proto__", 0.1],
+    ])
+  })
+
+  it("has no refactor-first rate without a seam decision", () => {
+    expect(processMetrics([turn("gtd(human): idle → building")]).refactorFirstRate).toBeNull()
+  })
+
+  it("counts continuations only for agent turns, the bare form included", () => {
+    const m = processMetrics([
+      turn("gtd(agent): seam.continue.naive"),
+      turn("gtd(human): seam.continue.naive → seam.oversized"),
+    ])
+    expect(m.continuations).toEqual({ "seam.naive": 1 })
+  })
+
+  it("sums findings per quality lens and skips commits gtd did not write", () => {
+    const m = processMetrics([
+      turn(
+        "gtd(agent): build.quality.correctness.reviewing → build.quality.conventions.reviewing",
+        {
+          findings: 2,
+        },
+      ),
+      turn("gtd(agent): build.quality.conventions.reviewing → build.fix.quality.fixing", {
+        findings: 1,
+      }),
+      turn("fix: a hand-made commit", { cost: "5" }),
+    ])
+    expect(m.findings).toEqual({
+      total: 3,
+      byLens: { "build.quality.correctness": 2, "build.quality.conventions": 1 },
+    })
+    expect(m.cost.total).toBe(0)
+  })
+})
+
+describe("flaky re-checks", () => {
+  it("counts each flaky re-check under its own full step name", () => {
+    const m = processMetrics([
+      {
+        message:
+          "gtd(check): start-gate.recheck → design.triage\n\nGtd-Mark: flaky=start-gate.check",
+        findings: 0,
+      },
+      {
+        message: "gtd(check): build.health.recheck → idle\n\nGtd-Mark: flaky=health.check",
+        findings: 0,
+      },
+      {
+        message:
+          "gtd(check): implement.health.recheck → implement.closing\n\nGtd-Mark: flaky=health.check",
+        findings: 0,
+      },
+      { message: "gtd(agent): seam.naive → seam.check\n\nGtd-Mark: covers=AC-1", findings: 0 },
+      { message: "fix: hand-made\n\nGtd-Mark: flaky=x.check", findings: 0 },
+    ])
+    expect(m.flaky).toEqual({
+      total: 3,
+      byStep: { "start-gate.recheck": 1, "build.health.recheck": 1, "implement.health.recheck": 1 },
+    })
+    expect(totalMetrics([m, m]).flaky).toEqual({
+      total: 6,
+      byStep: { "start-gate.recheck": 2, "build.health.recheck": 2, "implement.health.recheck": 2 },
+    })
+  })
+})
+
+describe("totalMetrics", () => {
+  it("adds processes and recomputes the rate over every decision", () => {
+    const a = processMetrics([
+      turn("gtd(agent): seam.naive → seam.check", { cost: "1 a" }),
+      turn("gtd(check): seam.check → implement.applying"),
+    ])
+    const b = processMetrics([
+      turn("gtd(agent): seam.continue.naive → seam.note", { cost: "2 b" }),
+      turn("gtd(agent): seam.note → refactor.deriving"),
+      turn("gtd(agent): seam.naive → seam.note"),
+      turn("gtd(agent): seam.note → refactor.deriving"),
+    ])
+    const total = totalMetrics([a, b])
+    expect(total.processes).toBe(2)
+    expect(total.slices).toEqual({ decided: 3, landed: 1, rebuilt: 2, refactored: 2 })
+    expect(total.refactorFirstRate).toBe(0.667)
+    expect(total.continuations).toEqual({ "seam.naive": 1 })
+    expect(total.cost.byModel).toEqual({ a: 1, b: 2 })
+  })
+})
+
+const CONFIG = `import { agent, human, scope } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle")
+  await scope("build", () => scope("quality", () => scope("correctness", () => agent("reviewing", "review"))))
+}
+`
+
+const land = async (repo: InMemRepo, files: Record<string, string>): Promise<string> => {
+  for (const [path, content] of Object.entries(files)) repo.writeFile(path, content)
+  const { io, result } = makeCapturingCliIo(repo)
+  await Effect.runPromise(runCli(["node", "gtd.js", "land", "--json"], io))
+  const { stdout, exitCode, stderr } = result()
+  if (exitCode !== 0) throw new Error(`land exited ${exitCode}: ${stderr}`)
+  const outcome = applyEmittedScript(
+    repo,
+    new Map(),
+    (JSON.parse(stdout) as { script: string }).script,
+  )
+  if (!outcome.ok) throw new Error(outcome.error)
+  return repo.resolveRef("HEAD")!
+}
+
+describe("readProcessMetrics", () => {
+  it("counts the findings a reviewing turn added to an existing QUALITY.md", async () => {
+    const repo = new InMemRepo()
+    repo.writeFile("gtd.config.ts", CONFIG)
+    repo.writeFile(".gtd/QUALITY.md", "## old finding\n")
+    repo.seedCommit("chore: add workflow")
+    const entry = await land(repo, { "NOTE.md": "go\n" })
+    const tip = await land(repo, { ".gtd/QUALITY.md": "## old finding\n\n## one\n\n## two\n" })
+    const metrics = await Effect.runPromise(
+      readProcessMetrics({ entry, tip }).pipe(Effect.provide(testLayers(repo, {}))),
+    )
+    expect(metrics.findings).toEqual({ total: 2, byLens: { "build.quality.correctness": 2 } })
+    expect(metrics.workflow).toBeNull()
+  })
+})