oliver-kriska/claude-elixir-phoenix / plugins/rewrite/skills/architect
architect
VerifiedDesign the idiomatic Elixir architecture for a rewrite: set the compatibility bar (ADR-000), consult phx specialists on open questions, then build contexts, ledger and ADRs. Use after /rewrite:analyze.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.3 KB |
| references/compatibility-bar.md | markdown | 8.3 KB |
| scripts/ledger.py | script | 23.0 KB |
scripts/ledger.py
View on GitHub#!/usr/bin/env python3
"""Deterministic checks and counts for the rewrite ledger (.claude/rewrite/ledger.md).
check — every M-/R-/C- ID defined in analysis/*.md is the ID (or an alias) of
exactly one ledger row, rows match their table's width, verdict and
state values are valid, ADR references resolve, and every AR-NN
departure has a complete record that scopes the row.
stats — counts by verdict, implementation, evidence and departure, with the
verified numerator kept separate from retired and accepted-risk rows.
`--slice` counts the IDs the seed's acceptance cases cite and its
mechanism and contract tables list, so an ID that the prose names
for another slice is not counted. A file with no acceptance cases
counts every ID it mentions.
obligations — the acceptance cases of a slice seed, one per `- [ ] AC-NN` or
`AC-NNa` item under `## Acceptance Criteria`, with the ledger IDs each
cites. Errors: an item without an ID, a duplicate ID, a criterion
listed both bare and lettered, and a ledger ID that the slice's
mechanism or contract table names but no case cites. These cases are
the parity auditor's rows, so its denominator is fixed by the seed.
set — writes the Impl and/or Evidence cell of each row whose ID cell lists one of
`--ids`, keeping every other byte. An unknown ID or a malformed row
changes nothing. The only command that writes; it never touches a
Departure cell.
Stdlib only.
Usage:
python3 ledger.py check [--rewrite-dir .claude/rewrite]
python3 ledger.py stats [--rewrite-dir .claude/rewrite] [--ids M-01,C-04 | --slice interview.md] [--json]
python3 ledger.py obligations --slice interview.md [--json]
python3 ledger.py set --ids C-40,C-42 [--impl implemented] [--evidence pass] [--rewrite-dir .claude/rewrite]
Exit status: 0 clean, 1 ledger errors (stats too: malformed rows, no ledger table, missing
columns; set: unknown ID or malformed row, nothing written), 2 unusable input (missing ledger
or slice).
"""
import argparse
import glob
import json
import os
import re
import sys
from collections import Counter
ID_RE = re.compile(r"\b([MRC]-\d{2,}[a-z]?)\b")
ROW_ID_RE = re.compile(r"^\|\s*[*`_]*([MRC]-\d{2,}[a-z]?)\b")
# Anything shaped like an M-/R-/C- ID; one that is not ID_RE would vanish from every count.
ID_LIKE_RE = re.compile(r"\b[MRC]-[A-Za-z0-9]+\b")
SEPARATOR_RE = re.compile(r"^\|[\s:|-]+\|?$")
ADR_RE = re.compile(r"\bADR-(\d{3})\b")
CASE_ITEM_RE = re.compile(r"^\s*[-*] \[[ xX]\]\s*(.*)$")
CASE_ID_RE = re.compile(r"^[*`_]*(AC-(\d+)([a-z]?))\b")
SLICE_TABLES = ("legacy mechanism", "external contracts")
AR_RE = re.compile(r"AR-\d{2,}")
AR_FIELDS = ("owner", "scope", "rationale", "review", "approved")
PLACEHOLDER_RE = re.compile(r"^(|—|-|\?|tbd|todo|pending|none|n/a|<[^>]*>)$", re.I)
NO_DEPARTURE = ("", "none", "—", "-")
VERDICTS = {"MAP", "REPLACE", "KEEP", "SHIM", "DELETE", "UNDECIDED"}
IMPL_STATES = {"pending", "implemented", "retired"}
EVIDENCE_STATES = {"not-run", "pass", "fail", "blocked", "stale"}
def read(path):
try:
with open(path, encoding="utf-8") as fh:
return fh.read()
except OSError:
return ""
def read_required(path):
"""Contents of `path`, or None when it cannot be read (unlike read(), which returns "")."""
try:
with open(path, encoding="utf-8") as fh:
return fh.read()
except (OSError, UnicodeDecodeError):
return None
def split_row(line):
# Escaped pipes (`a \| b`) stay inside their cell.
cells = re.split(r"(?<!\\)\|", line.strip().strip("|"))
return [re.sub(r"[*`]", "", c.replace("\\|", "|")).strip() for c in cells]
def tables(text):
"""Yield (header, data_rows) for each markdown table in `text`."""
block = []
for line in text.splitlines() + [""]:
if line.startswith("|"):
block.append(line)
continue
if len(block) >= 2 and SEPARATOR_RE.match(block[1]):
yield [h.lower() for h in split_row(block[0])], block[2:]
block = []
def column(header, *names):
for name in names:
for i, h in enumerate(header):
if h == name or h.startswith(name):
return i
return None
def is_ledger_header(header):
return bool(header) and header[0] == "id" and column(header, "verdict") is not None
def rows_as_dicts(text):
"""Rows of every ledger table (an `ID` first column and a `Verdict` column), each read
with its own table's header. Returns (table_columns, rows, malformed), where
table_columns lists, per ledger table, which axis columns its header has.
A row that mentions an ID but has none in its first cell, or whose width differs
from the header, is malformed: it fails the check instead of vanishing from counts."""
table_columns, out, malformed = [], [], []
for header, lines in tables(text):
if not is_ledger_header(header):
continue
idx = {
"verdict": column(header, "verdict"),
"impl": column(header, "impl", "implementation"),
"evidence": column(header, "evidence state", "evidence"),
"departure": column(header, "departure"),
}
table_columns.append({k: i is not None for k, i in idx.items()})
for line in lines:
cells = split_row(line)
odd = nonconforming(cells[0])
if odd:
malformed.append(f"nonconforming ID {', '.join(odd)}; IDs are M-, R- or C- plus two or more "
f"digits and an optional letter: {line[:80]}")
continue
match = ROW_ID_RE.match(line) and ID_RE.search(cells[0])
if not match:
if ID_RE.search(line):
malformed.append(f"no ID in first cell: {line[:80]}")
continue
if len(cells) != len(header):
malformed.append(f"{len(cells)} cells, header has {len(header)}: {line[:80]}")
continue
def cell(key):
i = idx[key]
return cells[i] if i is not None and i < len(cells) else ""
out.append({
"id": match.group(1),
"aliases": ID_RE.findall(cells[0]),
"verdict": cell("verdict"),
"impl": cell("impl").lower(),
"evidence": cell("evidence").lower(),
"departure": cell("departure"),
"has": {k: i is not None for k, i in idx.items()},
})
return table_columns, out, malformed
def nonconforming(first_cell):
return [t for t in ID_LIKE_RE.findall(first_cell) if not ID_RE.fullmatch(t)]
def nonconforming_definitions(rewrite_dir):
"""Analysis rows whose ID cell holds an ID-shaped token the checker cannot count."""
out = []
for path in sorted(glob.glob(os.path.join(rewrite_dir, "analysis", "*.md"))):
for line in read(path).splitlines():
if line.startswith("|") and not SEPARATOR_RE.match(line):
odd = nonconforming(split_row(line)[0])
if odd:
out.append(f"{os.path.basename(path)} defines nonconforming ID {', '.join(odd)}; rename it "
"to M-/R-/C- plus two or more digits so it is counted")
return out
def defined_ids(rewrite_dir):
ids = {}
for path in sorted(glob.glob(os.path.join(rewrite_dir, "analysis", "*.md"))):
for line in read(path).splitlines():
if ROW_ID_RE.match(line):
for alias in ID_RE.findall(split_row(line)[0]):
ids.setdefault(alias, os.path.basename(path))
return ids
def structure_errors(table_columns, malformed):
"""Structural problems shared by check and stats: no ledger table, a table missing a
required axis column, malformed rows. A complete table never masks an incomplete one."""
if not table_columns:
return ["ledger.md has no ledger table (header starting `| ID |` with a Verdict column)"]
errors = []
for n, has in enumerate(table_columns, 1):
label = "ledger table" if len(table_columns) == 1 else f"ledger table {n}"
errors += [f"{label} has no '{key}' column" for key in ("impl", "evidence") if not has[key]]
return errors + [f"malformed ledger row ({line})" for line in malformed]
def risk_records(text):
"""{AR-NN: {field: value}} for each `## AR-NN` section of accepted-risks.md."""
records, current = {}, None
for line in text.splitlines():
heading = re.match(r"^## (AR-\d{2,})\b", line)
if heading:
current = records.setdefault(heading.group(1), {})
continue
if line.startswith("#"):
current = None
continue
field = re.match(r"^\s*[-*]\s*\**([A-Za-z ]+?)\**\s*:\**\s*(.*)$", line)
if current is not None and field:
name = field.group(1).strip().lower()
if name in AR_FIELDS:
current[name] = field.group(2).strip()
return records
def risk_errors(row, ar, record):
if record is None:
return [f"{row['id']}: {ar} has no section in verify/accepted-risks.md"]
errors = [f"{row['id']}: {ar} has no {name.capitalize()}"
for name in AR_FIELDS if PLACEHOLDER_RE.match(record.get(name, ""))]
scope = set(ID_RE.findall(record.get("scope", "")))
if record.get("scope") and not scope & set(row["aliases"]):
errors.append(f"{row['id']}: {ar} Scope does not list {row['id']}")
return errors
def verdict_parts(value):
return [p.strip().upper() for p in re.split(r"→|->|/", value) if p.strip()]
def check(rewrite_dir):
warnings = []
ledger_path = os.path.join(rewrite_dir, "ledger.md")
text = read(ledger_path)
if not text:
return [f"missing {ledger_path}"], []
table_columns, rows, malformed = rows_as_dicts(text)
errors = structure_errors(table_columns, malformed)
if not table_columns:
return errors, []
for n, has in enumerate(table_columns, 1):
if not has["departure"]:
label = "ledger table" if len(table_columns) == 1 else f"ledger table {n}"
warnings.append(f"{label} has no 'departure' column; accepted risks cannot be recorded")
risks = risk_records(read(os.path.join(rewrite_dir, "verify", "accepted-risks.md")))
# Only row IDs and their aliases account for a mechanism; prose mentions do not.
accounted = Counter(alias for r in rows for alias in set(r["aliases"]))
missing = [(i, s) for i, s in defined_ids(rewrite_dir).items() if i not in accounted]
errors += [f"{i} (defined in {s}) is not accounted for in the ledger" for i, s in missing]
if missing:
warnings.append("only a row's ID cell accounts for an ID, prose does not; a mechanism the "
"legacy lacks gets a DELETE row ('absent in legacy')")
errors += [f"{i} appears in {n} ledger rows" for i, n in sorted(accounted.items()) if n > 1]
errors += nonconforming_definitions(rewrite_dir)
for r in rows:
parts = verdict_parts(r["verdict"])
bad = [p for p in parts if p not in VERDICTS]
if not parts or bad:
errors.append(f"{r['id']}: verdict '{r['verdict']}' not in {sorted(VERDICTS)}")
if r["has"]["impl"] and r["impl"] not in IMPL_STATES:
errors.append(f"{r['id']}: implementation '{r['impl']}' not in {sorted(IMPL_STATES)}")
if r["has"]["evidence"] and r["evidence"] not in EVIDENCE_STATES:
errors.append(f"{r['id']}: evidence '{r['evidence']}' not in {sorted(EVIDENCE_STATES)}")
if r["has"]["departure"] and r["departure"] == "":
errors.append(f"{r['id']}: empty departure cell (write 'none' or AR-NN)")
elif r["departure"] not in NO_DEPARTURE:
if not AR_RE.fullmatch(r["departure"]):
errors.append(f"{r['id']}: departure '{r['departure']}' is neither 'none' nor AR-NN")
else:
errors += risk_errors(r, r["departure"], risks.get(r["departure"]))
if "UNDECIDED" in verdict_parts(r["verdict"]) and r["impl"] == "implemented":
warnings.append(f"{r['id']}: implemented while its verdict is UNDECIDED")
arch = os.path.join(rewrite_dir, "architecture")
refs = set()
for path in [ledger_path] + glob.glob(os.path.join(arch, "*.md")):
refs.update(ADR_RE.findall(read(path)))
for num in sorted(refs):
if num == "000":
if not glob.glob(os.path.join(arch, "ADR-000*.md")):
errors.append("ADR-000 referenced but architecture/ADR-000-*.md is missing")
elif not glob.glob(os.path.join(arch, "adr", f"ADR-{num}*.md")):
errors.append(f"ADR-{num} referenced but architecture/adr/ADR-{num}-*.md is missing")
return errors, warnings
class LedgerError(Exception):
"""The ledger is structurally invalid, so no count of it can be trusted."""
def __init__(self, errors):
super().__init__("; ".join(errors))
self.errors = errors
def stats(rewrite_dir, ids=None):
"""Counts from one parse of ledger.md. Raises LedgerError when that same parse is
structurally invalid; adds `unmatched_ids` when `ids` is given."""
table_columns, rows, malformed = rows_as_dicts(read(os.path.join(rewrite_dir, "ledger.md")))
errors = structure_errors(table_columns, malformed)
if errors:
raise LedgerError(errors)
known = {alias for r in rows for alias in r["aliases"]}
if ids is not None:
rows = [r for r in rows if set(r["aliases"]) & ids]
verdicts, impl, evidence = Counter(), Counter(), Counter()
departures = 0
verified = 0
for r in rows:
for part in verdict_parts(r["verdict"])[-1:]:
verdicts[part] += 1
impl[r["impl"] or "?"] += 1
evidence[r["evidence"] or "?"] += 1
has_departure = r["departure"] not in NO_DEPARTURE
departures += has_departure
if r["impl"] == "implemented" and r["evidence"] == "pass" and not has_departure:
verified += 1
retired = impl.get("retired", 0)
result = {
"rows": len(rows),
"verified": verified,
"denominator": len(rows) - retired,
"retired": retired,
"accepted_risk": departures,
"undecided": verdicts.get("UNDECIDED", 0),
"verdicts": dict(sorted(verdicts.items())),
"implementation": dict(sorted(impl.items())),
"evidence": dict(sorted(evidence.items())),
}
if ids is not None:
result["unmatched_ids"] = sorted(ids - known)
return result
def sections(text):
"""Map each `## ` heading (lowercased) to the text under it."""
out, title, lines = {}, None, []
for line in text.splitlines() + ["## "]:
if line.startswith("## "):
if title is not None:
out[title] = "\n".join(lines)
title, lines = line[3:].strip().lower(), []
else:
lines.append(line)
return out
def obligations(text):
"""Acceptance cases of a slice seed and the errors that make them unusable as a denominator."""
parts = sections(text)
body = next((v for k, v in parts.items() if k.startswith("acceptance criteria")), None)
if body is None:
return [], ["no `## Acceptance Criteria` section"]
items = []
for line in body.splitlines():
m = CASE_ITEM_RE.match(line)
if m:
items.append([m.group(1)])
elif items and line.strip() and line[:1].isspace():
items[-1].append(line.strip())
cases, errors, seen = [], [], set()
for item in items:
text_ = " ".join(item)
m = CASE_ID_RE.match(text_)
if not m:
errors.append(f"acceptance item without an AC-NN id: {text_[:60]}")
continue
case = m.group(1)
if case in seen:
errors.append(f"{case} is listed twice")
seen.add(case)
cases.append({"id": case, "cites": sorted(set(ID_RE.findall(text_)))})
for case in sorted(c for c in seen if not c[-1].isalpha()):
if any(c != case and c.startswith(case) and c[len(case):].isalpha() for c in seen):
errors.append(f"{case} is listed bare and with lettered cases; keep one form")
if not cases:
errors.append("no acceptance cases")
cited = {i for c in cases for i in c["cites"]}
for title, part in parts.items():
if not title.startswith(SLICE_TABLES):
continue
for _, rows in tables(part):
for row in rows:
for ledger_id in ID_RE.findall(split_row(row)[0]):
if ledger_id not in cited:
errors.append(f"{ledger_id} ({title}) is cited by no acceptance case")
cited.add(ledger_id)
return cases, errors
def slice_ids(text):
cases, _ = obligations(text)
if not cases:
return set(ID_RE.findall(text))
ids = {i for c in cases for i in c["cites"]}
for title, part in sections(text).items():
if title.startswith(SLICE_TABLES):
for _, rows in tables(part):
ids.update(i for row in rows for i in ID_RE.findall(split_row(row)[0]))
return ids
def set_states(rewrite_dir, ids, impl=None, evidence=None):
"""Rewrite the Impl and Evidence cells of each ledger row whose ID cell lists one of `ids`.
Every other byte of the file is kept. Returns (changes, errors); nothing is written on an error."""
path = os.path.join(rewrite_dir, "ledger.md")
text = read_required(path)
if text is None:
raise LedgerError([f"cannot read {path}"])
lines = text.splitlines(keepends=True)
changes, errors, found = [], [], set()
header = None
for n, line in enumerate(lines):
body = line.rstrip("\r\n")
if not body.startswith("|"):
header = None
continue
if header is None:
nxt = lines[n + 1].rstrip("\r\n") if n + 1 < len(lines) else ""
h = [c.lower() for c in split_row(body)] if SEPARATOR_RE.match(nxt) else []
header = h if is_ledger_header(h) else []
continue
cells = split_row(body)
hits = set(ids) & set(ID_RE.findall(cells[0]))
if not header or SEPARATOR_RE.match(body) or not hits:
continue
found |= hits
label = ", ".join(sorted(hits))
raw = re.split(r"(?<!\\)\|", body)
if len(cells) != len(header) or len(raw) != len(header) + 2:
errors.append(f"{label}: malformed row, not changed: {body[:80]}")
continue
idx = (column(header, "impl", "implementation"), column(header, "evidence state", "evidence"))
if None in idx:
errors.append(f"{label}: its ledger table has no Impl or Evidence column")
continue
before = [cells[i] for i in idx]
after = [new or old for new, old in zip((impl, evidence), before)]
for i, value in zip(idx, after):
raw[i + 1] = f" {value} "
lines[n] = "|".join(raw) + line[len(body):]
changes.append(f"{cells[0]}: {' / '.join(before)} -> {' / '.join(after)}")
errors += [f"{i} is not the ID or an alias of any ledger row" for i in sorted(set(ids) - found)]
if not errors:
tmp = path + ".tmp"
with open(tmp, "w", encoding="utf-8", newline="") as fh:
fh.write("".join(lines))
os.replace(tmp, path)
return changes, errors
def format_stats(s):
lines = [
f"verified {s['verified']} of {s['denominator']} ledger rows (retired {s['retired']}, "
f"accepted risk {s['accepted_risk']}, UNDECIDED {s['undecided']})",
"verdicts: " + ", ".join(f"{k} {v}" for k, v in s["verdicts"].items()),
"implementation: " + ", ".join(f"{k} {v}" for k, v in s["implementation"].items()),
"evidence: " + ", ".join(f"{k} {v}" for k, v in s["evidence"].items()),
]
return "\n".join(lines)
def main(argv=None):
ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
ap.add_argument("command", choices=["check", "stats", "obligations", "set"])
ap.add_argument("--rewrite-dir", default=".claude/rewrite")
ap.add_argument("--ids", help="comma-separated ledger IDs to count, or for set to change")
ap.add_argument("--slice", help="count only the IDs this slice seed (interview.md) owns")
ap.add_argument("--impl", choices=sorted(IMPL_STATES), help="set: the new Impl state")
ap.add_argument("--evidence", choices=sorted(EVIDENCE_STATES), help="set: the new Evidence state")
ap.add_argument("--json", action="store_true")
args = ap.parse_args(argv)
if args.command == "set":
ids = [i.strip() for i in (args.ids or "").split(",") if i.strip()]
if not ids or (args.impl is None and args.evidence is None):
print("error: set needs --ids and at least one of --impl, --evidence")
return 2
try:
changes, errors = set_states(args.rewrite_dir, ids, args.impl, args.evidence)
except LedgerError as exc:
print(f"error: {exc.errors[0]}")
return 2
for e in errors:
print(f"error: {e}")
if errors:
print("ledger not changed")
return 1
print("\n".join(changes))
return 0
if args.command == "check":
errors, warnings = check(args.rewrite_dir)
for w in warnings:
print(f"warning: {w}")
for e in errors:
print(f"error: {e}")
print("ledger OK" if not errors else f"{len(errors)} error(s)")
return 1 if errors else 0
if args.command == "obligations":
text = read_required(args.slice) if args.slice else None
if text is None:
print(f"error: obligations needs a readable --slice file, got {args.slice}")
return 2
cases, errors = obligations(text)
if args.json:
print(json.dumps({"cases": cases, "errors": errors}, indent=2))
else:
print(f"obligations: {len(cases)} acceptance cases")
for c in cases:
print(f"{c['id']}: {', '.join(c['cites']) or 'no ledger ID'}")
for e in errors:
print(f"error: {e}")
return 1 if errors else 0
if not read(os.path.join(args.rewrite_dir, "ledger.md")):
print(f"error: missing {os.path.join(args.rewrite_dir, 'ledger.md')}")
return 2
ids = None
if args.ids is not None:
ids = {i.strip() for i in args.ids.split(",") if i.strip()}
if args.slice:
text = read_required(args.slice)
if text is None:
print(f"error: cannot read slice file {args.slice}")
return 2
ids = slice_ids(text)
try:
s = stats(args.rewrite_dir, ids)
except LedgerError as exc:
for e in exc.errors:
print(f"error: {e}", file=sys.stderr)
return 1
if ids is not None:
if not s["rows"]:
print("warning: the selection matches no ledger rows; nothing is verified", file=sys.stderr)
if s["unmatched_ids"]:
print("warning: not in the ledger: " + ", ".join(s["unmatched_ids"]), file=sys.stderr)
print(json.dumps(s, indent=2) if args.json else format_stats(s))
return 0
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |