Skip to content

DataArt/artisyn-implementation-harness / skills/implementation-harness

implementation-harness

Flagged

Install the portable AI-dev harness, rebuild its operational graph standalone, harvest project skill improvements into its canonical templates, package direct canonical edits into a portable bundle, or apply canonical updates to an existing project. Use /implementation-harness launch, /implementation-harness reindex-graph, or /implementation-harness patch harvest|prepare|apply.

FileKindSize
CHANGELOG.mdmarkdown37.5 KB
README.mdmarkdown13.7 KB
SKILL.mdskill md9.6 KB
bin/artisyn-implementation-harness.mjsexecutablescript11.8 KB
bin/lib/placer.mjsscript2.6 KB
bin/lib/providers.mjsscript1.8 KB
bin/lib/reporter.mjsscript3.0 KB
bin/lib/zip.mjsscript4.0 KB
canonical/adaptors/claude/browser.mdmarkdown2.5 KB
canonical/adaptors/claude/context.mdmarkdown517 B
canonical/adaptors/claude/credentials.mdmarkdown512 B
canonical/adaptors/claude/delegation.mdmarkdown910 B
canonical/adaptors/claude/interaction.mdmarkdown359 B
canonical/adaptors/claude/planning.mdmarkdown745 B
canonical/adaptors/claude/review.mdmarkdown1.0 KB
canonical/adaptors/claude/task-tracking.mdmarkdown897 B
canonical/adaptors/codex/browser.mdmarkdown1.0 KB
canonical/adaptors/codex/context.mdmarkdown517 B
canonical/adaptors/codex/credentials.mdmarkdown480 B
canonical/adaptors/codex/delegation.mdmarkdown910 B
canonical/adaptors/codex/interaction.mdmarkdown359 B
canonical/adaptors/codex/planning.mdmarkdown904 B
canonical/adaptors/codex/review.mdmarkdown973 B
canonical/adaptors/codex/task-tracking.mdmarkdown1.1 KB
canonical/adaptors/copilot/browser.mdmarkdown620 B
canonical/adaptors/copilot/context.mdmarkdown881 B
canonical/adaptors/copilot/credentials.mdmarkdown992 B
canonical/adaptors/copilot/delegation.mdmarkdown1.2 KB
canonical/adaptors/copilot/interaction.mdmarkdown454 B
canonical/adaptors/copilot/planning.mdmarkdown785 B
canonical/adaptors/copilot/review.mdmarkdown791 B
canonical/adaptors/copilot/task-tracking.mdmarkdown723 B
canonical/agents/architect/INTENT.mdmarkdown2.4 KB
canonical/agents/architect/TEMPLATE.mdmarkdown6.5 KB
canonical/agents/docs-writer/INTENT.mdmarkdown2.2 KB
canonical/agents/docs-writer/TEMPLATE.mdmarkdown2.8 KB
canonical/agents/infra/INTENT.mdmarkdown2.1 KB
canonical/agents/infra/TEMPLATE.mdmarkdown5.1 KB
canonical/agents/layer/INTENT.mdmarkdown6.0 KB
canonical/agents/layer/TEMPLATE.mdmarkdown1.5 KB
canonical/agents/onboarding/INTENT.mdmarkdown5.3 KB
canonical/agents/onboarding/TEMPLATE.mdmarkdown4.2 KB
canonical/agents/product-architect/INTENT.mdmarkdown7.5 KB
canonical/agents/product-architect/TEMPLATE.mdmarkdown3.9 KB
canonical/agents/scrum-master/INTENT.mdmarkdown10.9 KB
canonical/agents/scrum-master/TEMPLATE.mdmarkdown12.3 KB
canonical/docs/.og/cli.mjsscript13.6 KB
canonical/docs/.og/cli.test.mjsscript19.6 KB
canonical/docs/.og/constants.mjsscript2.9 KB
canonical/docs/.og/docs-operational-graph.sqlitebinary24.0 KB
canonical/docs/.og/docs.mjsscript5.5 KB
canonical/docs/.og/edges.mjsscript5.8 KB
canonical/docs/.og/schema.mjsscript741 B
canonical/docs/.og/utils.mjsscript5.2 KB
canonical/docs/Engineering Guide/01 Conventions.mdmarkdown3.0 KB
canonical/docs/Engineering Guide/03 Engineer Role.mdmarkdown2.6 KB
canonical/docs/Engineering Guide/04 AI Coding Tool Compatibility.mdmarkdown3.6 KB
canonical/docs/Engineering Guide/05 MCP Setup.mdmarkdown6.6 KB
canonical/docs/Engineering Guide/Documentation/01 Principles.mdmarkdown15.3 KB
canonical/docs/Engineering Guide/Documentation/02 Structure.mdmarkdown3.8 KB
canonical/docs/Engineering Guide/Documentation/03 HLD Intent.mdmarkdown8.1 KB
canonical/docs/Engineering Guide/Documentation/04 LLD Intent.mdmarkdown9.7 KB
canonical/docs/Engineering Guide/Documentation/05 NFR Intent.mdmarkdown6.0 KB
canonical/docs/Engineering Guide/Documentation/07 Terminology.mdmarkdown1.4 KB
canonical/docs/Engineering Guide/Lifecycles/00 Overview.mdmarkdown5.8 KB
canonical/docs/Engineering Guide/Lifecycles/01 Dev Lifecycle.mdmarkdown19.9 KB
canonical/docs/Engineering Guide/Lifecycles/02 Design Lifecycle.mdmarkdown29.4 KB
canonical/docs/Engineering Guide/Lifecycles/03 Evolve Lifecycle.mdmarkdown7.0 KB
canonical/docs/Engineering Guide/Lifecycles/04 Architecture Lifecycle.mdmarkdown3.6 KB
canonical/docs/Engineering Guide/Lifecycles/05 Documents Flow.mdmarkdown9.5 KB
canonical/manifest.jsonconfig1.6 KB
canonical/mcp.jsonconfig23 B
canonical/root-instructions/INTERFACE.mdmarkdown3.3 KB
canonical/settings.jsonconfig332 B
canonical/skills/design/INTENT.mdmarkdown28.6 KB
canonical/skills/design/TEMPLATE.mdmarkdown19.0 KB
canonical/skills/design/interfaces/architecture.mdmarkdown2.8 KB
canonical/skills/design/interfaces/contract.mdmarkdown7.4 KB
canonical/skills/design/interfaces/design.mdmarkdown2.3 KB
canonical/skills/design/interfaces/efforts.mdmarkdown2.5 KB
canonical/skills/design/interfaces/stack.mdmarkdown1.6 KB
canonical/skills/design/patterns/announce-progress.mdmarkdown997 B
canonical/skills/design/patterns/approval-intelligent.mdmarkdown1.5 KB
canonical/skills/design/patterns/approval-sign-off.mdmarkdown2.4 KB
canonical/skills/design/patterns/context-resolution.mdmarkdown6.6 KB
canonical/skills/design/patterns/design-architect-review.mdmarkdown2.4 KB
canonical/skills/design/patterns/design-oq-triage.mdmarkdown3.8 KB
canonical/skills/design/patterns/design-quality-gate.mdmarkdown1.4 KB
canonical/skills/design/patterns/do-report-commit.mdmarkdown1.2 KB
canonical/skills/design/patterns/docs-writer-authoring.mdmarkdown3.6 KB
canonical/skills/design/patterns/metrics.mdmarkdown11.9 KB
canonical/skills/design/patterns/multi-decision-split.mdmarkdown3.6 KB
canonical/skills/design/patterns/phase-sign-off.mdmarkdown2.4 KB
canonical/skills/design/patterns/satellite-review.mdmarkdown1.5 KB
canonical/skills/design/patterns/session-continuity.mdmarkdown827 B
canonical/skills/design/patterns/task-tracking.mdmarkdown779 B
canonical/skills/design/patterns/waf-review.mdmarkdown4.2 KB
canonical/skills/design/patterns/write-confirm.mdmarkdown963 B
canonical/skills/design/references/00-decision-router.mdmarkdown3.8 KB
canonical/skills/design/references/00-router.mdmarkdown4.6 KB
canonical/skills/design/references/01-context-gathering.mdmarkdown8.1 KB
canonical/skills/design/references/02-ceremony.mdmarkdown4.6 KB
canonical/skills/design/references/03-frame.mdmarkdown6.7 KB
canonical/skills/design/references/04-research.mdmarkdown8.1 KB
canonical/skills/design/references/05-evaluate.mdmarkdown9.0 KB
canonical/skills/design/references/06-solution.mdmarkdown13.7 KB
canonical/skills/design/references/07-review-gate.mdmarkdown4.1 KB
canonical/skills/design/references/08-address-feedback.mdmarkdown8.0 KB
canonical/skills/design/references/09-publish.mdmarkdown8.9 KB
canonical/skills/design/references/10-completion.mdmarkdown7.4 KB
canonical/skills/design/scripts/constants.mjsscript2.0 KB
canonical/skills/design/scripts/design-metrics.mjsscript35.4 KB
canonical/skills/design/scripts/design-metrics.test.mjsscript12.0 KB
canonical/skills/design/scripts/utils.mjsscript3.1 KB
canonical/skills/design/templates/evaluate.mdmarkdown1.4 KB
canonical/skills/design/templates/frame.mdmarkdown2.6 KB
canonical/skills/design/templates/report.mdmarkdown4.8 KB
canonical/skills/design/templates/research.mdmarkdown2.4 KB
canonical/skills/design/templates/stat.jsonconfig1.7 KB
canonical/skills/design/templates/stat.schema.jsonconfig17.1 KB
canonical/skills/dev/INTENT.mdmarkdown15.9 KB
canonical/skills/dev/TEMPLATE.mdmarkdown9.0 KB
canonical/skills/dev/interfaces/intent.mdmarkdown2.6 KB
canonical/skills/dev/patterns/announce-progress.mdmarkdown1.1 KB
canonical/skills/dev/patterns/approval-intelligent.mdmarkdown1.5 KB
canonical/skills/dev/patterns/approval-sign-off.mdmarkdown1.9 KB
canonical/skills/dev/patterns/do-report-commit.mdmarkdown888 B
canonical/skills/dev/patterns/metrics.mdmarkdown17.7 KB
canonical/skills/dev/patterns/phase-sign-off.mdmarkdown2.2 KB
canonical/skills/dev/patterns/review-gate.mdmarkdown3.6 KB
canonical/skills/dev/patterns/satellite-review.mdmarkdown3.1 KB
canonical/skills/dev/patterns/session-continuity.mdmarkdown797 B
canonical/skills/dev/patterns/task-tracking.mdmarkdown766 B
canonical/skills/dev/patterns/write-confirm.mdmarkdown615 B
canonical/skills/dev/references/00-router.mdmarkdown2.2 KB
canonical/skills/dev/references/01-context-gathering.mdmarkdown10.3 KB
canonical/skills/dev/references/02-ceremony.mdmarkdown4.5 KB
canonical/skills/dev/references/03-plan.mdmarkdown14.2 KB
canonical/skills/dev/references/04-implement.mdmarkdown11.7 KB
canonical/skills/dev/references/05-test.mdmarkdown7.8 KB
canonical/skills/dev/references/06-document.mdmarkdown11.7 KB
canonical/skills/dev/references/07-completion.mdmarkdown6.3 KB
canonical/skills/dev/scripts/constants.mjsscript3.2 KB
canonical/skills/dev/scripts/quality.mjsscript9.1 KB
canonical/skills/dev/scripts/quality.test.mjsscript6.6 KB
canonical/skills/dev/scripts/timing.mjsscript38.1 KB
canonical/skills/dev/scripts/timing.test.mjsscript21.0 KB
canonical/skills/dev/scripts/utils.mjsscript3.1 KB
canonical/skills/dev/templates/plan.mdmarkdown3.3 KB
canonical/skills/dev/templates/report.mdmarkdown6.4 KB
canonical/skills/dev/templates/stat.jsonconfig1.4 KB
canonical/skills/dev/templates/stat.schema.jsonconfig29.3 KB
canonical/skills/evolve/INTENT.mdmarkdown1.6 KB
canonical/skills/evolve/TEMPLATE.mdmarkdown1.3 KB
canonical/skills/evolve/interfaces/improvement.mdmarkdown1.2 KB
canonical/skills/evolve/interfaces/reflection.mdmarkdown353 B
canonical/skills/evolve/interfaces/validation.mdmarkdown653 B
canonical/skills/evolve/patterns/task-tracking.mdmarkdown787 B
canonical/skills/evolve/references/00-router.mdmarkdown1.1 KB
canonical/skills/evolve/references/01-reflect.mdmarkdown805 B
canonical/skills/evolve/references/02-triage.mdmarkdown2.6 KB
canonical/skills/evolve/references/03-draft.mdmarkdown1.2 KB
canonical/skills/evolve/references/04-validate.mdmarkdown1.5 KB
canonical/skills/evolve/references/05-adopt.mdmarkdown1.5 KB
canonical/skills/war/INTENT.mdmarkdown4.5 KB
canonical/skills/war/TEMPLATE.mdmarkdown1.8 KB
canonical/skills/war/patterns/present-and-save.mdmarkdown1.0 KB
canonical/skills/war/patterns/scope-resolution.mdmarkdown830 B
canonical/skills/war/references/01-design.mdmarkdown3.4 KB
canonical/skills/war/references/02-implementation.mdmarkdown3.8 KB
canonical/skills/war/templates/design-report.mdmarkdown869 B
canonical/skills/war/templates/implementation-report.mdmarkdown1.8 KB
canonical/skills/where-we-are/INTENT.mdmarkdown3.3 KB
canonical/skills/where-we-are/TEMPLATE.mdmarkdown6.3 KB
canonical/skills/where-we-are/report-template.mdmarkdown2.0 KB
canonical/skills/x-ray/INTENT.mdmarkdown2.4 KB
canonical/skills/x-ray/TEMPLATE.mdmarkdown10.5 KB
implementation-harness.mdmarkdown1.4 KB
package.jsonmanifest696 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/CHANGELOG.md.patchother1.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/README.md.patchother1.9 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/SKILL.md.patchother2.5 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/agents/docs-writer/INTENT.md.patchother1.4 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/docs/.og/cli.test.mjs.patchother846 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/docs/Engineering Guide/04 AI Coding Tool Compatibility.md.patchother3.4 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/docs/Engineering Guide/05 MCP Setup.md.patchother5.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/manifest.json.patchother662 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/settings.json.patchother150 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/skills/design/INTENT.md.patchother19.4 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/patterns/skill-authoring.md.patchother692 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/host-capabilities.md.patchother1.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/01-launch.md.patchother1.1 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/01a-launch-plan.md.patchother1.6 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/01b-launch-install.md.patchother7.3 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/02-launch-questions.md.patchother5.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/08-provider-launch.md.patchother3.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/patch/04-patch-harvest.md.patchother2.6 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/patch/05-patch-apply.md.patchother3.0 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/patch/06-patch-state.md.patchother7.1 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/scripts/lib/agent-format.mjs.patchother2.2 KB

canonical/skills/dev/scripts/timing.mjs

View on GitHub
#!/usr/bin/env node
// Self-contained dev metrics recorder: stage/step timing, checks, and the generated
// Stage/Step Metrics report sections. Review-findings/tests/debt derivation lives in
// the sibling quality.mjs; shared constants and generic helpers are their own files.
import fs from 'node:fs';
import path from 'node:path';
import { randomUUID } from 'node:crypto';
import { spawn } from 'node:child_process';
import { parseArgs } from 'node:util';

import {
  LIFECYCLE,
  STAGES,
  FINAL_STAGE,
  FILES,
  STAGE_REPORT_MARKERS,
  STEP_REPORT_MARKERS,
  LEGACY_REPORT_MARKERS,
  ACTIVITIES_BY_STAGE,
  ACTIVITIES,
  REASONS,
  TRIGGERS,
} from './constants.mjs';
import {
  fail,
  need,
  member,
  utc,
  stamp,
  seconds,
  last,
  atomic,
  escapeMarkdownCell,
  humanDuration,
} from './utils.mjs';
import { deriveQuality, qualitySummary } from './quality.mjs';

const names = [
  'dir',
  'ticket',
  'coverage',
  'stage',
  'id',
  'title',
  'order',
  'plan-ref',
  'depends-on',
  'activity',
  'reason',
  'detail',
  'kind',
  'name',
  'result',
  'evidence',
  'source',
  'file',
  'created-at',
  'author',
];
const argv = process.argv.slice(2);
const separator = argv.indexOf('--');
const command = separator < 0 ? [] : argv.slice(separator + 1);
const { values: o, positionals: words } = parseArgs({
  args: separator < 0 ? argv : argv.slice(0, separator),
  allowPositionals: true,
  options: Object.fromEntries(names.map((name) => [name, { type: 'string' }])),
});
const [noun, verb] = words;
let lock, dir, data;
let child;
let caughtSignal = null;
const signalHandler = (signal) => {
  caughtSignal = signal;
  child?.kill(signal);
};

