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/design/scripts/design-metrics.mjs

View on GitHub
#!/usr/bin/env node
// Self-contained design metrics recorder; uses only this flow's constants and helpers.
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,
  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';

const names = [
  'dir',
  'ticket',
  'coverage',
  'stage',
  'id',
  'activity',
  'reason',
  'detail',
  'kind',
  'name',
  'result',
  'evidence',
  'source',
  'file',
  'created-at',
];
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 validate(d) {
  need(
    d.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'
  );
  {
    need(d.steps.length === 0, 'Design records stages, not implementation steps');
    need(
      Number.isSafeInteger(d.design_revision) && d.design_revision >= 0,
      'Invalid design revision'
    );
  }
  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', 'skipped']);
    if (unit.status === 'skipped')
      need(
        unit.id === 'address-feedback' &&
          unit.attempts.length === 0 &&
          unit.skip_reason &&
          unit.evidence_ref &&
          stamp(unit.skipped_at),
        'Invalid skipped stage'
      );
    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(
      Number.isSafeInteger(check.design_revision) &&
        check.design_revision >= 0 &&
        check.design_revision <= d.design_revision,
      'Invalid check revision'
    );
    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 derive(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.stages
    .map((s) =>
      d.checks.filter((c) => c.stage_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),
    wait_seconds_to_date:
      wait +
      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 atomically persist stat.json. */
function save() {
  validate(data);
  data.metrics = derive(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. The step slot stays
 * null in the design flow, which records stages only.
 * @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 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.
 * A non-initial trigger bumps the design revision (invalidating the prior
 * approval) and returns a completed publish stage to pending.
 * @param {object} unit Stage.
 * @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';
  if (trigger !== 'initial') {
    data.design_revision++;
    const publish = data.stages.find((s) => s.id === 'publish');
    const completion = data.stages.find((s) => s.id === 'completion');
    if (unit.id !== 'publish' && unit.id !== 'completion' && publish.status === 'completed') {
      publish.status = 'pending';
      if (completion.status === 'completed') completion.status = 'pending';
    }
  }
  data.started_at ??= now;
  data.completed_at = null;
}
/**
 * Whether the current design revision is approved: its latest "Design
 * approval" acceptance passed in this revision, and every named check
 * recorded in this revision passes at its latest run.
 * @returns {boolean}
 */
function designApproved() {
  const approval = data.checks.findLast(
    (c) => c.kind === 'acceptance' && c.name === 'Design approval'
  );
  if (!approval || approval.result !== 'passed') return false;
  if (approval.design_revision !== data.design_revision) return false;
  const latest = new Map(
    data.checks
      .filter((c) => c.design_revision === data.design_revision)
      .map((c) => [JSON.stringify([c.kind, c.name]), c])
  );
  return [...latest.values()].every((c) => c.result === 'passed');
}
/**
 * Render the generated metrics block into the report file, replacing only the
 * marker-delimited region and preserving all surrounding prose.
 */
function report() {
  const rows = data.stages.map((s) => {
    const ints = data.intervals.filter((i) => i.stage_id === s.id && 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 = s.attempts[0]?.started_at;
    const end = s.status === 'completed' ? last(s).ended_at : null;
    return `| ${[s.id + ' (' + s.status + ')', start, end, humanDuration(end ? seconds(start, end) : null), humanDuration(sum('work')), humanDuration(sum('wait')), 'unavailable', 'unavailable', data.coverage, s.attempts.length, data.checks.filter((c) => c.stage_id === s.id && c.result === 'failed').length].map(escapeMarkdownCell).join(' | ')} |`;
  });
  const heading = 'Stage Metrics';
  const unitName = 'Stage';
  const columnNotes = `**Elapsed** = wall-clock time from the stage'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 stage. Durations are shown as \`Xh Ym Zs\`, rounded to the nearest second; open intervals are excluded from Elapsed/Work/Wait.`;
  const section = `## ${heading}\n\n${REPORT_MARKERS.start}\nSource: [${FILES.stat}](${FILES.stat}). ${columnNotes} Token subtotals have ${data.metrics.token_coverage} coverage; ticket usage is not allocated to individual units.\n\nObserved work: ${humanDuration(data.metrics.observed_work_seconds)} · Wait to date: ${humanDuration(data.metrics.wait_seconds_to_date)} (closed ${humanDuration(data.metrics.observed_wait_seconds)} + current ${humanDuration(data.metrics.open_wait_seconds)}) · Unclassified: ${humanDuration(data.metrics.unclassified_seconds)}\n\n| ${unitName} | Started (UTC) | Completed (UTC) | Elapsed | Work | Wait | Input tokens | Output tokens | Coverage | Attempts | Failed checks |\n| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |\n${rows.join('\n')}\n${REPORT_MARKERS.end}\n`;
  const file = path.join(dir, FILES.report);
  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
  const marker = existing.includes(REPORT_MARKERS.start)
    ? REPORT_MARKERS
    : existing.includes(LEGACY_REPORT_MARKERS.start)
      ? LEGACY_REPORT_MARKERS
      : 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.
    atomic(
      file,
      existing.slice(0, start) +
        section.split(`## ${heading}\n\n`)[1].trimEnd() +
        existing.slice(end + marker.end.length)
    );
  } else {
    // Preserve existing prose and historic rows, even if an older metrics section exists.
    atomic(file, existing + '\n' + section);
  }
}

/** @returns {object} A fresh v2 stat.json document for this lifecycle. */
function initialState(now) {
  return {
    schema_version: 2,
    lifecycle: LIFECYCLE,
    design_revision: 0,
    ticket: need(o.ticket, 'init requires --ticket'),
    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 attempt and design revision. */
function newCheck(now) {
  return {
    id: o.id ?? randomUUID(),
    ...context(),
    design_revision: data.design_revision,
    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 design completion. Requires publish completed, current-revision
 * approval, and no unfinished stages; full coverage additionally requires
 * every stage completed or the authorized feedback skip. 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(designApproved(), 'Design completion requires recorded approval');
  need(
    data.stages.every((s) => ['pending', 'completed', 'skipped'].includes(s.status)) &&
      data.steps.every((s) => s.status === 'completed'),
    'Unfinished work remains'
  );
  need(
    data.coverage === 'partial' ||
      data.stages.every((s) => s.status === 'completed' || s.status === 'skipped'),
    'Full-flow completion requires all stages'
  );
  close(now);
  data.completed_at ??= now;
}

/**
 * Skip the address-feedback stage after recorded approval, with attributed
 * evidence and no fabricated attempt. Identical replays are no-ops;
 * conflicting replays fail.
 */
function skipFeedback(unit, now) {
  need(unit.id === 'address-feedback', 'Only address-feedback may be skipped');
  need(designApproved(), 'Skipping feedback requires recorded Design approval');
  need(['pending', 'skipped'].includes(unit.status), 'Cannot skip started feedback');
  need(o.reason && o.evidence, 'skip requires --reason and --evidence');
  if (unit.status === 'skipped') {
    need(
      unit.skip_reason === o.reason && unit.evidence_ref === o.evidence,
      'Conflicting skip replay'
    );
    return;
  }
  Object.assign(unit, {
    status: 'skipped',
    skip_reason: o.reason,
    evidence_ref: o.evidence,
    skipped_at: now,
  });
}

/**
 * On a review-gate retry, restore skipped feedback to pending, moving the
 * skip record into `skip_history`.
 */
function reopenFeedback(unit) {
  if (unit.id !== 'review-gate' || verb !== 'retry') return;
  const feedback = data.stages.find((s) => s.id === 'address-feedback');
  if (feedback.status !== 'skipped') return;
  (feedback.skip_history ??= []).push({
    reason: feedback.skip_reason,
    evidence_ref: feedback.evidence_ref,
    skipped_at: feedback.skipped_at,
  });
  feedback.status = 'pending';
  delete feedback.skip_reason;
  delete feedback.evidence_ref;
  delete feedback.skipped_at;
}

/**
 * Trigger for a new stage attempt: retries use the explicit reason, and
 * feedback's first start is inherently rework.
 * @returns {string}
 */
function stageTrigger(unit) {
  if (verb === 'retry') return member(o.reason, TRIGGERS);
  return unit.id === 'address-feedback' ? 'review_feedback' : 'initial';
}

/**
 * Start or retry a design stage and open its work interval. Repeating a start
 * on an already active stage acts as a checkpoint, not a new attempt.
 */
function startStage(unit, now) {
  need(unit.status !== 'skipped', 'Retry review-gate before starting previously skipped feedback');
  need(
    !data.stages.some((s) => s !== unit && ['active', 'waiting'].includes(s.status)),
    'Complete the active stage first'
  );
  if (verb === 'retry' || unit.status === 'pending') {
    if (verb === 'retry') need(unit.attempts.length, 'Cannot retry a stage that has never started');
    reopenFeedback(unit);
    close(now);
    attempt(unit, stageTrigger(unit), now);
  } else need(unit.status !== 'completed', 'Use retry to reopen completed work');
  interval('work', o.activity ?? ACTIVITIES_BY_STAGE[unit.id], now);
}

/** Stages whose sign-off is a phase-sign-off.md stop, not the MR-approval fact. */
const SIGN_OFF_GATED_STAGES = new Set([
  'context-gathering',
  'ceremony',
  'frame',
  'research',
  'evaluate',
  'solution',
  'publish',
  'completion',
]);

/**
 * Complete a stage; repeating a completion is a no-op. Review Gate and
 * Address Feedback are the MR-approval fact, not a phase sign-off, so they
 * are exempt from the "<Stage> sign-off" check. Publish additionally
 * requires current-revision approval.
 */
function completeStage(unit, now) {
  if (unit.status === 'completed') return;
  need(['active', 'waiting'].includes(unit.status), 'Stage has not started');
  if (SIGN_OFF_GATED_STAGES.has(unit.id))
    need(
      data.checks.some(
        (c) =>
          c.stage_attempt_id === last(unit).id &&
          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)`
    );
  if (unit.id === 'publish') need(designApproved(), 'Publish requires recorded Design approval');
  close(now);
  unit.status = 'completed';
  Object.assign(last(unit), { ended_at: now, outcome: 'completed' });
}

/** Handle `stage` subcommands: start, retry, skip, and complete. */
function handleStage(now) {
  const id = need(o.stage, 'Missing stage ID');
  const unit = need(
    data.stages.find((s) => s.id === id),
    `Unknown stage: ${id}`
  );
  if (verb === 'skip') return skipFeedback(unit, now);
  if (['start', 'retry'].includes(verb)) return startStage(unit, now);
  if (verb === 'complete') return completeStage(unit, now);
  fail('Expected start, retry, skip, 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);
  validate(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);
}

/** 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', handleStage],
    ['wait', startWait],
    ['resume', () => interval('work', need(o.activity, 'resume requires --activity'))],
    ['checkpoint', checkpointWork],
    ['recover', recoverWork],
    ['check', handleCheck],
    ['usage', importUsage],
    ['complete', completeLifecycle],
    ['report', () => {}],
    ['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(`design-metrics: ${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: 471kUpdated 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