@dpeek/codeless 0.1.0 → 0.1.2

package/README.md

@@ -97,7 +97,7 @@ the runner does not generate or copy project instructions.
 The package-owned planner extension activates every planner session. Before its
 first project prompt, it requires the exact `<slug>-planner` Pi name, establishes
 and verifies the `<slug>_planner` Herdr identity, and confirms `approve_stream_change`,
-`dispatch_stream_implementer`, and `next_stream_change` are active. Missing or
+`dispatch_stream_implementer`, `rework_stream_implementer`, `finish_stream_implementer`, and `next_stream_change` are active. Missing or
 incompatible activation, identity mismatch, or inactive tools stops before
 `/change`; global Pi extension installation is unnecessary.
 The approval tool has no arguments. Its extension derives the active
@@ -154,9 +154,18 @@ planners or worktree shells are running.
   worktree/<slug>/    # stream/<slug> branch
   worktree/main/      # example integration checkout location
   .land-lock/         # shared landing owner and recorded integration commit
-  metrics/<slug>/NNN.json # first dispatch, landing time, and landed commit
+  metrics/<slug>/NNN.json # dispatch/landing times and deduplicated implementer attempts
 ```
 
+Run `codeless init` once after configuring a project. It creates the shared state
+layout and the dedicated integration worktree at
+`<workspace>/worktree/<integration-branch>` without requiring Herdr. For the
+default workspace it adds only `/.codeless/state/` to the primary checkout's
+`.gitignore`; an absolute workspace override does not modify repository ignores.
+It is safe to repeat when that exact worktree is registered. It stops rather
+than moving a branch checkout, replacing an occupied target, or broadening a
+repository ignore rule that covers configuration or prompts.
+
 Normal `git clean -fd` preserves ignored state. `git clean -fdx` removes ignored
 files and can therefore destroy local Codeless journals, metrics, and worktrees;
 inspect its targets before using it.
@@ -167,36 +176,65 @@ Run creation, opening, and planner launch from a Herdr-managed shell. Landing
 needs no Herdr session.
 
 ```sh
+codeless init
 codeless create <slug>
 codeless open <slug>
 codeless planner <slug>
 codeless approve <planner-session>
 codeless dispatch <numbered-change-file>
+codeless rework <numbered-change-file> <feedback>
+codeless finish <numbered-change-file>
 codeless land <slug>
 codeless next <numbered-change-file> <landed-commit>
 codeless metrics
 ```
 
-Slugs are lowercase kebab-case, at most 24 characters. `create` starts
+Slugs are lowercase kebab-case, at most 24 characters. `init` validates the
+existing configuration and integration branch, reports the branch, primary
+checkout, workspace, and integration worktree, then creates only the shared
+state directories and canonical integration worktree when absent. All other
+commands validate their prerequisites and never bootstrap this setup. `create` starts
 `stream/<slug>` from the integration branch and creates its local documents;
 it refuses existing streams. `open` resumes a stream. Both run the configured
 install command, then validate and open a planner beside an idle shell. `planner`
 starts Pi in an existing stream's lone shell after the same role preflight. Its
 activation establishes the same identity as creation and reopening.
 Dispatch validates the implementer selection before touching the planner's
-right-hand pane, starts a fresh ephemeral implementer, and waits for completion.
+right-hand pane, starts a fresh ephemeral implementer with Codeless's reporting
+extension and its explicit Pi extension flag, and waits for completion. Rework verifies
+that same change's idle implementer and worktree, invokes one package-owned Pi command
+that verifies its immutable stream/change scope, arms reporting, and submits one feedback
+turn with the same one-hour limit, records a `rework`
+attempt, and returns it before review is queued again. Finish verifies that identity,
+gracefully exits it, and waits for the right pane's stream-worktree shell. Neither operation
+replaces the agent, changes its selection, retries, or continues after a mismatch, timeout,
+blocked agent, or ambiguous pane. Its JSON result is a normalized attempt report, which the
+planner tool exposes before queueing review. It includes the actual settled model/thinking selection,
+terminal text and outcome, full-session Pi usage and available Pi cost estimate,
+timestamps, and tool/error counts; prompts, source, thinking, credentials, and
+transcripts are not retained.
 
 The first valid dispatch creates one atomic local JSON metric record for its
-stream and numbered change. Retries preserve its original dispatch time. After a
-successful integration fast-forward, Codeless records the landed time and commit
-on that change's canonical record, creating a landed record without elapsed time
-when dispatch collection was unavailable; collection warnings never alter
-dispatch or landing.
-`codeless metrics` prints every recorded stream and a project total. Its elapsed
-columns are dispatch-to-land wall-clock time; among landed changes, records
+stream and numbered change. Each accepted run receives a new attempt ID and is
+added idempotently under that record; re-ingesting an ID preserves the original
+attempt and retries preserve the original dispatch time. Missing, malformed, or
+unwritable collection data warns and stores an incomplete attempt when possible
+without retrying or failing a settled implementation. After a successful
+integration fast-forward, Codeless records the landed time and commit on that
+change's canonical record, creating a landed record without elapsed time when
+dispatch collection was unavailable; collection warnings never alter dispatch or
+landing.
+`codeless metrics` prints every recorded stream and a project total. Its first
+table reports dispatch-to-land wall-clock time; among landed changes, records
 without a measured duration are explicitly unavailable. Dispatched-but-unlanded
-changes remain a separate count. Metrics are prospective local observations, not
-journal state or a recovery mechanism.
+changes remain a separate count. Its second table reports implementer attempts:
+distinct changes with rework, initial and rework turns, incomplete collection,
+exact stored terminal outcomes, and tool errors. Usage and cost coverage count
+measured attempts separately from unavailable collection; token totals include
+only measured usage, and cost totals remain grouped by recorded currency without
+conversion. These counts do not establish implementation quality or review
+success. Metrics are prospective local observations, not journal state or a
+recovery mechanism.
 
 Landing requires clean stream and integration worktrees and exactly one stream
 commit outside their merge base. It acquires `.land-lock` atomically, recording
@@ -233,8 +271,35 @@ From this package directory, run `bun run check` for formatting, lint, types,
 and tests, or `bun run test` for tests alone. The integration tests use real Git
 worktrees and mock Herdr/Pi commands; they never launch actual agents.
 
-`npm publish` runs the full check through `prepublishOnly` and publishes
-`@dpeek/codeless` with public access.
+From a clean `main` checkout, publish the next patch release with:
+
+```sh
+bun run release
+```
+
+The script verifies npm authentication, runs the full check and an npm package
+dry run, increments the patch version, commits `package.json` with the version as
+the complete commit message, creates the matching version tag, and publishes
+`@dpeek/codeless`. It intentionally does not push the commit or tag.
+
+For non-interactive local publishing, create an npm granular access token with
+read/write access to `@dpeek/codeless` (or the `@dpeek` scope) and **Bypass 2FA**
+enabled. Put the token in the repository's ignored `.env` file:
+
+```sh
+NPM_TOKEN=npm_your_token_here
+```
+
+Reference that variable from your user-level `~/.npmrc`:
+
+```ini
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+```
+
+`bun run release` loads `.env` and passes the token to npm. Never put the token
+directly in a committed `.npmrc` or source file. If npm package settings disallow
+tokens, publishing will still require an OTP. For hosted CI, prefer npm trusted
+publishing instead of a long-lived token.
 
 Keep source, tests, executable, extension, and dependencies inside this project.
 Keep project policies and real prompts outside it. Add automation only for

package/extension/implementer-reporting.js

@@ -0,0 +1,215 @@
+import { existsSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+
+function text(message) {
+  if (message?.role !== "assistant" || !Array.isArray(message.content)) return undefined;
+  const value = message.content
+    .filter((part) => part?.type === "text" && typeof part.text === "string")
+    .map((part) => part.text)
+    .join("");
+  return value || undefined;
+}
+
+function validUsage(value) {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    ["input", "output", "cacheRead", "cacheWrite"].every(
+      (key) => Number.isFinite(value[key]) && value[key] >= 0,
+    )
+  );
+}
+
+function sessionUsage(entries) {
+  const usages = [];
+  for (const entry of entries) {
+    if (
+      entry?.type === "message" &&
+      (entry.message?.role === "assistant" || entry.message?.role === "toolResult") &&
+      validUsage(entry.message.usage)
+    )
+      usages.push(entry.message.usage);
+    if (
+      (entry?.type === "compaction" || entry?.type === "branch_summary") &&
+      validUsage(entry.usage)
+    )
+      usages.push(entry.usage);
+  }
+  if (usages.length === 0) return undefined;
+  const total = (key) => usages.reduce((sum, usage) => sum + usage[key], 0);
+  const costs = usages.map((usage) => usage.cost?.total);
+  return {
+    input: total("input"),
+    output: total("output"),
+    cacheRead: total("cacheRead"),
+    cacheWrite: total("cacheWrite"),
+    ...(costs.every((cost) => Number.isFinite(cost) && cost >= 0)
+      ? {
+          cost: {
+            amount: costs.reduce((sum, cost) => sum + cost, 0),
+            currency: "USD",
+            source: "pi-model-estimate",
+          },
+        }
+      : {}),
+  };
+}
+
+function messages(entries) {
+  return entries
+    .filter((entry) => entry?.type === "message")
+    .map((entry) => entry.message)
+    .filter((message) => message?.role === "assistant" || message?.role === "toolResult");
+}
+
+function write(path, value) {
+  const temporary = `${path}.${process.pid}.${crypto.randomUUID()}`;
+  try {
+    writeFileSync(temporary, `${JSON.stringify(value)}\n`, { flag: "wx" });
+    renameSync(temporary, path);
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+
+export default function implementerReportingExtension(pi) {
+  pi.registerFlag("codeless-attempt", { type: "string" });
+  let configuration;
+  let startupScope;
+  let rearm;
+  let startedAt;
+  let entryOffset = 0;
+  let toolCalls = 0;
+  let errorCount = 0;
+
+  function configure(value, offset = 0) {
+    if (
+      typeof value?.path !== "string" ||
+      typeof value?.id !== "string" ||
+      typeof value?.stream !== "string" ||
+      typeof value?.change !== "string" ||
+      !["initial", "rework"].includes(value?.kind)
+    )
+      throw new Error("Codeless attempt configuration is invalid");
+    return { value, offset };
+  }
+  pi.on("session_start", () => {
+    try {
+      const value = JSON.parse(pi.getFlag("codeless-attempt") ?? "");
+      configuration = configure(value).value;
+      startupScope = { stream: configuration.stream, change: configuration.change };
+    } catch {}
+  });
+  function requireScope(value) {
+    if (
+      startupScope === undefined ||
+      value?.stream !== startupScope.stream ||
+      value?.change !== startupScope.change
+    )
+      throw new Error("Codeless stream/change scope does not match this implementer session");
+  }
+
+  pi.registerCommand("codeless-rework", {
+    description: "Submit one scope-verified Codeless implementer rework turn",
+    handler: async (args, ctx) => {
+      let value;
+      try {
+        value = JSON.parse(args);
+      } catch {
+        throw new Error("Codeless rework requires one JSON-quoted request");
+      }
+      requireScope(value);
+      if (typeof value?.feedback !== "string" || value.feedback.trim().length === 0)
+        throw new Error("Codeless rework requires concise non-empty feedback");
+      const next = configure(value, ctx.sessionManager.getEntries().length);
+      if (next.value.kind !== "rework") throw new Error("Codeless rework attempt must be rework");
+      configuration = undefined;
+      rearm = next;
+      try {
+        pi.sendUserMessage(`Review feedback: ${value.feedback.trim()}`, { deliverAs: "followUp" });
+      } catch (error) {
+        rearm = undefined;
+        throw error;
+      }
+    },
+  });
+
+  pi.registerCommand("codeless-finish", {
+    description: "Gracefully finish a scope-verified Codeless implementer",
+    handler: async (args, ctx) => {
+      let value;
+      try {
+        value = JSON.parse(args);
+      } catch {
+        throw new Error("Codeless finish requires one JSON-quoted scope");
+      }
+      requireScope(value);
+      await ctx.shutdown();
+    },
+  });
+  pi.on("agent_start", () => {
+    if (rearm !== undefined) {
+      configuration = rearm.value;
+      entryOffset = rearm.offset;
+      rearm = undefined;
+      startedAt = new Date().toISOString();
+      toolCalls = 0;
+      errorCount = 0;
+    } else {
+      startedAt ??= new Date().toISOString();
+    }
+  });
+  pi.on("tool_execution_end", (event) => {
+    toolCalls += 1;
+    if (event.isError) errorCount += 1;
+  });
+  pi.on("agent_settled", (_event, ctx) => {
+    if (configuration === undefined) return;
+    const report = configuration;
+    configuration = undefined;
+    const entries = ctx.sessionManager.getEntries().slice(entryOffset);
+    const settledMessages = messages(entries);
+    const final = [...settledMessages].reverse().find((message) => message.role === "assistant");
+    const totals = sessionUsage(entries);
+    const model = final?.responseModel ?? final?.model ?? ctx.model?.id;
+    const provider = final?.provider ?? ctx.model?.provider;
+    const selection =
+      typeof provider === "string" &&
+      typeof model === "string" &&
+      typeof pi.getThinkingLevel() === "string"
+        ? { provider, model, thinking: pi.getThinkingLevel() }
+        : undefined;
+    const finalText = text(final);
+    const complete =
+      selection !== undefined &&
+      typeof final?.stopReason === "string" &&
+      final.stopReason.length > 0 &&
+      finalText !== undefined &&
+      totals !== undefined;
+    write(report.path, {
+      id: report.id,
+      stream: report.stream,
+      change: report.change,
+      role: "implementer",
+      kind: report.kind,
+      startedAt: startedAt ?? new Date().toISOString(),
+      endedAt: new Date().toISOString(),
+      ...(selection === undefined ? {} : { selection }),
+      outcome: final?.stopReason ?? "unknown",
+      ...(finalText === undefined ? {} : { text: finalText }),
+      ...(totals === undefined
+        ? {}
+        : {
+            usage: {
+              input: totals.input,
+              output: totals.output,
+              cacheRead: totals.cacheRead,
+              cacheWrite: totals.cacheWrite,
+            },
+            ...(totals.cost === undefined ? {} : { cost: totals.cost }),
+          }),
+      toolCalls,
+      errorCount,
+      incomplete: !complete,
+    });
+  });
+}

package/extension/planner.js

@@ -1,10 +1,13 @@
 import { fileURLToPath } from "node:url";
+import { validAttempt } from "../src/attempt.ts";
 
 const codeless = fileURLToPath(new URL("../bin/codeless", import.meta.url));
 const thinkingLevels = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 const requiredTools = [
   "approve_stream_change",
   "dispatch_stream_implementer",
+  "rework_stream_implementer",
+  "finish_stream_implementer",
   "next_stream_change",
 ];
 
@@ -289,6 +292,98 @@ export default function plannerExtension(pi) {
       },
     });
 
+    pi.registerTool({
+      name: "rework_stream_implementer",
+      label: "Remediate stream implementation",
+      description:
+        "Reuse the idle implementer for this approved change, submit one actionable feedback turn, collect its rework attempt, and queue review again.",
+      promptSnippet: "Send one concise remediation request to the existing stream implementer",
+      promptGuidelines: [
+        "Call rework_stream_implementer only when review finds actionable defects in the approved change. Use its approved changePath and concise feedback; never reproduce Herdr commands.",
+        "The tool queues review only after a settled rework attempt. Stop on any error and do not retry automatically.",
+      ],
+      parameters: {
+        type: "object",
+        properties: {
+          changePath: {
+            type: "string",
+            description: "Absolute path to the approved changes/NNN.md file",
+          },
+          feedback: { type: "string", description: "Concise actionable review feedback" },
+        },
+        required: ["changePath", "feedback"],
+        additionalProperties: false,
+      },
+      async execute(_toolCallId, params, signal) {
+        const changePath = params.changePath.replace(/^@/, "");
+        const execution = await pi.exec("bun", [codeless, "rework", changePath, params.feedback], {
+          signal,
+          timeout: 3_700_000,
+        });
+        const output = [execution.stdout.trim(), execution.stderr.trim()]
+          .filter(Boolean)
+          .join("\n");
+        if (execution.code !== 0)
+          throw new Error(output || `codeless rework failed with exit code ${execution.code}`);
+        let attempt;
+        try {
+          attempt = JSON.parse(execution.stdout);
+        } catch {
+          throw new Error("Codeless returned an invalid rework attempt");
+        }
+        if (!validAttempt(attempt, attempt?.stream, attempt?.change) || attempt.kind !== "rework")
+          throw new Error("Codeless returned an invalid rework attempt");
+        pi.sendUserMessage(`/review ${JSON.stringify(changePath)}`, {
+          deliverAs: "steer",
+          expandPromptTemplates: true,
+        });
+        return {
+          content: [{ type: "text", text: attempt.text || "Implementer rework settled." }],
+          details: { changePath, attempt },
+        };
+      },
+    });
+
+    pi.registerTool({
+      name: "finish_stream_implementer",
+      label: "Finish stream implementer",
+      description:
+        "Gracefully exit the verified idle implementer after review approval and confirm its right-hand pane returned to the stream shell.",
+      promptSnippet: "Finish the approved stream implementer before commit and landing",
+      promptGuidelines: [
+        "Call finish_stream_implementer exactly once after recording review approval and before following commit-and-land instructions.",
+        "Stop on failure; do not use Herdr commands or continue to commit and land.",
+      ],
+      parameters: {
+        type: "object",
+        properties: {
+          changePath: {
+            type: "string",
+            description: "Absolute path to the approved changes/NNN.md file",
+          },
+        },
+        required: ["changePath"],
+        additionalProperties: false,
+      },
+      async execute(_toolCallId, params, signal) {
+        const changePath = params.changePath.replace(/^@/, "");
+        const execution = await pi.exec("bun", [codeless, "finish", changePath], {
+          signal,
+          timeout: 35_000,
+        });
+        const output = [execution.stdout.trim(), execution.stderr.trim()]
+          .filter(Boolean)
+          .join("\n");
+        if (execution.code !== 0)
+          throw new Error(output || `codeless finish failed with exit code ${execution.code}`);
+        return {
+          content: [
+            { type: "text", text: "Implementer exited and its pane returned to the stream shell." },
+          ],
+        };
+      },
+    });
+
     pi.registerTool({
       name: "dispatch_stream_implementer",
       label: "Dispatch stream implementer",
@@ -322,13 +417,22 @@ export default function plannerExtension(pi) {
         if (execution.code !== 0) {
           throw new Error(output || `codeless dispatch failed with exit code ${execution.code}`);
         }
+        let attempt;
+        try {
+          attempt = JSON.parse(execution.stdout);
+        } catch {
+          throw new Error("Codeless returned an invalid implementer attempt");
+        }
+        if (!validAttempt(attempt, attempt?.stream, attempt?.change)) {
+          throw new Error("Codeless returned an invalid implementer attempt");
+        }
         pi.sendUserMessage(`/review ${JSON.stringify(changePath)}`, {
           deliverAs: "steer",
           expandPromptTemplates: true,
         });
         return {
-          content: [{ type: "text", text: output || "Implementer settled." }],
-          details: { changePath },
+          content: [{ type: "text", text: attempt.text || "Implementer settled." }],
+          details: { changePath, attempt },
         };
       },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpeek/codeless",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "An attended planner and implementer workflow for parallel capability development",
   "homepage": "https://github.com/dpeek/codeless#readme",
   "bugs": {
@@ -27,7 +27,7 @@
   },
   "scripts": {
     "check": "oxfmt --config .oxfmtrc.json --write . && oxlint --config .oxlintrc.json --fix --type-aware --type-check . && bun run test",
-    "prepublishOnly": "bun run check",
+    "release": "bun ./scripts/release.ts",
     "test": "bun test ./test --dots"
   },
   "dependencies": {

package/spec/workflow.md

@@ -49,6 +49,18 @@ Git-ignored, and every linked worktree resolves the same primary-checkout state:
   metrics/<slug>/NNN.json
 ```
 