/**
 * Enforce every structural invariant of a stat.json document.
 * Throws on the first violation; never mutates the document.
 * @param {object} d Parsed stat.json contents.
 */
function validateState(d) {
  need(
    (d.lifecycle ?? LIFECYCLE) === LIFECYCLE,
    'Metrics belong to a different lifecycle; use its own directory and CLI'
  );
  need(
    d.schema_version === 2,
    'Unsupported schema_version; preserve old data and migrate explicitly'
  );
  for (const key of ['stages', 'steps', 'intervals', 'checks', 'usage_samples'])
    need(Array.isArray(d[key]), `Missing ${key}`);
  need(stamp(d.tracking_started_at), 'Missing tracking start');
  need(
    d.ticket && ['from_tracking_start', 'partial'].includes(d.coverage),
    'Invalid ticket/coverage'
  );
  const ids = new Set();
  const unique = (id) => {
    need(typeof id === 'string' && id && !ids.has(id), `Invalid/duplicate ID: ${id}`);
    ids.add(id);
  };
  const attempts = new Map();
  const units = [...d.stages, ...d.steps];
  for (const unit of units) {
    unique(unit.id);
    member(unit.status, ['pending', 'active', 'waiting', 'completed']);
    need(Array.isArray(unit.attempts), 'Missing attempts');
    for (const attempt of unit.attempts) {
      unique(attempt.id);
      attempts.set(attempt.id, unit);
      need(
        stamp(attempt.started_at) &&
          (attempt.ended_at === null ||
            (stamp(attempt.ended_at) && seconds(attempt.started_at, attempt.ended_at) >= 0)),
        'Invalid attempt timestamps'
      );
      member(attempt.trigger, ['initial', ...TRIGGERS]);
      member(attempt.outcome, [null, 'completed', 'superseded']);
    }
  }
  for (const stage of d.stages) member(stage.id, STAGES);
  for (const step of d.steps) {
    need(
      Number.isInteger(step.order) && step.order >= 0 && step.title && step.plan_ref,
      'Invalid step definition'
    );
    need(
      Array.isArray(step.depends_on) &&
        step.depends_on.every((id) => id !== step.id && d.steps.some((s) => s.id === id)),
      'Invalid step dependencies'
    );
  }
  const refs = (record) => {
    need(
      d.stages.some((s) => s.id === record.stage_id && attempts.get(record.stage_attempt_id) === s),
      'Invalid stage attempt reference'
    );
    if (record.step)
      need(
        d.steps.some((s) => s.id === record.step.id && attempts.get(record.step.attempt_id) === s),
        'Invalid step attempt reference'
      );
  };
  let end = -Infinity;
  for (const interval of d.intervals) {
    unique(interval.id);
    refs(interval);
    need(
      stamp(interval.started_at) &&
        stamp(interval.last_observed_at) &&
        seconds(interval.started_at, interval.last_observed_at) >= 0,
      'Invalid interval checkpoint'
    );
    need(Date.parse(interval.started_at) >= end, 'Overlapping intervals');
    if (interval.ended_at !== null)
      need(
        stamp(interval.ended_at) && seconds(interval.last_observed_at, interval.ended_at) >= 0,
        'Invalid interval end'
      );
    member(interval.kind, ['work', 'wait']);
    member(
      interval.kind === 'work' ? interval.activity : interval.reason,
      interval.kind === 'work' ? ACTIVITIES : REASONS
    );
    need(seconds(d.tracking_started_at, interval.started_at) >= 0, 'Interval predates tracking');
    end = interval.ended_at === null ? Infinity : Date.parse(interval.ended_at);
  }
  for (const check of d.checks) {
    unique(check.id);
    refs(check);
    member(check.kind, ['build', 'test', 'lint', 'typecheck', 'acceptance']);
    member(check.result, ['running', 'passed', 'failed', 'error', 'cancelled', 'interrupted']);
    need(stamp(check.started_at), 'Invalid check start');
    if (check.result === 'running') {
      need(
        check.ended_at === null &&
          check.source === 'command' &&
          check.exit_code === null &&
          check.signal === null,
        'Invalid running check'
      );
      need(stamp(check.last_observed_at), 'Running check needs a checkpoint');
    } else
      need(
        stamp(check.ended_at) && seconds(check.started_at, check.ended_at) >= 0,
        'Invalid check end'
      );
    if (check.last_observed_at !== undefined)
      need(
        stamp(check.last_observed_at) &&
          seconds(check.started_at, check.last_observed_at) >= 0 &&
          (check.ended_at === null || seconds(check.last_observed_at, check.ended_at) >= 0),
        'Invalid check checkpoint'
      );
    need(check.name && check.evidence_ref && check.source, 'Missing check name/evidence/source');
    need(check.exit_code === null || Number.isInteger(check.exit_code), 'Invalid exit code');
    need(check.signal === null || typeof check.signal === 'string', 'Invalid signal');
  }
  const samples = new Set();
  for (const sample of d.usage_samples) {
    need(
      sample.sample_id &&
        sample.source &&
        sample.session_id &&
        sample.scope === 'ticket' &&
        sample.measurement === 'delta',
      'Usage requires ticket-scoped, non-overlapping runtime deltas'
    );
    const key = JSON.stringify([sample.source, sample.session_id, sample.sample_id]);
    need(!samples.has(key), 'Duplicate usage sample');
    samples.add(key);
    for (const key of ['input_tokens', 'output_tokens'])
      need(
        sample[key] === null || (Number.isSafeInteger(sample[key]) && sample[key] >= 0),
        `Invalid ${key}`
      );
  }
  for (const key of ['tracking_started_at', 'started_at', 'completed_at', 'ticket_created_at'])
    need(d[key] === null || stamp(d[key]), `Invalid ${key}`);
  if (d.ticket_created_at)
    need(
      d.ticket_created_source && seconds(d.ticket_created_at, d.tracking_started_at) >= 0,
      'Creation timestamp needs attribution and must not be in the future'
    );
  need(
    d.started_at === null || seconds(d.tracking_started_at, d.started_at) >= 0,
    'Work predates tracking'
  );
  if (d.completed_at)
    need(
      d.started_at && seconds(d.started_at, d.completed_at) >= 0,
      'Invalid completion timestamp'
    );
  need(
    d.stages.length === STAGES.length && STAGES.every((id) => d.stages.some((s) => s.id === id)),
    'Missing lifecycle stages'
  );
  for (const group of [d.stages, d.steps])
    need(
      group.filter((s) => ['active', 'waiting'].includes(s.status)).length <= 1,
      'Multiple active units'
    );
  for (const unit of units) {
    const running = unit.attempts.filter((a) => a.ended_at === null);
    need(
      running.length <= 1 && (running.length === 1) === ['active', 'waiting'].includes(unit.status),
      'Attempt/status mismatch'
    );
    if (unit.status === 'completed')
      need(last(unit)?.outcome === 'completed', 'Missing completed attempt');
  }
}

/**
 * Recalculate the derived metrics summary from the raw records.
 * @param {object} d Validated stat.json contents.
 * @param {string} now Current UTC timestamp.
 * @returns {object} Fresh `metrics` block; unknown telemetry stays null.
 */
function deriveMetrics(d, now) {
  const intervals = d.intervals.filter((i) => i.ended_at !== null);
  const sum = (predicate) =>
    intervals.filter(predicate).reduce((n, i) => n + seconds(i.started_at, i.ended_at), 0);
  const work = sum((i) => i.kind === 'work');
  const wait = sum((i) => i.kind === 'wait');
  const attempts = new Map(
    [...d.stages, ...d.steps].flatMap((s) => s.attempts.map((a) => [a.id, a]))
  );
  const checked = d.steps
    .map((s) =>
      d.checks.filter((c) => c.step?.id === s.id && ['passed', 'failed'].includes(c.result))
    )
    .filter((c) => c.length);
  const tokenSum = (key) =>
    d.usage_samples.some((s) => s[key] !== null)
      ? d.usage_samples.reduce((n, s) => n + (s[key] ?? 0), 0)
      : null;
  return {
    as_of: now,
    lead_time_seconds:
      d.completed_at && d.ticket_created_at ? seconds(d.ticket_created_at, d.completed_at) : null,
    cycle_time_seconds:
      d.completed_at && d.started_at ? seconds(d.started_at, d.completed_at) : null,
    observed_work_seconds: work,
    observed_wait_seconds: wait,
    open_work_seconds: d.intervals
      .filter((i) => i.ended_at === null && i.kind === 'work')
      .reduce((n, i) => n + seconds(i.started_at, i.last_observed_at), 0),
    open_wait_seconds: d.intervals
      .filter((i) => i.ended_at === null && i.kind === 'wait')
      .reduce((n, i) => n + seconds(i.started_at, now), 0),
    // Open work is bounded by its checkpoint; open waits are intentionally still ongoing.
    unclassified_seconds: Math.max(
      0,
      seconds(d.tracking_started_at, d.completed_at ?? now) -
        work -
        wait -
        d.intervals
          .filter((i) => i.ended_at === null)
          .reduce(
            (n, i) => n + seconds(i.started_at, i.kind === 'wait' ? now : i.last_observed_at),
            0
          )
    ),
    rework_seconds: sum(
      (i) =>
        i.kind === 'work' &&
        ['verification_failure', 'review_feedback', 'scope_change'].includes(
          attempts.get(i.step?.attempt_id ?? i.stage_attempt_id)?.trigger
        )
    ),
    blocked_seconds: sum(
      (i) => i.kind === 'wait' && ['external_dependency', 'environment'].includes(i.reason)
    ),
    approval_wait_seconds: sum((i) => i.kind === 'wait' && i.reason === 'approval'),
    failed_checks: d.checks.filter((c) => c.result === 'failed').length,
    first_pass_verification_rate: checked.length
      ? checked.filter((checks) => {
          const first = new Map();
          for (const c of checks) {
            const key = JSON.stringify([c.kind, c.name]);
            if (!first.has(key)) first.set(key, c);
          }
          return [...first.values()].every((c) => c.result === 'passed');
        }).length / checked.length
      : null,
    human_reported_seconds: d.metrics?.human_reported_seconds ?? null,
    tokens: d.usage_samples.length
      ? { input_tokens: tokenSum('input_tokens'), output_tokens: tokenSum('output_tokens') }
      : null,
    token_coverage: d.usage_samples.length ? 'partial' : 'unavailable',
  };
}

/** Validate, re-derive metrics and per-unit flags, and atomically persist stat.json. */
function save() {
  validateState(data);
  for (const stage of data.stages)
    stage.flags = flagsOf(
      stage,
      data.checks.filter((c) => c.stage_id === stage.id)
    );
  for (const step of data.steps)
    step.flags = flagsOf(
      step,
      data.checks.filter((c) => c.step?.id === step.id)
    );
  data.metrics = deriveMetrics(data, utc());
  atomic(path.join(dir, FILES.stat), JSON.stringify(data, null, 2) + '\n');
}
/** @returns {object|undefined} The single open interval, if any. */
const open = () => data.intervals.find((i) => i.ended_at === null);
/** Close the open interval, bounding its checkpoint and end at `now`. */
function close(now = utc()) {
  const i = open();
  if (i) {
    i.last_observed_at = now;
    i.ended_at = now;
  }
}
/** @returns {object} The active or waiting stage; throws when none is. */
function activeStage() {
  return need(
    data.stages.find((s) => ['active', 'waiting'].includes(s.status)),
    'Start a stage first'
  );
}
/**
 * Attribution for new records: the current stage attempt, plus the current
 * step attempt when a step is active.
 * @returns {{stage_id: string, stage_attempt_id: string, step: object|null}}
 */
function context() {
  const stage = activeStage();
  const step = data.steps.find((s) => ['active', 'waiting'].includes(s.status));
  return {
    stage_id: stage.id,
    stage_attempt_id: last(stage).id,
    step: step ? { id: step.id, attempt_id: last(step).id } : null,
  };
}
/**
 * Open or extend an interval. Repeating the open interval's exact context only
 * moves its checkpoint; anything else closes it and starts a new interval.
 * Mirrors the interval kind onto the active stage/step status.
 * @param {'work'|'wait'} kind
 * @param {string} value Activity (work) or reason (wait).
 * @param {string} [now] UTC timestamp.
 */
function interval(kind, value, now = utc()) {
  member(value, kind === 'work' ? ACTIVITIES : REASONS);
  const refs = context();
  const current = open();
  const key = kind === 'work' ? 'activity' : 'reason';
  if (
    current &&
    current.kind === kind &&
    current[key] === value &&
    current.stage_attempt_id === refs.stage_attempt_id &&
    current.step?.attempt_id === refs.step?.attempt_id &&
    (kind === 'work' || current.detail === (o.detail ?? null))
  )
    current.last_observed_at = now;
  else {
    close(now);
    data.intervals.push({
      id: randomUUID(),
      ...refs,
      kind,
      [key]: value,
      ...(kind === 'wait' ? { detail: o.detail ?? null } : {}),
      started_at: now,
      ended_at: null,
      last_observed_at: now,
    });
  }
  activeStage().status = kind === 'work' ? 'active' : 'waiting';
  const step = data.steps.find((s) => ['active', 'waiting'].includes(s.status));
  if (step) step.status = kind === 'work' ? 'active' : 'waiting';
}
/**
 * Begin a new attempt on a unit, superseding an unfinished one. Any new
 * attempt clears ticket completion; the first sets the observed start.
 * @param {object} unit Stage or step.
 * @param {string} trigger 'initial' or a retry trigger.
 * @param {string} now UTC timestamp.
 */
function attempt(unit, trigger, now) {
  if (last(unit)?.ended_at === null)
    Object.assign(last(unit), { ended_at: now, outcome: 'superseded' });
  unit.attempts.push({ id: randomUUID(), started_at: now, ended_at: null, trigger, outcome: null });
  unit.status = 'active';
  data.started_at ??= now;
  data.completed_at = null;
}

/** Shared column-definition prose for the Stage/Step Metrics section header. */
function columnNotes(unit) {
  return `**Elapsed** = wall-clock time from the ${unit}'s first start to its completion (includes any wait). **Work** = summed observed work intervals (active effort) within that span. **Wait** = summed observed wait intervals (blocked on developer input, approval, or an external dependency) within that span. Work + Wait can read less than Elapsed when time went unclassified, or more after a retry reopened the ${unit}. Durations are shown as \`Xh Ym Zs\`, rounded to the nearest second; open intervals are excluded from Elapsed/Work/Wait. **Flags** surfaces non-initial attempt triggers (๐Ÿ” retried/rework, ๐Ÿ”€ scope change, ๐Ÿ”“ reopened) and any failed check (โš ๏ธ), derived from recorded data โ€” never a new judgment call โ€” so a reader can scan for problem ${unit}s without parsing every row.`;
}

/**
 * Splice `sectionText` into `existing` at `markers`, or append it if the markers are
 * absent. A `legacy` marker pair (from reports generated before the stage/step
 * split) is migrated in place: the new section, including its new markers, replaces
 * the legacy block.
 */
function spliceSection(existing, heading, markers, sectionText, legacy) {
  const marker = existing.includes(markers.start)
    ? markers
    : legacy && existing.includes(legacy.start)
      ? legacy
      : null;
  if (marker) {
    const start = existing.indexOf(marker.start);
    const end = existing.indexOf(marker.end, start);
    need(end >= 0, 'Unclosed metrics marker');
    // Splice literal content so titles containing replacement patterns remain intact.
    return (
      existing.slice(0, start) +
      sectionText.split(`## ${heading}\n\n`)[1].trimEnd() +
      existing.slice(end + marker.end.length)
    );
  }
  // Preserve existing prose and historic rows, even if an older metrics section exists.
  return existing + '\n' + sectionText;
}

/** Non-initial attempt triggers that count as a flaggable code, keyed by trigger. */
const TRIGGER_FLAGS = {
  verification_failure: 'retried',
  review_feedback: 'rework',
  scope_change: 'scope_change',
  reopened: 'reopened',
};
/** Scannable label for each flag code, used only when rendering the report. */
const FLAG_LABELS = {
  retried: '๐Ÿ” retried',
  rework: '๐Ÿ” rework',
  scope_change: '๐Ÿ”€ scope change',
  reopened: '๐Ÿ”“ reopened',
  failed_check: 'โš ๏ธ failed check',
};

/**
 * Derive scannable problem-flag codes for `unit` from data already recorded โ€”
 * never a new judgment call, only a label over existing attempt triggers and
 * check results. Persisted onto the unit itself by `save()`, and re-rendered as
 * labels in the report's Flags column.
 * @returns {string[]} Flag codes (keys of `FLAG_LABELS`), empty when none apply.
 */
function flagsOf(unit, checks) {
  const flags = new Set();
  for (const a of unit.attempts) if (TRIGGER_FLAGS[a.trigger]) flags.add(TRIGGER_FLAGS[a.trigger]);
  if (checks.some((c) => c.result === 'failed')) flags.add('failed_check');
  return [...flags];
}

