undefined

**Verify indexion is available** before proceeding. The drift gate
(Step 2.5) and validation loop (Step 3) depend on it:

```bash
indexion --version                       # must be installed
indexion kgf edges <any-source-file>     # must detect language and show edges

undefined

The output uses `### Requirement N:` and `#### N.M:` hierarchy matching
cc-sdd's expected ID format. The agent's `$kiro-spec-requirements` phase will
further refine into EARS format with acceptance criteria.

**Supported specification formats:**
| Format | Extension | KGF spec |
|--------|-----------|----------|
| RFC plaintext | `.rfc.txt` | `rfc-plaintext` |
| ISO/IEC technical document | `.spec.txt` | `technical-document` |
| Markdown (README, etc.) | `.md` | `markdown` |

undefined

**Traceability chain:** `spec align` works between documents at the
same abstraction level. For full traceability, check each adjacent pair:

```bash

Do NOT align source spec directly against design or code — the vocabulary
spaces differ too much (normative spec language vs. software design vs.
code identifiers). Each hop bridges one abstraction gap.

**Semantic fidelity review (not automatable):**

`spec align` checks vocabulary overlap, but cannot detect requirements
that **invert** the source spec's intent while using the same vocabulary.
A common failure mode:

- Source spec: "The DCTDecode filter **shall decode** JPEG data into samples"
- Requirements draft: "For DCTDecode, the decoder **shall return** an error
  indicating the filter is not yet supported"

Both mention "DCTDecode", "filter", "shall" — vocabulary matches, so
`spec align` reports MATCHED. But the requirement says the opposite of
what the spec demands. This creates a hidden gap that only surfaces when
E2E tests fail (Step 2.9).

**After `spec draft` generates requirements, review for these patterns:**

- `"not yet supported"`, `"not implemented"`, `"placeholder"`, `"stub"`
  — these indicate the draft punted on a spec requirement
- `"shall return an error"` for something the source spec says `"shall
  decode/process/convert"` — intent inversion
- Requirements that group multiple spec features into a single "unsupported"
  bucket — each spec feature deserves its own requirement

Fix these before proceeding to Step 2. Leaving them creates a false sense
of spec conformance that only E2E testing can expose.

FEATURE=<feature>
SPEC_DIR=.kiro/specs/$FEATURE
REPORT_DIR=.indexion/sdd-reports/$FEATURE
mkdir -p $REPORT_DIR

indexion spec align diff .kiro/specs/<FEATURE>/requirements.md src/<pkg>/ --format markdown --threshold 0.3
indexion spec align status .kiro/specs/<FEATURE>/requirements.md src/<pkg>/ --threshold 0.3 --fail-on drifted

indexion spec align diff .kiro/specs/<FEATURE>/requirements.md src/<pkg>/ --format markdown --threshold 0.3
indexion spec align status .kiro/specs/<FEATURE>/requirements.md src/<pkg>/ --threshold 0.3 --fail-on any

**Monitor impl progress:**

```bash

**Operational notes:**

- Always use `--json` with file redirect + `tail -f`. Piping through
  `| tail` suppresses all output until completion.
- For long prompts, write to a file and use `$(cat file.md)`. Shell
  HEREDOC with `$()` can cause stdin blocking.
- Use `/loop` (Claude Code) to poll `git log --oneline -1` + `ps`
  every 60-120s during long impl runs.

indexion spec align status $SPEC_DIR/requirements.md src/ --threshold 0.3 --fail-on drifted

indexion spec align diff $SPEC_DIR/requirements.md src/ --format markdown --threshold 0.3
indexion spec align status $SPEC_DIR/requirements.md src/ --threshold 0.3 --fail-on any

After completing each task (commit), run:
  indexion spec align diff ... --threshold 0.3
  indexion spec align status ... --threshold 0.3 --fail-on any
If DRIFTED, SPEC_ONLY, or SHALLOW items remain for the requirement
your task addresses, fix them before moving to the next task.
- DRIFTED: add spec vocabulary to public declaration doc comments
- SPEC_ONLY: implement the missing requirement
- SHALLOW: add non-trivial function implementations (>4 lines) to the
  SAME FILE where the matched type is defined. Do not add logic in a
  separate file — SHALLOW checks per-file.
When all tasks are done, spec align status --fail-on any must exit 0
with Shallow: 0.

undefined

**Recovery — never commit manually:**

When a stall is confirmed:

1. Kill the process: `kill $CODEX_PID`
2. Check what was completed: `git log`, `git status`, `git diff --cached`
3. If uncommitted work exists and tests pass, generate indexion reports:
   ```bash
   indexion spec align diff $SPEC_DIR/requirements.md src/ \
     --format markdown --threshold 0.3 -o $REPORT_DIR/align-current.md
   indexion spec verify --spec="$SPEC_DIR/requirements.md" src/ \
     --format md -o $REPORT_DIR/verify-current.md

indexion --version
indexion kgf edges <any-project-file>   # should show edges, not errors

indexion spec align diff ... --specs-dir /path/to/indexion/kgfs

undefined

**Common E2E failure modes after SHALLOW=0:**
- Type definitions exist and logic functions exist, but the pipeline
  raises errors on real input (missing encoding tables, unsupported
  font types, etc.)
- All tests pass on synthetic fixtures but fail on real files because
  fixtures don't exercise the full code path
- Functions are implemented but not wired into the top-level API

If E2E tests fail, write additional Codex prompts targeting the specific
failure. The spec align gate ensures the vocabulary stays aligned while
Codex fixes the implementation.

for FEATURE in feature-a feature-b feature-c; do
  codex exec --full-auto --json -C . \
    "$(cat $REPORT_DIR/$FEATURE/impl-phase-b.md)" \
    > $REPORT_DIR/$FEATURE/impl-phase-b.jsonl 2>&1 &
  echo "$FEATURE: $!"
done

undefined

The validation script:
1. Runs `spec verify` (vocabulary gap between spec and impl)
2. Runs `spec align diff` (requirement-level drift)
3. Runs `spec align trace` (traceability matrix)
4. Runs `spec align status` (CI-style pass/fail)
5. Injects all reports into the agent's `validate-impl` prompt
6. Agent produces GO/NO-GO decision with specific task numbers
7. On `--fix`, automatically re-runs `spec-impl` for failing tasks

undefined

**Key constraints:**
- The prompt does NOT dictate specific vocabulary to add. It provides the
  alignment reports and lets the agent determine what to fix.
- The agent must target public declarations only — private function doc
  comments are invisible to `spec align`.
- Typical: 1-2 fix cycles. If SPEC_ONLY persists, the agent may need
  guidance that the relevant public API entry point should carry the
  vocabulary (e.g. a top-level `open` function documents the full flow).

**Known blind spots:**

- **CLI entry points with no public API:** Main/entry-point modules
  often have no public declarations — all functions are private to the
  module. `spec align` extracts vocabulary only from public declarations,
  so entry-point modules always show Matched: 0 / SPEC_ONLY for all
  requirements. **Workaround:** split CLI logic into a library module
  that exposes public functions, with the entry point as a thin
  dispatcher. Align requirements against the library, not the entry point.

- **Empty doc comments:** Codex often writes doc comment syntax without
  any actual text content. These are invisible to `spec align` because
  they contain no vocabulary. The vocab fix prompt must explicitly
  instruct the agent: "Do not leave doc comments empty. Every public
  declaration must have a doc comment that describes its purpose using
  terminology from the requirements."

- **Internal-only modules (private functions):** When implementation
  logic is entirely private (not public), `spec align` cannot see it.
  This is common in filter/codec packages where a public pipeline
  function dispatches to private decoders. SHALLOW triggers on the
  type file even though logic exists. **Workaround:** either promote
  key internal functions to public (they become testable API surface),
  or consolidate spec vocabulary into the public pipeline function's
  doc comment so the requirement matches there instead.

- **Literal requirements vs. identifier matching:** Requirements that
  reference project-specific literals (package names, table numbers,
  configuration keys) will show as DRIFTED if the implementation doc
  comments don't mention the exact literal. This is usually a sign
  that the **requirements contain project-specific details that don't
  belong there** — fix the requirements to use generic descriptions,
  or accept that the vocab fix agent must propagate these literals.

- **"Fallback" framing vs. spec-mandated implementation:** When the
  agent proposes a "fallback" for an unsupported feature, verify
  whether the feature is actually required by the source specification.
  Example: TrueType font cmap table parsing was proposed as a
  "fallback" but is in fact mandated by the spec for TrueType font
  encoding resolution. Framing spec requirements as fallbacks creates
  incorrect priority and may lead to incomplete implementation.

- **Vocabulary match ≠ functional correctness:** DRIFTED=0 and
  SHALLOW=0 confirm vocabulary alignment but cannot verify that the
  implementation actually works. E2E tests (text extraction from real
  files, visual rendering comparison) are essential to catch:
  - Type definitions that compile but never execute
  - Processing pipelines that raise errors on real input
  - Coordinate transforms that produce wrong output
  - Font/encoding paths that silently return empty results

undefined

`plan reconcile` complements `spec align` in the SDD workflow:
- **spec align**: requirements.md ↔ implementation code (spec conformance)
- **plan reconcile**: implementation code ↔ documentation (doc freshness)

Use `spec align` for pre-merge gates (CI). Use `plan reconcile` for
ongoing documentation maintenance after the feature ships.

indexion spec draft <source-file-or-dir>
indexion spec draft --output requirements.md --format markdown rfc.md
indexion spec draft --profile sdd-requirement rfc.md

indexion spec verify --spec='requirements.md' src/lib/ --format md

indexion spec align diff requirements.md src/lib/ --format markdown --threshold 0.3

indexion spec align trace requirements.md src/lib/ --format json --threshold 0.3

indexion spec align status requirements.md src/lib/ --fail-on any --threshold 0.3

| `--fail-on` | Description |
|-------------|-------------|
| `none` | Always pass |
| `drifted` | Fail if any DRIFTED |
| `spec-only` | Fail if any SPEC_ONLY |
| `shallow` | Fail if any SHALLOW (type-only stubs without function implementations) |
| `any` | Fail on DRIFTED, SPEC_ONLY, SHALLOW, or CONFLICT |

indexion spec align watch --mode=diff requirements.md src/lib/
indexion spec align watch --mode=status requirements.md src/lib/

indexion spec align suggest requirements.md src/lib/ --format tasks --agent codex