+`codeless init` is the explicit, idempotent bootstrap for a configured project.
+It requires the configured integration branch to exist and creates the shared
+state directories plus that branch's worktree only at
+`<workspace>/worktree/<integration-branch>`. It reuses only the exact registered
+canonical checkout. An occupied target, a branch registered elsewhere, invalid
+checkout, or ambiguous Git registration stops unchanged; init never switches
+branches, moves worktrees, or repairs conflicts. With the default workspace,
+it accepts a repository ignore rule only when it ignores the state path without
+covering configuration or configured prompts, otherwise appending the narrow
+`/.codeless/state/` rule. An absolute workspace never changes repository
+ignores. No other command bootstraps this layout.
+
 `planner.md` owns decisions, approvals, review outcomes, landing history, and
 the context needed by a fresh planner. `change.md` is the editable current
 proposal. `changes/NNN.md` is the immutable-by-policy approved input to one
@@ -91,8 +103,8 @@ post-landing replacement—uses the package-owned extension as its activation
 boundary. Before its first project prompt, activation requires the exact
 `<slug>-planner` Pi session name, establishes and verifies Herdr reports
 `<slug-with-hyphens-replaced>_planner`, and verifies
-`approve_stream_change`, `dispatch_stream_implementer`, and
-`next_stream_change` are active. Missing or incompatible activation, identity
+`approve_stream_change`, `dispatch_stream_implementer`, `rework_stream_implementer`,
+`finish_stream_implementer`, and `next_stream_change` are active. Missing or incompatible activation, identity
 mismatch, or an incomplete tool set stops visibly before `/change`. A direct
 restart may begin with Herdr's `pi` fallback identity; activation renames and
 rereads only that fallback. Any other identity mismatch stops. Implementers use
@@ -108,18 +120,41 @@ right-hand Herdr pane only when that pane is an available shell or the expected
 idle implementer, starts a fresh ephemeral Pi implementer in the stream
 worktree, submits `/implement`, and waits for at most one hour.
 
-Successful dispatch queues the expanded `/review` prompt back into the planner.
+Successful dispatch loads the package-owned reporting extension while retaining
+`--no-session` and passes its report configuration through that extension's
+explicit Pi string flag, then returns one normalized attempt to the planner tool
+before it queues the expanded `/review` prompt. Attempts have a stable ID and
+capture only stream/change/role, start and settlement timestamps, Pi's actual
+settled provider/model/thinking selection, terminal outcome and final text,
+full-session Pi input/output/cache usage (including tool results, compaction,
+and branch summaries), available Pi model cost estimate with USD currency and
+source, and tool/error counts. Cost is omitted when Pi did not supply valid
+cost totals. They do not retain prompts, source, credentials, thinking, or a
+transcript. The extension writes its narrow report atomically once, then
+remains disarmed for remediation; Codeless atomically deduplicates it inside the
+per-change metric record, rejecting a
+conflicting duplicate ID. Missing, malformed, or unwritable collection warns
+and yields an explicitly incomplete attempt when possible without failing or
+repeating a settled implementation.
+
 The planner inspects the full diff and relevant code, checks the approved
 acceptance criteria, and runs focused checks when the implementation output is
-insufficient. Remediation reuses the same implementer context. Once approved,
-the planner records the review result, exits the implementer so its pane returns
-to a shell, and follows the commit-and-land prompt without another approval
-round.
-
-Dispatch and remediation do not retry automatically. Dispatch currently exposes
-Herdr command output rather than a normalized implementation result, and
-remediation and implementer shutdown are still performed through prompt-owned
-Herdr commands.
+insufficient. The planner-only `rework_stream_implementer` tool accepts that
+approved path and concise feedback, verifies the expected idle implementer, its
+right-hand pane and worktree, then invokes one package-owned Pi command. That command
+verifies the immutable startup stream/change scope, arms package reporting in the existing
+conversation, and submits one bounded feedback turn. It records
+and returns one `rework` attempt before queueing review again; missing or malformed
+reports warn and yield an incomplete attempt after settlement. Prompt rejection,
+timeout, blocked state, identity/worktree/change mismatch, or ambiguous pane stops
+without a completed attempt or queued review. The separate planner-only
+`finish_stream_implementer` tool first verifies that immutable stream/change scope in the
+same idle implementer, then gracefully exits it and waits for its pane to become the
+stream-worktree shell. Its failure
+stops before commit or landing instructions continue.
+
+Dispatch, remediation, and shutdown do not retry automatically or replace an
+implementer session or its selected model.
 
 ## Commit and landing
 
@@ -162,21 +197,27 @@ before another implementation.
 ## Local workflow metrics
 
 The first dispatch for a stream and numbered change creates one atomic local
-metric record. Retrying dispatch preserves the original timestamp. Successful
-landing adds its timestamp and commit, or creates a landed record with
-unavailable elapsed time when dispatch collection was unavailable. Collection
-warnings do not change dispatch or landing outcomes.
-
-`codeless metrics` reports every recorded stream and a project total with:
-
-- landed and dispatched-but-unlanded change counts;
-- measured versus unavailable elapsed coverage; and
-- total and average dispatch-to-land wall-clock time.
-
-The measurements are prospective, local observations. They are not journal
-state, an approval source, or a recovery mechanism. Token usage, cost,
-normalized attempt results, review rework, and failure breakdowns are not yet
-collected.
+metric record. Every accepted dispatch creates a new attempt ID; re-ingesting an
+attempt ID is atomic and idempotent, while the original dispatch timestamp stays
+unchanged. Successful landing adds its timestamp and commit, or creates a landed
+record with unavailable elapsed time when dispatch collection was unavailable.
+Collection warnings do not change dispatch or landing outcomes.
+
+`codeless metrics` reports every recorded stream and a project total in two
+tables. The elapsed table reports landed and dispatched-but-unlanded change
+counts, measured versus unavailable elapsed coverage, and total and average
+dispatch-to-land wall-clock time. The attempt table aggregates only validated
+canonical attempt records and reports distinct changes with rework, initial and
+rework turns, incomplete collection, exact stored terminal-outcome labels, and
+summed tool errors.
+
+Usage coverage is measured versus unavailable attempts; input, output,
+cache-read, and cache-write totals include only attempts with recorded usage.
+Cost coverage follows the same rule, and totals are grouped by recorded currency
+without conversion. Missing usage or cost is unavailable, never zero. These
+measurements do not establish implementation quality or review success. They
+are prospective local observations, not journal state, an approval source, or a
+recovery mechanism.
 
 ## Limits