/** One Stage/Step Metrics table row for `unit` (a stage or a numbered step). */
function metricsRow(unit, label, intervalsOf, checksOf) {
  const ints = intervalsOf(unit).filter((i) => i.ended_at);
  const sum = (kind) =>
    ints.filter((i) => i.kind === kind).reduce((n, i) => n + seconds(i.started_at, i.ended_at), 0);
  const start = unit.attempts[0]?.started_at;
  const end = unit.status === 'completed' ? last(unit).ended_at : null;
  const checks = checksOf(unit);
  const flags =
    flagsOf(unit, checks)
      .map((f) => FLAG_LABELS[f])
      .join(' ') || 'โ€”';
  const cells = [
    label,
    start,
    end,
    humanDuration(end ? seconds(start, end) : null),
    humanDuration(sum('work')),
    humanDuration(sum('wait')),
    'unavailable',
    'unavailable',
    data.coverage,
    unit.attempts.length,
    checks.filter((c) => c.result === 'failed').length,
    flags,
  ];
  return `| ${cells.map(escapeMarkdownCell).join(' | ')} |`;
}

/**
 * Render the Stage/Step Metrics section for `unitName` ('Stage'/'Step').
 * @param {string} [trailer] Extra prose appended after the table, before the end marker.
 * @returns {string} The full `## {unitName} Metrics` section, markers included.
 */
function metricsSection(unitName, rows, markers, unit, trailer = '') {
  const heading = `${unitName} Metrics`;
  const table = `| ${unitName} | Started (UTC) | Completed (UTC) | Elapsed | Work | Wait | Input tokens | Output tokens | Coverage | Attempts | Failed checks | Flags |\n| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |\n${rows.join('\n')}`;
  const summary = `Observed work: ${humanDuration(data.metrics.observed_work_seconds)} ยท Wait: ${humanDuration(data.metrics.observed_wait_seconds)} ยท Unclassified: ${humanDuration(data.metrics.unclassified_seconds)}`;
  return `## ${heading}\n\n${markers.start}\nSource: [${FILES.stat}](${FILES.stat}). ${columnNotes(unit)} Token subtotals have ${data.metrics.token_coverage} coverage; ticket usage is not allocated to individual units.\n\n${summary}\n\n${table}${trailer}\n${markers.end}\n`;
}

/** Refresh Stage/Step Metrics in the report file, preserving all surrounding prose. */
function report() {
  const stageRows = data.stages.map((s) =>
    metricsRow(
      s,
      s.id,
      (stage) => data.intervals.filter((i) => i.stage_id === stage.id),
      (stage) => data.checks.filter((c) => c.stage_id === stage.id)
    )
  );
  const stageSection = metricsSection(
    'Stage',
    stageRows,
    STAGE_REPORT_MARKERS,
    'stage',
    `\n\n${qualitySummary(data.quality)}`
  );

  const stepRows = data.steps
    .toSorted((a, b) => a.order - b.order)
    .map((s) =>
      metricsRow(
        s,
        `${s.id}: ${s.title}`,
        (step) => data.intervals.filter((i) => i.step?.id === step.id),
        (step) => data.checks.filter((c) => c.step?.id === step.id)
      )
    );
  const stepSection = metricsSection('Step', stepRows, STEP_REPORT_MARKERS, 'step');

  const file = path.join(dir, FILES.report);
  let content = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
  content = spliceSection(content, 'Stage Metrics', STAGE_REPORT_MARKERS, stageSection);
  // The pre-split single block was the step table; migrate it in place under the step section.
  content = spliceSection(
    content,
    'Step Metrics',
    STEP_REPORT_MARKERS,
    stepSection,
    LEGACY_REPORT_MARKERS
  );
  atomic(file, content);
}

/** @returns {object} A fresh v2 stat.json document for this lifecycle. */
function initialState(now) {
  return {
    schema_version: 2,
    lifecycle: LIFECYCLE,
    ticket: need(o.ticket, 'init requires --ticket'),
    author: o.author ?? null,
    tracking_started_at: now,
    ticket_created_at: o['created-at'] ?? null,
    ticket_created_source: o['created-at']
      ? need(o.source, '--created-at requires --source')
      : null,
    started_at: null,
    completed_at: null,
    coverage: member(o.coverage ?? 'from_tracking_start', ['from_tracking_start', 'partial']),
    stages: STAGES.map((id) => ({ id, status: 'pending', attempts: [] })),
    steps: [],
    intervals: [],
    checks: [],
    usage_samples: [],
    metrics: {},
  };
}

/** @returns {object} A check record attributed to the current stage/step attempt. */
function newCheck(now) {
  return {
    id: o.id ?? randomUUID(),
    ...context(),
    name: o.name,
    kind: o.kind,
    started_at: now,
    ended_at: now,
    result: o.result,
    evidence_ref: o.evidence,
    source: o.source,
    exit_code: null,
    signal: null,
  };
}

/**
 * Finalize ticket completion. Requires the final stage completed and no
 * unfinished units; full coverage additionally requires every stage completed.
 * Repeating a completion preserves the original timestamp.
 */
function completeLifecycle(now) {
  need(
    data.stages.find((s) => s.id === FINAL_STAGE).status === 'completed',
    `${FINAL_STAGE} stage must be complete`
  );
  need(
    data.stages.every((s) => ['pending', 'completed'].includes(s.status)) &&
      data.steps.every((s) => s.status === 'completed'),
    'Unfinished work remains'
  );
  need(
    data.coverage === 'partial' || data.stages.every((s) => s.status === 'completed'),
    'Full-flow completion requires all stages'
  );
  close(now);
  data.completed_at ??= now;
}

/**
 * Register an approved plan step. An identical replay is a no-op; a
 * conflicting redefinition fails.
 * @param {string} id Stable step ID.
 * @param {object|undefined} unit Existing step with this ID, if any.
 */
function addStep(id, unit) {
  const definition = {
    id,
    title: need(o.title, 'Missing --title'),
    order: Number(need(o.order, 'Missing --order')),
    plan_ref: need(o['plan-ref'], 'Missing --plan-ref'),
    depends_on: o['depends-on']?.split(',') ?? [],
  };
  if (!unit) {
    data.steps.push({ ...definition, status: 'pending', attempts: [] });
    return;
  }
  for (const key of Object.keys(definition))
    need(
      JSON.stringify(unit[key]) === JSON.stringify(definition[key]),
      `Step ${id} already exists with different ${key}`
    );
}

/**
 * Guard a start/retry: only one unit of each kind may be active, steps run
 * only inside implement, and step dependencies must be complete.
 */
function ensureUnitCanStart(unit, isStage) {
  if (!isStage) {
    need(activeStage().id === 'implement', 'Implementation steps run within implement');
    need(
      unit.depends_on.every((id) => data.steps.find((s) => s.id === id)?.status === 'completed'),
      'Incomplete step dependencies'
    );
  }
  const units = isStage ? data.stages : data.steps;
  need(
    !units.some((s) => s !== unit && ['active', 'waiting'].includes(s.status)),
    `Complete the active ${noun} first`
  );
  if (isStage)
    need(
      !data.steps.some((s) => ['active', 'waiting'].includes(s.status)),
      'Complete the active step first'
    );
}

/**
 * Start or retry a stage/step and open its work interval. Repeating a start
 * on an already active unit acts as a checkpoint, not a new attempt.
 */
function startUnit(unit, isStage, now) {
  ensureUnitCanStart(unit, isStage);
  if (verb === 'retry' || unit.status === 'pending') {
    if (verb === 'retry') need(unit.attempts.length, 'Cannot retry a unit that has never started');
    close(now);
    attempt(unit, verb === 'retry' ? member(o.reason, TRIGGERS) : 'initial', now);
  } else need(unit.status !== 'completed', 'Use retry to reopen completed work');
  const activity = isStage ? ACTIVITIES_BY_STAGE[unit.id] : 'implementation';
  interval('work', o.activity ?? activity, now);
}

/**
 * Guard a completion: stages need their steps finished and a passed
 * "<Stage> sign-off" acceptance check recorded in the current attempt (the
 * developer's reply); steps need at least one check and passing latest results
 * for every named check of the current attempt.
 */
function ensureUnitCanComplete(unit, isStage) {
  need(['active', 'waiting'].includes(unit.status), 'Unit has not started');
  if (isStage) {
    need(
      !data.steps.some((s) => ['active', 'waiting'].includes(s.status)) &&
        (unit.id !== 'implement' || data.steps.every((s) => s.status === 'completed')),
      'Finish implementation steps first'
    );
    need(
      data.checks.some(
        (c) =>
          c.stage_attempt_id === last(unit).id &&
          !c.step &&
          c.kind === 'acceptance' &&
          c.result === 'passed' &&
          /sign-off$/i.test(c.name)
      ),
      `Stage ${unit.id} needs a passed "<Stage> sign-off" acceptance check in this attempt (record the developer's reply first)`
    );
    return;
  }
  const checks = data.checks.filter((c) => c.step?.attempt_id === last(unit).id);
  const latest = new Map(checks.map((c) => [JSON.stringify([c.kind, c.name]), c]));
  need(
    latest.size && [...latest.values()].every((c) => c.result === 'passed'),
    'Step requires passing verification; unresolved checks remain'
  );
}

/** Complete a stage/step; repeating a completion is a no-op. */
function completeUnit(unit, isStage, now) {
  if (unit.status === 'completed') return;
  ensureUnitCanComplete(unit, isStage);
  close(now);
  unit.status = 'completed';
  Object.assign(last(unit), { ended_at: now, outcome: 'completed' });
}

/** Handle `stage`/`step` subcommands: add, start, retry, and complete. */
function handleUnit(now) {
  const isStage = noun === 'stage';
  const id = need(isStage ? o.stage : o.id, 'Missing stage/step ID');
  const unit = (isStage ? data.stages : data.steps).find((s) => s.id === id);
  if (verb === 'add' && !isStage) return addStep(id, unit);
  need(unit, `Unknown ${noun}: ${id}`);
  if (['start', 'retry'].includes(verb)) return startUnit(unit, isStage, now);
  if (verb === 'complete') return completeUnit(unit, isStage, now);
  fail('Expected add, start, retry, or complete');
}

/**
 * Take the exclusive writer lock or fail; never removes another writer's lock.
 * @returns {string} Lock file path, released in main's `finally`.
 */
function acquireLock() {
  const lockPath = path.join(dir, FILES.lock);
  try {
    lock = fs.openSync(lockPath, 'wx');
    fs.writeFileSync(lock, JSON.stringify({ pid: process.pid, started_at: utc() }));
  } catch (error) {
    if (error.code === 'EEXIST')
      fail(
        `Metrics writer locked: ${lockPath}. If interrupted, verify its PID is no longer running before removing this lock.`
      );
    throw error;
  }
  return lockPath;
}

/** Load and validate stat.json, or build the initial state for a first init. */
function loadState(now) {
  const file = path.join(dir, FILES.stat);
  if (noun === 'init' && !fs.existsSync(file)) {
    data = initialState(now);
    return;
  }
  data = JSON.parse(fs.readFileSync(file, 'utf8'));
  migrateStages(data);
  validateState(data);
}

/**
 * Forward-migrate a document written before a lifecycle stage existed: append the
 * missing stage as pending, in lifecycle order. Nothing recorded is changed.
 */
function migrateStages(d) {
  if (!Array.isArray(d.stages)) return;
  const present = new Set(d.stages.map((s) => s.id));
  for (const id of STAGES)
    if (!present.has(id)) d.stages.push({ id, status: 'pending', attempts: [] });
  d.stages.sort((a, b) => STAGES.indexOf(a.id) - STAGES.indexOf(b.id));
}

/** Move the open interval's checkpoint; a no-op when nothing is open. */
function checkpointWork(now) {
  const current = open();
  if (current) current.last_observed_at = now;
}

/**
 * Recover from an interrupted session: close open work at its last checkpoint
 * and mark persisted `running` checks `interrupted` so they demand a rerun.
 */
function recoverWork() {
  const current = open();
  if (current?.kind === 'work') current.ended_at = current.last_observed_at;
  for (const check of data.checks.filter((c) => c.result === 'running')) {
    check.result = 'interrupted';
    check.ended_at = check.last_observed_at;
    check.evidence_ref = `Execution interrupted; last observed at ${check.last_observed_at}; rerun required`;
  }
  // Explicit waits survive session gaps; resume closes them.
}

/** Import one runtime usage sample; identical replays are ignored, conflicts fail. */
function importUsage() {
  const sample = JSON.parse(fs.readFileSync(need(o.file, 'usage requires --file'), 'utf8'));
  const existing = data.usage_samples.find(
    (s) =>
      s.source === sample.source &&
      s.session_id === sample.session_id &&
      s.sample_id === sample.sample_id
  );
  if (existing) {
    need(JSON.stringify(existing) === JSON.stringify(sample), 'Conflicting usage sample');
    return;
  }
  data.usage_samples.push(sample);
}

/**
 * Detect a replayed check event ID; on a match, reproduce the recorded exit
 * code without executing or recording anything.
 * @returns {boolean} True when the event was a replay.
 */
function replayCheck() {
  const previous = data.checks.find((c) => o.id && c.id === o.id);
  if (!previous) return false;
  const current = context();
  need(
    previous.name === o.name &&
      previous.kind === o.kind &&
      (!o.result || previous.result === o.result) &&
      previous.step?.attempt_id === current.step?.attempt_id &&
      previous.stage_attempt_id === current.stage_attempt_id,
    'Conflicting check event ID'
  );
  process.exitCode = previous.exit_code ?? (previous.result === 'passed' ? 0 : 1);
  console.log(JSON.stringify({ duplicate: o.id }));
  return true;
}

/** Record externally observed check evidence; never executes a command. */
function recordManualCheck(check) {
  need(!command.length, 'record does not execute a command');
  member(o.result, ['passed', 'failed', 'error', 'cancelled']);
  need(o.evidence && o.source, 'Manual check requires --evidence and --source');
  data.checks.push(check);
  return 0;
}

/**
 * Persist progress once per second while a wrapped command runs, so recovery
 * can bound the observed work even after a hard kill.
 * @returns {{stop: function(): void, verify: function(): void}}
 */
function startHeartbeat(check) {
  let error;
  const timer = setInterval(() => {
    try {
      const now = utc();
      checkpointWork(now);
      check.last_observed_at = now;
      save();
    } catch (caught) {
      error = caught;
      child?.kill('SIGTERM');
    }
  }, 1000);
  return {
    stop() {
      clearInterval(timer);
    },
    verify() {
      if (error) throw error;
    },
  };
}

/**
 * Spawn the wrapped verification command without a shell.
 * @returns {Promise<{error?: string, code?: number, signal?: string}>}
 */
function spawnVerification() {
  return new Promise((resolve) => {
    child = spawn(command[0], command.slice(1), { stdio: 'inherit', shell: false });
    child.once('error', (error) => resolve({ error: error.message }));
    child.once('close', (code, signal) => resolve({ code, signal }));
  });
}

/** Map a child outcome to a stored check result. */
function checkResult(outcome, signal) {
  if (outcome.error) return 'error';
  if (signal) return 'cancelled';
  return outcome.code === 0 ? 'passed' : 'failed';
}

/** Map a child outcome to the exit code this process forwards. */
function checkExitCode(outcome, signal) {
  if (outcome.error) return 127;
  if (signal === 'SIGINT') return 130;
  if (signal) return 143;
  return outcome.code;
}

/**
 * Record the finished command's outcome on the check.
 * @returns {number} Exit code to forward.
 */
function applyCheckOutcome(check, outcome) {
  check.exit_code = outcome.code ?? null;
  check.signal = outcome.signal ?? caughtSignal;
  check.result = checkResult(outcome, check.signal);
  check.source = 'command';
  check.evidence_ref = outcome.error ?? `Command exit recorded for ${o.name}`;
  // Arguments/output can contain secrets: do not persist them.
  return checkExitCode(outcome, check.signal);
}

/**
 * Run a wrapped verification command: persist the check as `running` first,
 * heartbeat during execution, then record the outcome and restore the prior
 * work activity. A termination signal closes work without restarting it.
 * @returns {Promise<number>} Exit code to forward.
 */
async function executeCheck(check, now) {
  need(!verb && command.length, 'Use check -- <executable> <args>, or check record');
  const previousActivity = open()?.kind === 'work' ? open().activity : 'verification';
  interval('work', 'verification', now);
  Object.assign(check, {
    result: 'running',
    ended_at: null,
    last_observed_at: now,
    source: 'command',
    evidence_ref: `Command started for ${o.name}`,
  });
  data.checks.push(check);
  save(); // Persist before spawning so recovery cannot reuse an older passing check.
  const heartbeat = startHeartbeat(check);
  let exit;
  try {
    exit = applyCheckOutcome(check, await spawnVerification());
  } finally {
    heartbeat.stop();
    child = null;
  }
  heartbeat.verify();
  check.ended_at = utc();
  check.last_observed_at = check.ended_at;
  close(check.ended_at);
  if (!check.signal) interval('work', previousActivity, check.ended_at);
  return exit;
}

/**
 * Handle `check` (execute) and `check record` (manual evidence).
 * @returns {Promise<boolean>} True when a replayed event ended the command early.
 */
async function handleCheck(now) {
  member(o.kind, ['build', 'test', 'lint', 'typecheck', 'acceptance']);
  need(o.name, 'check requires --name');
  if (replayCheck()) return true;
  const check = newCheck(now);
  const exit = verb === 'record' ? recordManualCheck(check) : await executeCheck(check, now);
  save();
  process.exitCode = exit;
  return false;
}

/** Handle `wait start`: open an explicit wait interval. */
function startWait() {
  need(verb === 'start', 'Unknown command');
  interval('wait', o.reason);
}

/** Recompute the quality inventory from the report file's source tables. */
function refreshQuality() {
  const file = path.join(dir, FILES.report);
  data.quality = deriveQuality(
    fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '',
    data.checks
  );
}

/** Handle `quality validate`: fail closed on any open finding, failure, or non-terminal check. */
function validateQualityClosure() {
  need(verb === 'validate', 'Use quality validate');
  refreshQuality();
  need(data.quality.closure_issues.length === 0, data.quality.closure_issues.join('; '));
  need(
    data.quality.tests?.failed === null ||
      data.quality.tests === null ||
      data.quality.tests.failed === 0,
    'Latest test case failures remain'
  );
  const latest = new Map(data.checks.map((c) => [JSON.stringify([c.kind, c.name]), c]));
  need(
    [...latest.values()].every((c) => c.result === 'passed'),
    'Latest recorded checks must pass before closure'
  );
}

/** Persist mutations, refresh the report when asked, and print the summary line. */
function finishCommand() {
  if (noun !== 'validate') save();
  if (noun === 'report') report();
  console.log(JSON.stringify({ command: words.join(' '), ticket: data.ticket }));
}

/** Entry point: lock, load, guard interrupted checks, dispatch, release. */
async function main() {
  dir = path.resolve(need(o.dir, 'Every command requires --dir <ticket impl directory>'));
  need(words.length <= 2, 'Unexpected positional arguments');
  if (noun === 'init') fs.mkdirSync(dir, { recursive: true });
  const lockPath = acquireLock();
  try {
    const now = utc();
    loadState(now);
    need(
      !data.checks.some((c) => c.result === 'running') ||
        ['recover', 'report', 'validate'].includes(noun),
      'Interrupted verification found; run recover before recording new work'
    );
    if (await dispatchCommand(now)) return;
    finishCommand();
  } finally {
    fs.closeSync(lock);
    fs.unlinkSync(lockPath);
    lock = undefined;
  }
}

/**
 * Route the parsed command to its handler.
 * @returns {unknown} Truthy when the handler already finished the command.
 */
function dispatchCommand(now) {
  const handlers = new Map([
    [
      'init',
      () => need(data.ticket === o.ticket, 'Ticket does not match existing stat.json') && false,
    ],
    ['stage', handleUnit],
    ['step', handleUnit],
    ['wait', startWait],
    ['resume', () => interval('work', need(o.activity, 'resume requires --activity'))],
    ['checkpoint', checkpointWork],
    ['recover', recoverWork],
    ['check', handleCheck],
    ['usage', importUsage],
    ['complete', completeLifecycle],
    ['report', refreshQuality],
    ['quality', validateQualityClosure],
    ['validate', () => {}],
  ]);
  const handler = need(handlers.get(noun), 'Unknown command');
  return handler(now);
}

process.on('SIGINT', signalHandler);
process.on('SIGTERM', signalHandler);
await main().catch((error) => {
  console.error(`timing: ${error.message}`);
  process.exitCode = 1;
});
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why โ€” repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" โ€” or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself โ€” your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall