# Armature Auditor

> Use when verifying completed work before story sign-off — checks citation coverage, source UUID integrity, outcome quality, and repo health. Runs validate, sources verify, render-context, and doctor --strict.

- Skill: `scullxbones/armature-auditor` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add scullxbones/armature-auditor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/scullxbones/armature-auditor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: scullxbones (https://skillmd.com/u/scullxbones)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/scullxbones/armature-auditor

---


# Armature Auditor

The Auditor verifies that completed work is honest and traceable before story sign-off. Every issue must have a valid cited source, every decision must be recorded, and outcomes must satisfy acceptance criteria.

## DAG Hygiene Mandate

**`arm validate` and `arm doctor` must exit clean at all times.** This is non-negotiable.

Before running any audit and after completing your checks, confirm:
```bash
arm validate       # zero ERRORs; all issues cited
arm doctor        # zero errors; no broken refs, orphaned ops, or cycles
```

If either exits non-zero, do not approve the story. Report the specific issues back to workers for remediation. Treat DAG decay the same way you treat failing tests — it is a blocker, not a warning to ignore.

Warnings from other stories must be resolved, not ignored. If `arm doctor` reports a D1 (commits referencing non-done issues) or D2 (stale claims) from unrelated work, clean them up before auditing. DAG health is cumulative.

---

## When to Run

The Auditor runs **after** workers report tasks done and **before** story transition and PR. It is a gate, not a monitor.

```
Workers complete tasks → Auditor runs → Story transitions to done → PR opened
```

Do not approve a story transition until all audit checks pass. If any check fails, report the specific issues back to the workers for remediation before re-auditing.

**Scope Clarification:** The Auditor checks **structural integrity** (citation coverage and repo health) but does NOT perform **semantic review** of code changes. Semantic conformance to acceptance criteria is handled by the `armature-reviewer` skill, which is dispatched by the coordinator after each task completes. Both gates must pass before story sign-off.

## The Audit Checklist

Work through these steps in order. Each step must pass before proceeding to the next.

### Step 1 — Citation Integrity

```bash
arm validate
```

Expected output: `COVERAGE: N/N cited` with **zero ERROR lines**.

If `arm validate` reports ERROR lines, read `references/citation-errors.md`.

For CI use (exits non-zero on any error):

```bash
arm validate --ci
```

`arm validate` always checks the whole graph. There are no scoping flags.

### Step 2 — Source Freshness

```bash
arm sources verify
```

All sources must show `OK`. Any `MISSING` entry means a source fingerprint is stale or the source was removed after initial registration.

If sources show `MISSING`:

```bash
arm sources sync        # fetch and re-fingerprint all sources
arm sources verify      # re-run until all show OK
```

If a source is gone entirely, re-register it:

```bash
arm sources add --url /path/to/source --type filesystem
```

If source content changed and you need to review the delta before accepting it:

```bash
arm sources stale-review        # interactive review of sources whose content changed
```

### Step 3 — Outcome Quality Review

List all terminal tasks under the story (done, merged, and cancelled):

```bash
arm list --terminal --parent STORY-ID
```

For each completed task, inspect its outcome against its acceptance criteria:

```bash
arm render-context --issue ISSUE-ID
```

`render-context` shows both the `acceptance` criteria array and the recorded `outcome` field side by side. Verify that:

- The outcome is **concrete** — it describes what was built, references specific files, commands, or test results, and cites metrics where applicable.
- The outcome **addresses every acceptance criterion** — if `acceptance` lists "TestDoctorVerbose passes" and the outcome says "done", that is a gap.
- The outcome is **not vague** — flag "Done", "Fixed", "Implemented", "Completed" as insufficient before sign-off.

You can also inspect an issue directly:

```bash
arm show ISSUE-ID      # shows outcome and acceptance criteria side by side
```

**Good outcome example:**
> "Added `--verbose` flag to `arm doctor`; each violation now prints the op file path and affected issue ID; 3 new tests added; make check green at 82% coverage"

**Vague outcome examples (flag these):**
> "Done" / "Fixed" / "Implemented as requested" / "Completed"

### Step 4 — Validation Warnings and --strict

`arm validate` may report `WARNING` lines in two categories:

1. **Scope Overlap** — Two or more tasks touch the same file(s)
2. **Context Files** — A task's context_files array is empty while its scope spans 3+ distinct directories

These warnings are not errors by default, but **must be resolved before sign-off**.

#### Scope Overlap Resolution

```bash
# Make overlapping tasks serial
arm link --source ISSUE-A --dep ISSUE-B

# Or treat overlaps as errors to confirm none remain
arm validate --strict
```

If two tasks genuinely do not overlap despite the warning, document the rationale with `arm decision` on one of the issues before proceeding.

#### Context Files Resolution

The W5 warning fires when a task's `context_files` is empty AND its scope spans 3+ distinct directories (broad scope). Context files are informational references to files that inform the task but are not modified directly. Resolve this warning by either narrowing the scope to fewer directories or by adding context_files declarations.

```bash
# View context_files warnings
arm validate

# Option 1: Narrow the scope to cover fewer directories (< 3)
arm amend TASK-01 --scope "src/**/*.go"

# Option 2: Add context_files declarations (informational files that inform the task)
arm amend TASK-01 --context-file docs/notes.md --context-file docs/spec.md
```

Choose Option 1 if the task can be more tightly scoped. Choose Option 2 if the task genuinely works across multiple directories and context files will help the worker understand the cross-directory dependencies.

#### Using --strict

The `--strict` flag promotes all warnings to errors, including both scope overlap and context_files warnings:

```bash
arm validate --strict
```

This is useful in CI or pre-merge gates to ensure no warnings are missed. Scope overlap and context_files warnings are distinct categories and must be resolved separately — linking issues for scope overlap does not resolve context_files warnings.

### Step 5 — Repo Health

```bash
arm doctor --strict
```

`--strict` promotes all warnings to errors. The command must **exit zero**. Any warning or error must be resolved before approving the story.

For machine-readable output:

```bash
arm doctor --format json
```

Doctor checks reference:

| Code | Severity | Check |
|------|----------|-------|
| D1 | warning | Git commits reference non-done issues |
| D2 | warning | Claimed issues with expired TTL (stale claims) |
| D3 | error | Op files reference issue IDs not in graph |
| D4 | error | Issues whose parent points to non-existent ID |
| D5 | error | `blocked_by` chains forming a dependency cycle |
| D6 | warning | Issues without `sources link` or `sources accept-citation` (field-presence only — see caveat below) |

## Pre-Merge Gate

Before approving the story transition, all five checks must be green:

| Check | Command | Pass Condition |
|-------|---------|----------------|
| Citation integrity | `arm validate` | Zero ERRORs, `COVERAGE: N/N cited` |
| Source freshness | `arm sources verify` | Zero MISSING |
| Outcome quality | `arm render-context --issue ID` for each done task | All outcomes concrete, all acceptance criteria addressed |
| Validation warnings | `arm validate --strict` | Zero scope overlap warnings, zero context_files warnings |
| Repo health | `arm doctor --strict` | Exit zero (zero ERRORs, zero WARNINGs) |

Only after all five pass should you approve the story for transition and PR.

## Common Failure Modes

| Failure Mode | Why It Happens | Fix |
|---|---|---|
| Trusting D6 alone for citation integrity | `arm doctor` D6 checks field presence only — it will pass even if the source UUID is invalid (E8) | Always run `arm validate` after `arm doctor`; D6 and E8 check different things |
| Accepting vague outcomes ("done", "fixed") | Worker transitions without writing a concrete outcome | Use `arm render-context --issue ID` to cross-check outcome against `acceptance` criteria; require workers to amend before sign-off |
| Skipping `arm sources verify` | Source fingerprints go stale silently when documents are updated after initial registration | Always run `arm sources verify` as step 2; run `arm sources sync` to refresh, then re-verify |