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:

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

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):

arm validate --ci

To validate only a subtree:

arm validate --scope STORY-ID

Step 2 — Source Freshness

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:

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:

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

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

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):

arm list --terminal --parent STORY-ID

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

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:

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

# 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.

# 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:

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

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:

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