Formalize an approved design into a structured spec.xml with acceptance criteria. Use when a design.md is ready to become the authoritative spec, or spec quality is below threshold — the delta authority, hands to arc-planning.
Instrucciones de origen · Vista previa de solo lectura
name
arc-refining
description
Formalize an approved design into a structured spec.xml with acceptance criteria. Use when a design.md is ready to become the authoritative spec, or spec quality is below threshold — the delta authority, hands to arc-planning.
category
sdd
status
promoted
Refiner
Iron Law
NO INVENTION WITHOUT AUTHORIZATION. PRESERVE EVERY PRIOR DELTA. NEVER WRITE AUTHORITATIVE STATE ON BLOCK.
Every criterion the refiner emits MUST trace to a design phrase or a user Q&A row — invention from training-data inference is forbidden. No overwrite of earlier <delta> elements. No refiner-report.md artifact. No escape hatch from the DAG completion gate. On R3 axis block: write only _pending-conflict.md (the explicit ephemeral exception per fr-rf-015), exit non-zero, no authoritative state (spec.xml, details/). On non-R3 blocks: terminal output only, exit non-zero, zero filesystem state. If you find yourself wanting to fill an unbound axis with a "sensible default", trim history, write a block report, or add a --force flag, stop and surface the underlying need to the user instead.
Third authorization source (attended-only). A status: accepted ledger entry in specs/<spec-id>/decisions.yml that carries ratified_by (minted by arcforge ratify) is a valid authorization source for a concrete MUST — but ONLY in attended mode (ARCFORGE_MODE=attended). In unattended mode this third source cannot be produced by the agent, and the three legal moves (see Phase 5's "No invention without authorization" section and the Mode-Split subsection) are unchanged. Authorization granularity is the VALUE, not the decision-id: citing an accepted decision authorizes ONLY the exact values listed in its authorized_values that the human confirmed at ratify, never arbitrary values derived from the decision's prose. A <trace>D-NNN:value</trace> cites a specific value from authorized_values; that exact value must appear in the accepted entry's list.
REQUIRED BACKGROUND:
Read ${ARCFORGE_ROOT}/scripts/lib/sdd-schemas/spec.md before producing any spec.xml (primary form) — it carries the canonical identity-header schema (required fields, supersedes format, delta-element rules), auto-generated from ${ARCFORGE_ROOT}/scripts/lib/sdd-utils.js's SPEC_HEADER_RULES. The CLI alternative node "${ARCFORGE_ROOT}/scripts/lib/print-schema.js" spec produces equivalent content. This is the single source of truth — no templates, no hand-authored examples, no drift.
references/spec-structure.md — supplementary field tables for per-spec directory layout and detail-file requirement rules. Load when about to write files in Phase 5.
Overview
Transform design documents into structured XML specifications: raw source (design.md) → live contract (spec.xml). The spec becomes Source of Truth — downstream skills read it directly, never the design doc.
Boundary
arc-refining owns formalizing design docs into authoritative specs/<spec-id>/spec.xml and details/*.xml. It does not own completion-claim verification (that is arc-verifying) and it does not own post-implementation spec sync or spec/code drift reconciliation (that is the optional, separate, future arc-syncing-spec workflow — never folded into the SessionStart bootstrap or the arc-using router).
When NOT to Use
No design doc exists yet (run /arc-brainstorming first)
Task is small enough that a structured spec is overhead
Spec is already authoritative and the work is reconciling it with post-implementation reality — that is the arc-syncing-spec job (separate, opt-in workflow), not refiner
Core Rules
ask, don't assume / iterate — never invent requirements; ask 2–3 clarifying questions per iteration and complete the quality checklist before writing any files.
source of truth — spec.xml is authoritative; downstream skills quote it, never the design doc.
R2 unidirectional — refiner MUST NOT write to docs/plans/. On non-R3 blocks (DAG gate, design-doc validation, identity-header validation), refiner writes nothing — terminal output and non-zero exit only. On R3 axis blocks (Phase 4 axis-1/2/3, Phase 5.5a self-contradiction, Phase 5.5b axis-3-LLM, Phase 6b mechanical-auth-check), refiner writes ONLY the ephemeral specs/<spec-id>/_pending-conflict.md — never spec.xml, never details/. The Iron Law's "NEVER WRITE AUTHORITATIVE STATE ON BLOCK" governs both cases.
Phase 0 — Locate Inputs
If the user has not provided a spec-id, scan specs/ and docs/plans/ to present available targets and ask the user to choose.
Once you have the spec-id, locate the design doc at docs/plans/<spec-id>/<date>/design.md.
Phase 1 — DAG Completion Gate (when prior spec exists)
Before producing a new spec version, verify that the prior sprint is complete. This gate lives in the refiner — not the planner — so the wiki layer can never reach an inconsistent state where spec_version is at v(N+1) while v(N)'s DAG is still running.
No prior spec → skip this phase. v1 formalization has no prior sprint to be incomplete.
Prior spec exists → run the gate check:
: "${ARCFORGE_ROOT:=$HOME/.agents/arcforge}"
node "${ARCFORGE_ROOT}/scripts/cli.js" sdd-gate dag --spec-id <spec-id>
Reads the stable JSON, giving three outcomes:
dag: null (no dag.yaml) → proceed. Legal: refined but not yet planned.
status: "pass" (exit 0, all epics "completed") → proceed with the new iteration.
status: "block" (exit 1) → BLOCK. dag.incompleteEpics lists the unfinished epics; print them plus "Complete current sprint before iterating.", exit non-zero, write no files (no spec.xml, no details/, no report).
No escape hatch
When the gate blocks, the user has exactly two paths: (a) complete the remaining epics (status → completed), then re-run refiner; or (b) abandon the spec by deleting specs/<spec-id>/, then start over. There is no --force flag, no abandoned epic status, no override, no partial-abandonment mechanism. If you find yourself wanting to add an escape hatch, stop and surface the underlying need to the user instead.
If valid is false and any issue has level: 'ERROR' — BLOCK. Print the issues to terminal, exit non-zero, write no files. Do not write any report file.
If valid is false with only WARNINGs — proceed but surface the warnings to the user.
If valid is true — proceed.
Phase 2.5 — Vision and Decision-Ledger Context (D6)
After input validation passes, load vision and ledger context (read-only), then validate them.
2.5a — Load Context
If specs/<spec-id>/vision.md exists, read it as context (long-horizon intent). If specs/<spec-id>/decisions.yml exists, read it as context (recorded decisions and their status). Both are read-only inputs: do NOT write to vision.md, and do NOT edit existing ledger entries — the B2 immutability hook will deny any such write.
2.5b — Validate Vision and Ledger (sdd-gate context)
The gate chains three sub-checks — vision, ledger (append-only against HEAD), then spec↔decision↔anchor graph. status: "pass" (exit 0) → proceed; status: "block" (exit 1) names the failing sub-gate in gate and lists errors. No-op rule: when decisions.yml, vision.md, and spec.xml are all absent, the gate MUST PASS (only present files are validated). Writes no files. On ERROR: BLOCK — terminal output only, exit non-zero, no files (non-R3 block).
Phase 3 — Detect Behavior Context
Check the filesystem for a prior spec at the canonical path:
specs/<spec-id>/spec.xmlexists → this is an iteration; the design doc must contain Context + Change Intent sections.
specs/<spec-id>/spec.xmldoes not exist → this is the first formalization (v1); the design doc carries prose with problem / solution / requirements / scope.
This is one refiner behavior with conditional fields based on filesystem state — not two modes. The filesystem is the single source of truth for which sections to expect. When a prior spec exists, the design doc MUST have both Context and Change Intent sections; missing either is ERROR — block with: "Iteration design doc must have Context and Change Intent sections — re-run brainstorming with the prior spec in scope."
When the design doc's date folder is older than or equal to the spec's recorded design_iteration, produce a WARNING: "design iteration <date> is not newer than spec source <spec-date> — this may be a stale design doc."
Before drafting the spec, read the design doc and the brainstorming Q&A decision-log in full, then check three axes. R3 fires when ANY axis surfaces a contradiction.
Axis 1 — design.md internal contradictions.
Contradictory requirements within the design. Print both requirement IDs to terminal — e.g., REQ-A requires "sessions expire after 15 minutes" and REQ-B requires "sessions never expire" is an axis-1 contradiction; terminal output MUST name both REQ-A and REQ-B with a pointer to specs/<spec-id>/_pending-conflict.md.
When prior spec exists: contradiction between new design requirements and existing spec requirements.
Broken dependencies (requirements that depend on removed requirements).
Axis 2 — design.md ↔ user Q&A answers.
If design says X and a user Q&A row says ¬X, the conflict is unresolved. Refiner does not silently pick one — silently picking either side is forbidden even if the Q&A answer is more recent than the design. Terminal output MUST cite both the design line range and the Q&A row q_id. Example: design says windowSec: 60; Q&A row says "use windowMs for consistency" → axis 2 fires. Authoring a reconciled middle ground (windowMs: 60000) without surfacing the conflict is the failure mode this axis catches.
Axis 3 — spec-draft coverage (deferral and invention).
Every criterion the refiner is about to draft must trace to a (design phrase ∪ Q&A row) source. A criterion with no such source is invention; under R3, it does not belong in the spec.
Deferral signals in Q&A ("use defaults", "covered.", "skip", "you decide", and similar) DO NOT authorize concrete MUSTs. A deferred axis is unbound, not "implicitly authorized via training-data common practice".
On any axis firing — BLOCK. Print to terminal:
Which axis fired (1, 2, or 3) and a one-line description of the conflict.
The specific design line ranges and Q&A row q_ids involved (so the user can locate them without re-reading the whole design).
1–3 candidate resolutions the user can pick from when re-running brainstorming. Provide AT LEAST 1 and AT MOST 3 — the writer enforces this range. Examples per axis:
Axis 1: (a) keep requirement A, drop B; (b) keep B, drop A; (c) widen scope so both hold under disjoint conditions.
Axis 2: (a) keep design wording, edit Q&A row; (b) accept Q&A answer, edit design; (c) make the axis configurable so both stances coexist.
Axis 3: (a) downgrade the criterion to SHOULD/MAY citing design's qualitative phrase; (b) leave the axis unbound; (c) ask user to specify a concrete value in a new design iteration.
Before exiting non-zero, MUST write the conflict handoff file (fr-rf-015-ac1) by piping the conflict payload as JSON to the conflict gate stage. The heredoc keeps the payload off disk until the CLI writes the canonical file:
All four payload keys (per PENDING_CONFLICT_RULES) are mandatory; reproduce them exactly (no synonyms), a missing/empty field exits non-zero:axis_fired is "1"/"2"/"3" (invention, Phase 5.5a, and Phase 5.5b all use "3"); conflict_description names the design line ranges and Q&A q_ids; candidate_resolutions is a list of 1–3 (never zero, never >3) user-pickable resolutions; user_action_prompt is always Run /arc-brainstorming iterate <spec-id> to resolve this conflict.
The schema source of truth is PENDING_CONFLICT_RULES (from ${ARCFORGE_ROOT}/scripts/lib/sdd-utils). The file is written at specs/<spec-id>/_pending-conflict.md (echoed back as conflict_marker in the gate JSON). It is ephemeral — brainstorming Phase 0 reads it as Change Intent seed, then deletes it on successful new-design write; refiner does NOT clean it up. A malformed payload (missing required field, zero resolutions) exits non-zero and writes nothing.
MUST NOT write _pending-conflict.md for non-R3-axis blocks — the DAG completion gate, design-doc validation, and identity-header validation are pipeline-mechanical or programmer-error blocks, not axis contradictions: terminal output only, exit non-zero, no file written.
On an R3 axis block: the _pending-conflict.md is the only file written — no spec.xml, no details/, no report. The user routes through /arc-brainstorming iterate <spec-id> to author a new dated design.md; refiner re-runs against it, no stale state to clean up.
Ask at least 2–3 clarifying questions when gaps or ambiguities (not contradictions) surface — gaps are unbound axes (legal under axis 3), not R3 triggers.
Phase 5 — Draft Spec In Memory (Two-Pass Write)
Build the complete spec.xml and all specs/<spec-id>/details/*.xmlin memory before writing any file to disk. This is the two-pass write pattern: build in memory → validate → write atomically only if valid.
No invention without authorization
Refiner MUST NOT author criteria from training-data inference. When a design phrase is qualitative ("rate-limited", "fast", "secure") or a Q&A row defers ("use defaults", "covered.", "skip", "you decide"), the legitimate refiner moves are exactly three:
Preserve design's qualitative phrasing as SHOULD/MAY. The source phrase is in design.md — that is the authorization. SHOULD/MAY signals "non-binding hint" without inventing a concrete number. The <trace> cites the qualitative phrase in design.md.
Leave the axis unbound. No criterion at all on that axis. Downstream stages (planner, implementing) may surface the unbound axis as a planning question; refiner does not pre-answer it.
BLOCK with candidate resolutions. When ambiguity is large enough that neither (1) nor (2) is honest — for example, the design's qualitative phrase is so vague that any SHOULD wording would itself be invention — route the user through brainstorming via Phase 4's block flow.
Inventing a concrete MUST from training-data common practice ("most rate-limiters use 60-second windows, so MUST window=60s") is not on this list — it violates the Iron Law's first clause.
Deferral signals. A Q&A row carries deferral_signal=true when its user_answer_verbatim matches a canonical phrase per DECISION_LOG_RULES.deferral_signal_canonical_phrases ("use defaults", "covered.", "skip", "you decide"). A deferred axis is unbound; deferral does NOT authorize a concrete MUST — the same three legitimate moves apply.
Every concrete MUST must be sourced. For every concrete MUST, point to a non-deferral source — a design phrase containing the concrete value, or a Q&A row whose user_answer_verbatim contains it with deferral_signal=false. No such source = invention; use one of the three moves instead. mechanicalAuthorizationCheck (in ${ARCFORGE_ROOT}/scripts/lib/sdd-validators.js) verifies this at Phase 6, so any invention drafted here is caught and blocks downstream.
Field tables (identity header, per-spec directory layout, detail-file requirement rules, unchanged-requirements rule) are in references/spec-structure.md. The decision logic below (wiki-style delta accumulation, version increment semantics) stays here.
Mode-Split: Unattended vs. Attended
The refiner reads ARCFORGE_MODE from the environment (set by the calling environment — NOT agent self-report). Any value other than attended is treated as UNATTENDED. The default when the variable is absent is UNATTENDED.
UNATTENDED path (default, byte-for-byte the same as before D6). On a deferral or unbound/qualitative axis, the three legal moves above apply without change: downgrade to SHOULD/MAY, leave unbound, or BLOCK via _pending-conflict.md. In addition, the refiner MUST NOT take any of these actions in unattended mode:
MUST NOT write a status: accepted ledger entry.
MUST NOT self-ratify (i.e., set ratified_by on any entry without the arcforge ratify command having run).
MUST NOT treat a D-NNN: decision-trace as authorization for a concrete MUST unless the referenced entry already has status: accepted and ratified_by — which the agent itself cannot produce in unattended mode.
No "agent self-labels low-risk → auto-accept" escape hatch exists.
ATTENDED path (ARCFORGE_MODE=attended) — draft-then-ratify. When the refiner is in attended mode and encounters a deferral signal ("you decide", "use defaults", "covered.", "skip") or an unbound/qualitative axis:
Draft a status: proposed ledger entry in specs/<spec-id>/decisions.yml with authorized_values as a structured list (not prose). This records what the refiner would do but does NOT authorize any concrete MUST yet.
Commit the drafted ledger entry before stopping, so the proposed decision survives the session boundary:
Stop and instruct the human: print "Run arcforge ratify <spec-id> D-NNN to authorize the proposed values before this criterion can be written as a MUST."
Do NOT author the concrete MUST until a ratified (status: accepted + ratified_by) entry exists in the ledger.
Once ratification has occurred (the human has run arcforge ratify), the refiner may cite <trace>D-NNN:value</trace> where value is an exact item from authorized_values — the value the human confirmed at ratify.
The refiner NEVER mints an accepted entry itself and NEVER authors the concrete MUST without a pre-existing ratified entry. The unattended behavior is unchanged; the attended path only adds a draft-then-ratify exit rather than unconditionally leaving the axis unbound or blocking.
For how attended mode is opted into, how the human resolves and runs arcforge ratify under a plugin install, and where draft-then-ratify sits in the end-to-end pipeline, see ${ARCFORGE_ROOT}/docs/guide/sdd-pipeline.md.
Version Increment (when prior spec exists)
spec_version = previous version + 1
supersedes = <spec-id>:v<previous-version>
source/design_path and source/design_iteration point to the NEW design doc
Delta Elements — Wiki-Style Accumulation
<overview> accumulates all <delta> elements ever written. Each iteration appends one new <delta> as the last child of <overview>. Refiner MUST preserve every prior <delta> element verbatim — no overwrite, no merge, no deduplication, no rewrite. Earlier deltas are historical record, frozen at the moment they were appended.
delta.iteration MUST equal the new source/design_iteration
<added> and <modified> ref MUST correspond to a real requirement in current detail files
<added> and <modified> items SHOULD carry a decision attribute pointing to the relevant ledger entry when a specs/<spec-id>/decisions.yml entry exists that authorized the addition or change. Example: <added ref="fr-foo-001" decision="D-003" />. Use the D-id of the proposed or accepted ledger entry that captures the rationale. Omit the attribute when no ledger entry covers this item.
<removed> MUST include a <reason> child; <migration> is optional. The implementer LLM reads both as teardown guidance — phrase them with that reader in mind, not just for human archive purposes.
<renamed> is body-unchanged only — ref_new MUST exist in current detail files; semantic changes use <removed> + <added>, never <renamed> + <modified>.
For the first formalization (no prior spec): no <delta> element. Its absence signals "plan all requirements" to the planner.
For v2+: the new delta is appended after the prior delta(s). The resulting sequence MUST be ordered ascending by version. Both parsed.deltas (full array) and parsed.latest_delta (highest version) are exposed by parseSpecHeader for downstream consumers.
Phase 5.5 hosts two independent checks. Both can block; their block behaviors differ.
5.5a — Self-Contradiction Sub-Pass
Before Phase 6 output validation, re-read each requirement's <description> against each <criterion> (and against sibling criteria). Two failure modes to flag:
Scope mismatch. Description says "the system handles X" (covering both success and failure paths), but ACs only test the success path. The description's scope and the AC set's coverage diverge — readers will infer requirements that the spec does not actually test. Remediation hint: "widen ACs to cover failure path, or narrow description to match ACs."
RFC-2119 verb mismatch. Description uses MUST but a sibling AC for the same axis uses SHOULD (or vice versa). The verb's strength must be consistent across description and ACs for the same axis. Mismatches signal copy-paste drift between drafting passes. Remediation hint: "align verbs across description and ACs for the same axis."
If any requirement fails this sub-pass — BLOCK (R3 severity, MUST NOT downgrade to WARNING). Before exiting non-zero, run the Phase 4 sdd-gate conflict heredoc with axis_fired: '3', a conflict_description of '<requirement ID>: <scope or verb mismatch> — <remediation hint>', 1–3 candidate resolutions, and the standard user_action_prompt. Print the requirement ID and mismatch to terminal; write no authoritative files. Self-contradiction is not exempted from the single R3 recovery surface.
5.5b — Axis-3 LLM Judgment Pass
Re-read each criterion in the in-memory draft and verify it traces to a (design phrase ∪ Q&A row) citable source (the LLM-judgment layer of axis 3; Phase 6's mechanicalAuthorizationCheck is the mechanical follow-up over <trace> elements). Criteria with no citable source — BLOCK (R3 severity, MUST NOT downgrade to WARNING): run the Phase 4 sdd-gate conflict heredoc with axis_fired: '3', print which criterion has no source plus 1–3 candidate resolutions, exit non-zero. _pending-conflict.md is the only file written.
Phase 4 catches conflicts between the design inputs; Phase 5.5 catches the spec-to-be contradicting itself (5.5a) or having invented criteria (5.5b) — both write _pending-conflict.md, the single recovery surface for every R3 BLOCK.
Before writing any file to disk, validate the in-memory spec. Pipe the in-memory
draft spec.xml to the header gate stage over stdin (heredoc) — the draft never
touches disk, preserving zero-filesystem-state-on-block:
The header stage reads only the <overview> block, so the single spec.xml suffices (the in-memory details/*.xml are not inputs). status: "pass" (exit 0) → continue to 6b; status: "block" (exit 1) → the issues array carries the ERROR findings. Phase 6 runs two checks:
6a — Identity-header validation (non-R3 block):validateSpecHeader verifies that spec_id, spec_version, status, source, and scope are all present and well-formed; any missing/malformed field is ERROR.
Any level: 'ERROR' — BLOCK (no conflict file). Print findings with remediation to terminal, exit non-zero, write no files. Do NOT write _pending-conflict.md — header errors are schema/programmer errors, not axis contradictions.
Pipe the combined in-memory draft to the authorize gate stage. The mechanical check reads <requirement>/<criterion>/<trace> elements, which live in the details/*.xml content — so the input is the full Phase 5 draft (overview + every requirement + every <trace>) as a single concatenated XML stream, before the two-pass write splits it into spec.xml + details/. On a failed check the CLI deterministically writes specs/<spec-id>/_pending-conflict.md with axis_fired: '3' and the unauthorized-trace summary — the agent does NOT hand-build the marker here:
The stage loads the ledger from specs/<spec-id>/decisions.yml automatically.
status: "pass" (exit 0) → both checks passed. status: "block" (exit 1) →
unauthorized_traces lists the flagged criteria and conflict_marker echoes the
path of the written file.
If the authorize stage returns status: "block" — BLOCK (conflict file written by the CLI, per fr-rf-015-ac1), exit non-zero. Write no authoritative files (no spec.xml, no details/) — only the _pending-conflict.md the CLI produced.
If both checks pass: write all files atomically: spec.xml and all details/*.xml in a single operation. Partial writes (spec.xml written but details/ incomplete) MUST NOT occur.
Quality Checklist
Before writing files, confirm:
every requirement has at least one acceptance criterion with a <trace> element
every <trace> points to a real source — a design.md line range that contains the cited content, or a Q&A row q_id whose user_answer_verbatim contains the cited content (no invention from training data)
every concrete MUST has an authorizing source — design phrase or non-deferral Q&A answer; deferral signals do NOT authorize concrete MUSTs
no vague language — use MUST/SHOULD/MAY per RFC 2119
all requirement IDs are unique across all detail files
all <detail_file path="..."> references point to files that will be written
for v2+: supersedes field present; format <spec-id>:v<N>
new <delta> element present and well-formed (when prior spec exists): version/iteration match, all refs resolve
every prior <delta> is preserved verbatim — <overview> contains the full ascending sequence
new <delta> is the last child of <overview>
Phase 4 three axes all clean (design internal, design ↔ Q&A, criterion coverage)
Phase 5.5a sub-pass clean (no description ↔ AC scope or verb mismatches)
Phase 5.5b axis-3 LLM judgment clean (every criterion has a citable source)
Phase 6a identity-header validation passed (validateSpecHeader returns no ERROR)
Phase 6b mechanical authorization check passed (mechanicalAuthorizationCheck returns valid: true — every resolves to design.md content, decision-log content, or a ratified ledger value ( entry with + , cited value in ))
Red Flags — Stop
"user seems happy, let's proceed"
"I can make reasonable assumptions about missing requirements"
"we can refine this in implementation"
"skipping clarifying questions"
"I'll just write a quick refiner-report.md so the user knows what blocked"
"I'll force past the DAG gate this once"
"I'll trim the older deltas — they're noise"
"user said 'use defaults' / 'covered.' / 'skip', so I'll pick a sensible value"
"training data shows most systems do X, so MUST X"
"design says X and Q&A says ¬X, but Q&A is more recent so I'll use that" (axis 2 silent pick)
"the criterion is obviously implied by the design's wording" (no <trace> source = invention)
"this scope mismatch between description and ACs is minor, ship it"
All mean: stop. Keep asking until checklist complete and user confirms. On R3 axis block: write _pending-conflict.md then exit non-zero — no authoritative files. On all other blocks: terminal + exit only — zero files. No escape hatch from the gate. Prior deltas are preserved verbatim. No invention from training data; no silent picks across design/Q&A conflicts; no shipping a spec that contradicts itself.
