Alignment Reader

Alignment Reader

Thin wrapper around ${CLAUDE_PLUGIN_ROOT}/scripts/alignment-read.sh. The script parses alignment.md per the canonical grammar in references/alignment-contract.md v1.4 and emits structured JSON. This skill gives the parser a Skill-tool-callable name and documents the invocation contract.

Contract

Input: one argument — absolute path to a task folder (the one containing alignment.md).

Output: single JSON object to stdout per references/alignment-contract.md. Exit code always 0 except for unrecoverable read failures (permission denied, IO error).

Fields:

• file_exists — boolean
• file_path — path to expected alignment.md
• task_name — from H1 # Alignment: <name> line (or **Task:** metadata fallback)
• created — from **Created:** <YYYY-MM-DD> metadata
• schema_version — JSON string, currently "1.0"
• sections.{task_level,phase_1,phase_2,phase_3} — each either {present: false} or a populated object with goal, expected_result, success_criteria[], success_criteria_prose, non_goals[], non_goals_prose, extras[], fields_missing[]. The two *_prose fields hold the raw body when it was written as prose instead of a list, and are null otherwise.
  • Each success_criteria[] item: {text, checked, verification, author, id}. verification is a string or null (v1.1, from — verify: <how>). author is "owner", "designer", or null (v1.3, from — by: <owner|designer>) — null means no author was recorded, not that the owner wrote it. id is "c<n>" or null (v1.4, from — id: c<n>); null means no id was recorded on that criterion.

A null id does not by itself send a resolver to task.md. scripts/contract-resolve.sh reads Task-Level ids only. It resolves from alignment.md when at least one Task-Level criterion carries an id, and reports the rest as unmarked — criteria that are invisible to coverage. It falls back to task.md only when no Task-Level criterion carries one. An id on a phase section is parsed and returned here, but no resolver reads it, so putting ids on phase criteria has no effect.

• warnings[] — array of {code, …} observations

Defensive posture (never throws)

Invocation

"${CLAUDE_PLUGIN_ROOT}/scripts/alignment-read.sh" "/abs/path/to/task/folder"

Parse with jq. Examples:

OUT=$("${CLAUDE_PLUGIN_ROOT}/scripts/alignment-read.sh" "$TASK_DIR")
EXISTS=$(jq -r '.file_exists' <<<"$OUT")
TASK_GOAL=$(jq -r '.sections.task_level.goal // empty' <<<"$OUT")
CRITERIA_COUNT=$(jq '.sections.task_level.success_criteria | length' <<<"$OUT")
# Any warnings at all?
jq -e '.warnings | length > 0' <<<"$OUT" >/dev/null && echo "warnings present"

Phase-level sections

Phase sections (phase_1, phase_2, phase_3) are OPTIONAL. A new task's alignment.md typically contains only ## Task-Level; phase sections are appended as the task enters each phase (by /research, /design, /implement).

Consumers checking "is the Phase 2 contract authored yet?" should test .sections.phase_2.present == true — not whether the section object exists (it always exists as {present: false} stub).

Consumers (v3.12.0+)

• /ai-dev-assistant:scope — read current state to decide overwrite/edit/cancel
• /ai-dev-assistant:research — pre-analysis hook checks whether alignment.md already exists; Phase 1 sub-step appends Phase 1 section
• /ai-dev-assistant:design — Phase 2 sub-step appends Phase 2 section
• /ai-dev-assistant:implement — Phase 3 sub-step appends Phase 3 section
• /ai-dev-assistant:complete — (future) may surface unchecked success criteria
• /ai-dev-assistant:review — Spec axis reads the Task-Level contract
• analysis-agent — indirectly informs scope_contract_recommended signal (caller reads this skill's output)
• spec-axis-reviewer — judges a change against the Task-Level success criteria
• scripts/contract-resolve.sh — resolves the criteria list, alignment.md Task-Level ids first, then task.md
• scripts/criterion-provenance.sh — reads the — by: author marker

Future consumers needing scope-contract data should call this skill rather than parsing alignment.md directly.

Do NOT

• Do not write to alignment.md from this skill. Reading only. Writes happen in the command flows (/scope, phase sub-steps).
• Do not treat non-empty warnings[] as a blocking error — warnings are observations; the parser always returns a best-effort result.
• Do not duplicate the parsing logic elsewhere. Call this skill or the script.
• Do not assume phase sections exist. Always guard on .sections.phase_N.present.

See also

• ${CLAUDE_PLUGIN_ROOT}/scripts/alignment-read.sh — the parser
• references/alignment-contract.md — canonical grammar, warning codes, JSON output contract
• project-state-reader skill (v1.0.0) — same design pattern, project-level metadata
• task-frontmatter-reader skill (v2.0.0) — same design pattern, task frontmatter