Skip to content

oliver-kriska/claude-elixir-phoenix / plugins/rewrite/skills/architect

architect

Verified

Design 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.

FileKindSize
SKILL.mdskill md7.3 KB
references/compatibility-bar.mdmarkdown8.3 KB
scripts/ledger.pyscript23.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())
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall