Align

Generated from workflows/modes/align.md, the mode contract the HELIX skill loads. Edit that file, not this page.

Use for reconciliation, traceability audits, drift checks, and artifact content placement reviews.

Start from authority: vision, PRD, features/stories, architecture/ADRs, designs, tests, implementation plans, code. The spec stack is the contract; code is a projection of it. Traceability is bidirectional: every material code surface (route/screen/CLI/API/job/migration) traces to a governing artifact, and every acceptance criterion traces to an exercising test. Unmapped material surfaces and unimplemented criteria are both alignment findings.
Desired-state rule (with intent guard). Specs describe the desired future state. Code behind specs → residual tracker work items, not silent requirement shrinks. Code ahead of docs → classify as plan-to-code honesty (STALE_PLAN / honesty evolve). Evolving specs to match code requires operator intent (explicit request or approved handoff) — do not auto-bless unapproved implementation as plan authority. Code reflects state; it does not redefine plan alone.
Reconstruct intent from planning artifacts before inspecting lower layers.
Classify each gap as ALIGNED, INCOMPLETE, DIVERGENT, UNDERSPECIFIED, STALE_PLAN, or BLOCKED.
Produce one durable alignment report when the action is more than a conversational review. The report must remain reviewable by a human in under ten minutes. Prefer the alignment-review template under the catalog (workflows/templates/alignment-review.md or the package references/templates/ path when present).
For every non-aligned gap (INCOMPLETE, UNDERSPECIFIED, DIVERGENT, STALE_PLAN), the handoff names all four fields defined in modes/_report.md (destination type, deliverable, next mode, evidence); never a CLI command.
Create or identify follow-up work for every non-aligned gap using those handoff fields. Evidence-gated implement work: before filing build/implement items, require concrete residual evidence (paths, tests, commands). Prefer story/AC floor items when only docs/traceability lag. “Residual already green” means a governing AC is exercised by a passing test (or a recorded exception). Close or re-scope only with that evidence.

Content migration ledger

If a user asks whether content belongs in the right HELIX document, use align mode. The alignment output must include a content migration ledger for every misplaced content unit:

Field	Required content
Source	Artifact path and line references
Content unit	Small named chunk of content
Classification	`keep`, `move`, `split`, `delete`, `needs-new-artifact`, or `decision-needed`
Destination	Exact destination artifact path or artifact type
Content to add	Destination-shaped draft content
Template fit	Destination section and blocking/warning checks
Destination risks	Any template check the proposed addition would fail
Follow-up	Tracker issue ID or explicit issue to create

Do not remove content from one artifact unless the destination content and follow-up work are captured durably.

Procedure: workflows/actions/reconcile-alignment.md (deeper step detail; this file is the contract).

End with the modes/_report.md block, mode: align.

Fan-out

When the host can run sub-agents, split the review and fan in through the report shape in modes/_report.md:

One agent per review dimension of the alignment procedure (artifact contract rubric, bidirectional traceability, ADR honoring, concern drift, concern realization, NFR targets, slot registry integrity, acceptance criteria, instrument integrity, quality evaluation, work-item coverage), or for a large tree one agent per artifact family (discover and frame, design, test, deploy, iterate).
Every agent gets the same scope root, the same catalog bind, and the governing artifacts its dimension needs, and returns only a helix_report block: findings with classification, artifact, lines, evidence, and the four handoff fields.
Fan in: merge the blocks; drop duplicates that share artifact, lines, and classification; when two agents classify one gap differently keep the stricter classification and record the disagreement under assumptions; renumber finding ids; recompute the summary counts; then write the one prose report a human reviews in under ten minutes.
Without sub-agents, run the dimensions in order. The output shape is the same either way.

Fan-out never widens scope. An agent that reads outside the scope root is discarded, and no agent writes an artifact; align stays read-only until the handoff.

Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition: model-primary
Issuer: HELIX helix
Signing key: ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source: reference/workflow-modes/align.md
Signed: 2026-09-23T14:11:58Z
Content digest: sha256:aa097924…543e0e62

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON

{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-09-23T14:11:58Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/reference/workflow-modes/align/",
        "digest": {
          "alg": "sha256",
          "value": "aa097924f59c36d0c144ab94cfcf70e3a2db6a236e212860779badad543e0e62"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "LZCMs0FdK4G9xyjG1P7-SwZyBv9jTwYGpNfwwp-oH7hJPUV0TZ5YRLUv1ytPtW1QVTFqJcrp8r2FBvOkh9A7CQ",
      "signed_at": "2026-09-23T14:11:58Z"
    }
  ]
}

attestation file · issuer keys