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/patterns/metrics.md

View on GitHub
# Dev metrics

The orchestrator uses the dependency-free Node.js CLI in `scripts/timing.mjs`
(relative to this dev skill). Only the orchestrator writes metrics. Never hand-edit
`stat.json`, derive durations in prose, estimate tokens, sum worker wall times, or
infer stage/step completion from file presence — record only observed transitions.
Requires Node.js 22 or newer. Every command requires `--dir` pointing to the ticket's
existing `impl` directory; there is no implicit current ticket.

If configuring automatic permission for recording commands, use subcommand-specific
rules with the subcommand immediately after the script path, for example:

- `Bash(node {{provider:skills_root}}/dev/scripts/timing.mjs checkpoint *)`
- `Bash(node {{provider:skills_root}}/dev/scripts/timing.mjs stage *)`
- `Bash(node {{provider:skills_root}}/dev/scripts/timing.mjs check record *)`

The same narrow pattern can cover `init`, `step`, `wait`, `resume`, `recover`,
`report`, `validate`, `usage`, `quality`, and `complete`. Never allowlist the entire script or
`check *`: executable checks can launch arbitrary programs. Keep `check -- ...`
subject to normal command approval. Replace any previous whole-script wildcard rule;
adding narrow rules alongside it does not remove the broad permission.

## Initialize and resume

Context creates the impl directory and the report skeleton as soon as the story
name is known (right after the tracker fetch), then runs init and starts the stage
**before** the heavy reading. Do not leave init for the end of Context: that is how
the stage ends up with zero recorded time.

```sh
node {{provider:skills_root}}/dev/scripts/timing.mjs init --dir "$IMPL_DIR" --ticket "$TICKET" --author "$(git config user.name)"
```

For direct-stage entry or an existing ticket without metrics, add `--coverage partial`.
Do not backfill unseen activity. Optionally provide `--created-at <UTC timestamp>`
and `--source <tracker field or attributed user statement>` when already known.
`--author` is the same `git config user.name` value already used for `2-report.md`'s
header table — reuse it rather than asking again; omit if unavailable.
The script rejects future creation timestamps. Repeated init preserves existing data
and requires the same ticket. `templates/stat.json` illustrates the v2 shape; do not
copy its null tracking timestamp in place of running init.

Right after init, run `stage start --stage context`.

At session resume, run `recover --dir "$IMPL_DIR"` **before** start, resume, or checkpoint.
It closes interrupted work at its last checkpoint, leaving the session gap unclassified.
Checks are persisted as `running` before execution. Recovery marks unfinished checks
`interrupted` at their last checkpoint; they block step completion until a fresh
passing run of the same named check is recorded. Use a new event ID for that rerun.
Other mutations reject unrecovered running checks; report and validate remain available.
It preserves an explicit wait until `resume` closes it. Inspect existing state; ordinary
resumption does not create another attempt. A stale `.dev-metrics.lock` requires checking
that its recorded PID is no longer running before removing that lock. Never remove a
live writer's lock. Unsupported schema versions fail without modifying the file; migrate
old records explicitly with preserved originals rather than recreating their history.

## Stage and step transitions

The commands below all use the same script and require `--dir "$IMPL_DIR"`:

| Boundary                                  | Command arguments                                                                                                              |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Stage entry                               | `stage start --stage context` (or `ceremony`, `plan`, `implement`, `test`, `document`, `completion`)                           |
| Add an approved plan step                 | `step add --id step-01 --title "Implement feature" --order 1 --plan-ref "1-plan.md#step-1"`                                    |
| Optional dependencies                     | Add `--depends-on step-01,step-02`; referenced steps must already exist                                                        |
| Implementation step entry                 | `step start --id step-01 --activity implementation`                                                                            |
| After long-running work / before yielding | `checkpoint`                                                                                                                   |
| Change activity / resume a wait           | `resume --activity verification`                                                                                               |
| Before asking approval                    | `wait start --reason approval --detail "Awaiting plan approval"`                                                               |
| Before asking for verification            | `wait start --reason user_input --detail "Awaiting step acceptance"`                                                           |
| External blocker                          | `wait start --reason external_dependency --detail "Awaiting API access"`                                                       |
| Environment blocker                       | `wait start --reason environment --detail "Build environment unavailable"`                                                     |
| Revise a failed step                      | `step retry --id step-01 --reason verification_failure`                                                                        |
| Verified step completion                  | `step complete --id step-01`                                                                                                   |
| Stage completion                          | `stage complete --stage implement` — refused until a passed `acceptance` check named `<Stage> sign-off` exists in this attempt |
| Revisit a stage                           | `stage retry --stage plan --reason scope_change`                                                                               |
| Refresh report metrics                    | `report`                                                                                                                       |
| Validate stored records                   | `validate`                                                                                                                     |

A stage cannot complete without its sign-off on record: a `check record --kind
acceptance --name "<Stage> sign-off" --result passed` in the current attempt, sourced
`developer` with their words as evidence. A retry opens a new attempt and needs a new
sign-off. This is the mechanical half of the phase sign-off; the honest half is not
writing `--source developer` for words that were never said.

Activities: `investigation`, `planning`, `implementation`, `verification`, `review`,
`documentation`. Retry reasons: `verification_failure`, `review_feedback`,
`scope_change`, `reopened`. Finish the current step before leaving Implement, and
finish the current stage before entering another. Add steps in dependency order.
Stable step IDs survive plan reordering. Conflicting repeated definitions fail;
this version does not support editing/removing approved step definitions.

Start/resume closes the previous interval automatically. Repeating a start or wait
with the same context is a checkpoint, not a new attempt. Call checkpoint before
yielding without a known wait reason and after long-running operations (delegated
worker runs, large builds) — not after every tool call. Recovery bounds observed work
at the last checkpoint, so sparse checkpoints only grow unclassified time; they never
corrupt state. Tool execution and worker latency count as observed work wall time,
not CPU time or human effort.

## Where the calls go

Each stage reference says exactly where its calls sit. The shape is always:

- First action of the stage: `stage start --stage <stage>`.
- Before any stop (phase sign-off, a question, a manual operation you must wait
  on): `report`, then `wait start --reason <approval|user_input|...>`. Then stop.
- On the reply: `stage complete --stage <stage>` if the phase is accepted (this
  closes the wait at the reply time), or `resume --activity <activity>` if there is
  more work in this stage.
- Last action of the stage, when nothing is pending: `stage complete`, then the next
  stage's `stage start`.

Why this matters for wait time: an open **work** interval keeps extending on the
next command. If you yield without `wait start`, the developer's whole reply time
becomes work. The script cannot tell the difference; only the protocol can. Run
report before any stop; never write while waiting. Recording a transition does not
authorise the underlying action.

## Verification evidence

Wrap an already authorized verification command without using a shell:

```sh
node {{provider:skills_root}}/dev/scripts/timing.mjs check --dir "$IMPL_DIR" \
  --id step-01-typecheck-run-01 --kind typecheck --name "Frontend typecheck" \
  -- yarn nx run frontline-report:typecheck
```

Adapt the executable to this project's actual checks. The wrapper forwards output,
returns the child exit code, checkpoints once per second, and records exit status.
After ordinary success, failure, or a spawn error, it restores the preceding work
activity (or verification if there was no work interval). Subsequent checkpoints
therefore continue recording work; no extra resume command is required. A termination
signal closes work without restarting it.
It does not store arguments or output, which may contain secrets. It holds the writer
lock while running, so concurrent mutations fail. A spawn error records `error`, a
signal records `cancelled`, and a nonzero exit records `failed`; a nonzero code alone
cannot establish whether assertions or the environment caused failure. Existing
command restrictions and tool approval requirements apply equally to wrapped commands;
never use the wrapper to bypass them. Avoid shell commands or indefinite servers.

For an actual developer confirmation or an externally executed check:

```sh
node {{provider:skills_root}}/dev/scripts/timing.mjs check record --dir "$IMPL_DIR" \
  --id step-01-acceptance-01 --kind acceptance --name "Plan acceptance" \
  --result passed --source developer --evidence "Developer confirmed the plan's checks passed"
```

**`--source developer` requires an actual developer reply to attribute.** `--source`
is free text the script does not validate — nothing technical stops writing
`developer` for a check you ran yourself. Using it that way is not a shortcut, it is
fabricating sign-off: the record then falsely tells everyone downstream (`2-report.md`,
the developer on resume, a future auditor) that a human confirmed something no human
ever saw. Only record `--source developer` when the developer's own message in this
conversation is what you are quoting or summarizing as `--evidence`; if no such reply
exists yet, the check has not happened yet — do not record it, do not mark the step
Done or complete, and do not invent evidence text to fill the gap. A check you ran
yourself (typecheck, build, browser walkthrough, anything) is recorded with a source
that says so (e.g. `--source self` or `--source orchestrator`), never `developer`,
regardless of how confident you are in the result — confidence is not attribution.
If you notice you've already recorded a fabricated `--source developer` entry,
correct it immediately with a new event under a new ID and reopen the step rather
than leaving the false record standing until asked about it.

Kinds: `build`, `test`, `lint`, `typecheck`, `acceptance`. Manual results also accept
`failed`, `error`, `cancelled`. `running` and `interrupted` are recorder-owned
results, not manual assertions. Manual timestamps record when evidence was received,
not an invented execution duration. `--id` deduplicates a replay; use a **new** ID
for each real rerun. Never reuse an event ID for different work or different commands.
Each check automatically references the current stage and optional step attempt.
Step completion requires at least one check and passing latest results for every named
check in its current attempt. After a retry, verification must be recorded again.

## Runtime usage

`usage --file <sample.json>` accepts a runtime-provided sample:

```json
{
  "sample_id": "runtime-event-123",
  "source": "runtime-provider",
  "session_id": "session-456",
  "scope": "ticket",
  "measurement": "delta",
  "input_tokens": 123,
  "output_tokens": null
}
```

Only non-overlapping ticket-scoped deltas are supported in v2. Source/session/sample
identity deduplicates replays. Do not import session totals spanning other tickets,
cumulative counters, estimates, or worker usage already included in a parent sample.
The CLI validates structure but cannot independently verify a provider's attribution.
Unknown counters stay null; imported totals remain labeled partial. Step token usage
stays unavailable because this version does not allocate ticket usage to steps.

## Data contract and derived metrics

`templates/stat.schema.json` specifies v2. Stages are the seven lifecycle units; steps
are stable approved implementation units. Each owns attempts with start/end, trigger,
and outcome. Intervals reference a stage attempt and optionally a step attempt;
only one orchestrator interval can be open and no intervals may overlap. `checks`
contains actual evidence, separate from time accounting. Unknown fields are retained.

`metrics` is a recalculated summary: closed observed work/wait, separately reported
open work/wait, unclassified time, rework (work on explicitly revised attempts),
blocked time, approval wait, failed check runs, first-pass verification rate, and
runtime token subtotals. First-pass rate considers steps with pass/fail evidence;
a step qualifies when the first recorded run of each named check passed. It is
provisional until verification is finished. Retries preserve the original evidence.

Lead time requires known ticket creation and completion; cycle time requires observed
start and completion. These stay null until their endpoints exist. Human effort is
never inferred. Completion requires the Completion stage finished and no active or pending steps;
full coverage also requires all seven stages completed. Only run `complete` after the
closure checks pass and the story is archived, never merely because a direct stage
ended. A stat.json written before the Completion stage existed gains it as pending on
the next mutation; nothing recorded changes. Reopening clears ticket completion
while preserving prior attempt history. Archive stat.json with the impl directory.

`report` updates only the generated marker block in `2-report.md`, preserving other
prose and historic rows. For an unmarked older report it appends a generated section.
Do not manually duplicate its rows or overwrite historic effort entries. Round display
values only; calculations retain seconds precision.

The CLI is self-contained within this flow. `scripts/timing.mjs` is the entrypoint —
stage/step/interval/check state, structural validation, and the generated Stage/Step
Metrics report sections. `scripts/quality.mjs` derives the report-sourced quality
inventory (Review Findings, Tech Debt, Test Results) that `timing.mjs` calls into for
`report` and `quality validate`. `scripts/constants.mjs` owns lifecycle IDs,
filenames, report markers, and activity/reason/finding values shared by both.
`scripts/utils.mjs` owns validation primitives, timestamp/duration helpers, atomic
writes, and Markdown cell escaping. Bootstrap installs all four together; no other
flow or shared recorder is required. Run this flow's regression suite after changes:

```sh
node --test {{provider:skills_root}}/dev/scripts/*.test.mjs
```

## Quality inventory

`report` parses the single Review Findings table, Tech Debt ledger and numerical
Test Results evidence into optional v2 `stat.json.quality`, then renders one summary
line beside Stage Metrics. It replaces the snapshot on every refresh; repeated report
runs never increment findings or test counts. IDs and source-table hash make the
snapshot traceable. Preserve kind, impact severity, classification, resolution,
deviation type, PR-origin subset, and linked debt as separate dimensions.

The table contract lives in `patterns/review-gate.md` and `templates/report.md`.
One underlying issue keeps one RF ID across reviews. A PR review counts unique RF
rows whose Origin includes `pr-review`, not review rounds or commits. Tech Debt counts
ledger entries and ticketed/unticketed disposition; it is not added to finding totals.
Tests Written counts new cases in the diff; Passed/Failed/Skipped are latest runner
case counts over non-overlapping scopes. Unknown source values stay null. Failed test
runs come from historical `checks` with kind `test`, independently of latest cases;
build/lint errors are not test failures. Counts are inventory, not a composite score
or a comparison between tickets with different review coverage.

Old v2 metrics without quality remain valid. Missing legacy table columns yield
unavailable evidence; do not backfill guesses or automatically rewrite historic reports.
Malformed canonical tables and duplicate IDs fail refresh rather than emit false counts.
Use `node --test {{provider:skills_root}}/dev/scripts/*.test.mjs` after recorder changes.

Before archive, run `quality validate --dir "$IMPL_DIR"` after `report`. This rejects
open findings, missing terminal evidence/TD ownership, latest failing case counts and
unresolved recorded checks. It checks structure; the orchestrator must still verify
AC coverage and the substance/authorization of each resolution. Review Findings must
exist for closure; explicitly consolidate legacy findings when resuming an old story.
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