# Align

> Alignment scorecard (`/align`)

- Skill: `opendatadiscovery/align` (Agent Skill)
- Install (CLI): `npx skillmds@latest add opendatadiscovery/align`
- Raw SKILL.md: https://api.skillmd.com/api/skills/opendatadiscovery/align/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: opendatadiscovery (https://skillmd.com/u/opendatadiscovery)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/opendatadiscovery/align

---


# Alignment scorecard (`/align`)

The cross-corpus consistency dashboard. A **deterministic roll-up — no LLM, no
subagents** in default mode — over the already-derived ontology + ground-truth
anchors. It answers the maintainer's standing question:

> *What is the level of alignment between documentation, ADRs, the codebase, and
> the tests — and what blocks us from building the contract tests that pin
> doc-claims to implementation?*

It does **not** re-derive anything (that's what `/enrich`, `/concepts`,
`/find-implicit-adrs`, `/doc-gap-check`, `/test-coverage`, `/reflect-feature`
produce). It **joins** those outputs + the graph, computes bi-directional
coverage ratios, and scores them. The expensive agentic re-verification is the
separate `--deep` mode (phase 2).

## What it measures (5 dimensions)

| Dim | Question |
|---|---|
| **A** Ontology ↔ Code | is the ontology a fresh, faithful mirror of code? (substrate freshness, enrichment, axis integrity) |
| **B** Ontology ↔ Doc (bi-dir) | *if docs claim it, does code exist?* (DESCRIBES→code resolution) · *if implemented, is it documented?* (features with inbound DESCRIBES) · open DocGaps · doc drift |
| **C** Ontology ↔ ADR | published ADRs ingested · REALISES code links · candidate disposition |
| **D** **Test-Traceability Ledger** | **no orphan tests** (every test/gap carries a typed gate) · ADRs enforced · features validated · bugs/scopes regress-guarded · probe execution + named-integration stacks |
| **E** Trust meta-gate | graph freshness · embeddings on? · latest `/panel` verdict · **reflection coverage** (the discount on every alignment claim) |

**The honesty rule (hard-coded):** every alignment metric is reported as
`aligned / checked / total`. A low contradiction count is rendered as
"UNKNOWN over N%", never "aligned" — because the layer that proves alignment
(feature-reflection) has run on <1% of features. The score cannot hide a blind
spot. The top line is a **Contract-Test Readiness verdict** (NOT-READY /
PILOT-READY / READY) + explicit blockers + the **ready-now subset** (what is
fully bridged and contract-testable today).

The Test-Traceability Ledger implements `feedback_tests_as_deterministic_gates`:
a test is never a free-floating item — it `enforces`→ADR / `validates`→Feature /
`regresses`→Finding-Issue / `guards`→RefactoringScope, checked bidirectionally
(every test has a gate; every test-worthy subject has a test or a gated gap).

## Argument forms

| Form | Behaviour |
|---|---|
| `/align [<repo>]` | **Default** (repo defaults to `odd-platform`). Compute the scorecard from the canonical files NOW (fresh `load_substrate` + `project`, independent of the last graph-build), write `alignment-scorecard.{md,yaml}` (the `.yaml` appends one trend row), print the summary + the top action. Cheap + idempotent — the periodic heartbeat. |
| `/align --show [<repo>]` | Read-only. Print the existing `lineage/{repo}/alignment-scorecard.md` (no recompute). |
| `/align --json [<repo>]` | Emit the machine payload (the written YAML) to stdout for downstream tooling. |
| `/align --deep [<repo>]` | **Phase 2 — not yet built.** The agentic contract audit: fan out subagents to *sample-verify* the cheap signals — re-fire `reflect-feature` on the highest-value un-reflected features, sample Doc→Code claims for live verification, drift-check each ADR's `REALISES`. Each finding logged as a gated `TestGap` via `playbooks/follow-up-on-disk.md`. Until built, the skill says so and runs the default mode. |

## Procedure (default mode)

1. Run `uv run --project lineage/_extractor lineage-extractor alignment <repo>`
   (deterministic; ~15 s; reads the canonical files + the built graph's
   `build-info.yaml` + git HEAD + the published ADR pages + the probe corpus).
2. Read back `lineage/{repo}/alignment-scorecard.md` and relay to the maintainer:
   the readiness verdict, the blockers, the per-dimension grades, the ready-now
   subset, and the top 3 actionable items.
3. If any dimension is RED for a *new* reason vs the prior `trend` row, call it
   out as a regression. The trend series is the periodic-monitoring surface.

## When to run

- **Per sprint checkpoint / milestone** — alongside `/panel` (which audits the
  *methodology*; `/align` audits the *ontology's fidelity* — complementary, and
  `/align` consumes the latest `/panel` verdict in its trust gate).
- **After a batch of `/enrich` + reducers** — to see whether coverage moved the
  alignment numbers.
- **Before starting contract-test work** — the readiness verdict + ready-now
  subset tell you exactly where to aim, and the actionable items name the
  blockers (Phase-4 Test layer, reflection coverage, ADR re-ingest, etc.).

On-demand only — **no daemon, no schedule** (APPROACH.md Rule 12; local-only).

## Outputs

- `lineage/{repo}/alignment-scorecard.md` — human, diffable, committed.
- `lineage/{repo}/alignment-scorecard.yaml` — machine metrics + `trend:` series
  (last 50 runs), committed.

## Cross-references

- `lineage/_extractor/src/lineage_extractor/alignment.py` — the implementation.
- `feedback_tests_as_deterministic_gates` (memory) — the Ledger's spine.
- `adrs/drafts/ground-truth-lineage.md` — Phase 4 (the `Test` layer the readiness
  verdict gates on).
- `lineage/GRAPH-TOPOLOGY.md` — the labels + edges rolled up here.
- `/panel` — the complementary methodology meta-review.