@design-ai/cli 4.55.0

package/tools/audit/stability-review.py

@@ -0,0 +1,332 @@
+#!/usr/bin/env python3
+"""Quarterly stability review report.
+
+Generates a markdown report listing knowledge files grouped by stability
+level + freshness. Surfaces:
+- experimental files that held up >= 6 months → promote to stable.
+- beta files >= 3 months old without recent edits → promote to stable.
+- stable files > 12 months old → review + bump or revise.
+- deprecated files with no removal plan → flag for next major.
+
+Usage:
+  python3 tools/audit/stability-review.py
+  python3 tools/audit/stability-review.py --output docs/STABILITY-REVIEW.md
+  python3 tools/audit/stability-review.py --warn-months 3 --promote-after 6
+
+Pairs with:
+- tools/migrations/promote-stability.py (bulk promote/demote)
+- tools/migrations/bump-last-updated.py (bulk freshness bump)
+
+Read docs/CONTRIBUTING.md "Quarterly stability review" for the full ritual.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from collections import defaultdict
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+KNOWLEDGE = ROOT / "knowledge"
+
+DATE_RE = re.compile(r"^(\d{4})-(\d{2})(?:-(\d{2}))?$")
+STABILITY_VALUES = {"stable", "beta", "experimental", "deprecated"}
+
+# Generated artifacts that are auto-regenerated and don't need manual review.
+# These are excluded from the "files without stability metadata" section.
+# (Surfaced as a v4.7 dogfood fix — COVERAGE.md was a false positive.)
+GENERATED_ARTIFACTS = {
+    "knowledge/COVERAGE.md",
+}
+
+
+@dataclass(frozen=True)
+class FileInfo:
+    path: Path
+    rel: Path
+    stability: str | None
+    last_updated: str | None
+    last_updated_date: date | None
+    age_months: int | None
+
+
+def find_frontmatter_bounds(text: str) -> tuple[int, int] | None:
+    lines = text.splitlines()
+    cursor = 0
+    while cursor < len(lines):
+        s = lines[cursor].strip()
+        if s.startswith("<!--") and s.endswith("-->"):
+            cursor += 1
+            continue
+        if s == "":
+            cursor += 1
+            continue
+        break
+    if cursor >= len(lines) or lines[cursor].strip() != "---":
+        return None
+    start = cursor + 1
+    for i in range(start, len(lines)):
+        if lines[i].strip() == "---":
+            return (start, i)
+    return None
+
+
+def extract_frontmatter_value(text: str, key: str) -> str | None:
+    bounds = find_frontmatter_bounds(text)
+    if bounds is None:
+        return None
+    start, end = bounds
+    for line in text.splitlines()[start:end]:
+        if line.lstrip().startswith(f"{key}:"):
+            return line.split(":", 1)[1].strip().strip("'\"")
+    return None
+
+
+def parse_date(value: str | None) -> date | None:
+    if value is None:
+        return None
+    m = DATE_RE.match(value)
+    if not m:
+        return None
+    year, month, day = int(m.group(1)), int(m.group(2)), m.group(3)
+    if day is None:
+        return date(year, month, 28)
+    return date(year, month, int(day))
+
+
+def months_diff(target: date, today: date) -> int:
+    return (today.year - target.year) * 12 + (today.month - target.month)
+
+
+def collect(today: date) -> list[FileInfo]:
+    out: list[FileInfo] = []
+    for path in sorted(KNOWLEDGE.rglob("*.md")):
+        rel = path.relative_to(ROOT)
+        # Skip generated artifacts — they don't carry stability by design.
+        if str(rel).replace("\\", "/") in GENERATED_ARTIFACTS:
+            continue
+        text = path.read_text(encoding="utf-8")
+        stability = extract_frontmatter_value(text, "stability")
+        last_updated = extract_frontmatter_value(text, "last_updated")
+        d = parse_date(last_updated)
+        age = months_diff(d, today) if d else None
+        out.append(
+            FileInfo(
+                path=path,
+                rel=rel,
+                stability=stability,
+                last_updated=last_updated,
+                last_updated_date=d,
+                age_months=age,
+            )
+        )
+    return out
+
+
+def render_promotion_candidates(files: list[FileInfo], from_level: str, min_age: int) -> list[FileInfo]:
+    """Files at `from_level` whose last_updated is at least `min_age` months ago."""
+    return [
+        f for f in files
+        if f.stability == from_level and f.age_months is not None and f.age_months >= min_age
+    ]
+
+
+def render_stale_within_level(files: list[FileInfo], level: str, threshold: int) -> list[FileInfo]:
+    return [
+        f for f in files
+        if f.stability == level and f.age_months is not None and f.age_months >= threshold
+    ]
+
+
+def render_report(files: list[FileInfo], today: date, *, warn_months: int, promote_after: int, stale_months: int) -> str:
+    lines: list[str] = []
+    lines.append(f"# Stability review — {today.isoformat()}")
+    lines.append("")
+    lines.append(
+        f"Generated by `tools/audit/stability-review.py`. "
+        f"Pairs with `tools/migrations/promote-stability.py` (bulk promote/demote) "
+        f"and `tools/migrations/bump-last-updated.py` (bulk freshness bump)."
+    )
+    lines.append("")
+
+    # Summary table
+    by_level: dict[str, list[FileInfo]] = defaultdict(list)
+    no_stability: list[FileInfo] = []
+    for f in files:
+        if f.stability and f.stability in STABILITY_VALUES:
+            by_level[f.stability].append(f)
+        else:
+            no_stability.append(f)
+
+    lines.append("## Summary")
+    lines.append("")
+    lines.append("| Level | Count | Oldest (months) |")
+    lines.append("| --- | --- | --- |")
+    for level in ("stable", "beta", "experimental", "deprecated"):
+        items = by_level.get(level, [])
+        oldest = max((f.age_months for f in items if f.age_months is not None), default=None)
+        oldest_str = f"{oldest}" if oldest is not None else "—"
+        lines.append(f"| {level} | {len(items)} | {oldest_str} |")
+    if no_stability:
+        lines.append(f"| (no stability key) | {len(no_stability)} | — |")
+    lines.append("")
+
+    # Section 1: experimental → stable promotion candidates
+    promote_exp = render_promotion_candidates(files, "experimental", promote_after)
+    lines.append(f"## Promotion candidates: experimental → stable (held up ≥ {promote_after} months)")
+    lines.append("")
+    if promote_exp:
+        lines.append("Run after review:")
+        lines.append("")
+        lines.append("```bash")
+        lines.append("python3 tools/migrations/promote-stability.py --from experimental --to stable \\")
+        for f in promote_exp:
+            lines.append(f"  {f.rel} \\")
+        if lines[-1].endswith(" \\"):
+            lines[-1] = lines[-1].rstrip(" \\")
+        lines.append("```")
+        lines.append("")
+    else:
+        lines.append("(none)")
+        lines.append("")
+
+    # Section 2: beta → stable promotion candidates
+    promote_beta = render_promotion_candidates(files, "beta", warn_months)
+    lines.append(f"## Promotion candidates: beta → stable (held up ≥ {warn_months} months)")
+    lines.append("")
+    if promote_beta:
+        lines.append("Run after review:")
+        lines.append("")
+        lines.append("```bash")
+        lines.append("python3 tools/migrations/promote-stability.py --from beta --to stable \\")
+        for f in promote_beta:
+            lines.append(f"  {f.rel} \\")
+        if lines[-1].endswith(" \\"):
+            lines[-1] = lines[-1].rstrip(" \\")
+        lines.append("```")
+        lines.append("")
+    else:
+        lines.append("(none)")
+        lines.append("")
+
+    # Section 3: stable files getting stale
+    stale_stable = render_stale_within_level(files, "stable", stale_months)
+    lines.append(f"## Stable files due for re-review (last_updated ≥ {stale_months} months ago)")
+    lines.append("")
+    if stale_stable:
+        lines.append(
+            f"Either bump `last_updated` (still accurate, no edits needed) or revise + bump."
+        )
+        lines.append("")
+        lines.append("Bulk-bump after review:")
+        lines.append("")
+        lines.append("```bash")
+        lines.append("python3 tools/migrations/bump-last-updated.py \\")
+        for f in stale_stable[:20]:
+            lines.append(f"  {f.rel} \\")
+        if len(stale_stable) > 20:
+            lines.append(f"  # ... and {len(stale_stable) - 20} more")
+        if lines[-1].endswith(" \\"):
+            lines[-1] = lines[-1].rstrip(" \\")
+        lines.append("```")
+        lines.append("")
+        lines.append("Files:")
+        lines.append("")
+        for f in stale_stable:
+            lines.append(f"- `{f.rel}` — {f.age_months} months old")
+        lines.append("")
+    else:
+        lines.append("(none)")
+        lines.append("")
+
+    # Section 4: deprecated files
+    deprecated = by_level.get("deprecated", [])
+    lines.append("## Deprecated files (review for next major removal)")
+    lines.append("")
+    if deprecated:
+        lines.append("These should be removed in the next major version. Confirm removal plan exists in CHANGELOG.")
+        lines.append("")
+        for f in deprecated:
+            age_str = f"{f.age_months} months" if f.age_months is not None else "no last_updated"
+            lines.append(f"- `{f.rel}` — {age_str}")
+        lines.append("")
+    else:
+        lines.append("(none)")
+        lines.append("")
+
+    # Section 5: files without stability metadata
+    if no_stability:
+        lines.append("## Files without `stability` metadata")
+        lines.append("")
+        lines.append("Add `stability:` to frontmatter (one of stable / beta / experimental / deprecated).")
+        lines.append("")
+        for f in no_stability:
+            lines.append(f"- `{f.rel}`")
+        lines.append("")
+
+    # Closing
+    lines.append("---")
+    lines.append("")
+    lines.append("## Ritual checklist")
+    lines.append("")
+    lines.append("Walk through each section above. For each candidate:")
+    lines.append("")
+    lines.append("- [ ] Read the file. Is the content still accurate?")
+    lines.append("- [ ] If yes: bump `last_updated` (use `tools/migrations/bump-last-updated.py`).")
+    lines.append("- [ ] If revisions needed: edit + bump.")
+    lines.append("- [ ] If obsolete: mark `stability: deprecated` and add deprecation note in body.")
+    lines.append("- [ ] For promotion candidates: confirm content stable, then promote.")
+    lines.append("")
+    lines.append("After the ritual, document outcome in `CHANGELOG.md` under the next minor release.")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--output",
+        type=Path,
+        help="Write report to this path (otherwise stdout)",
+    )
+    parser.add_argument("--warn-months", type=int, default=3, help="Beta promotion threshold (default: 3)")
+    parser.add_argument(
+        "--promote-after",
+        type=int,
+        default=6,
+        help="Experimental → stable threshold (default: 6)",
+    )
+    parser.add_argument(
+        "--stale-months",
+        type=int,
+        default=12,
+        help="Stable file re-review threshold (default: 12)",
+    )
+    parser.add_argument("--today", help="Override today (YYYY-MM-DD); for testing")
+    args = parser.parse_args()
+
+    today = date.fromisoformat(args.today) if args.today else date.today()
+
+    files = collect(today)
+    report = render_report(
+        files,
+        today,
+        warn_months=args.warn_months,
+        promote_after=args.promote_after,
+        stale_months=args.stale_months,
+    )
+
+    if args.output:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(report, encoding="utf-8")
+        print(f"Wrote: {args.output}")
+    else:
+        sys.stdout.write(report)
+
+
+if __name__ == "__main__":
+    main()

package/tools/audit/stale-check.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""Flag knowledge files whose `last_updated` is too old.
+
+Operationalizes the versioned frontmatter (added in v3.11). Default:
+- Warn: last_updated > 6 months ago.
+- Error: last_updated > 12 months ago (with --strict).
+
+Files without `last_updated` are skipped (backward-compatible).
+
+Usage:
+  python3 tools/audit/stale-check.py
+  python3 tools/audit/stale-check.py --strict
+  python3 tools/audit/stale-check.py --warn-months 3 --error-months 6
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from datetime import date
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+KNOWLEDGE = ROOT / "knowledge"
+
+DATE_RE = re.compile(r"^(\d{4})-(\d{2})(?:-(\d{2}))?$")
+
+
+def find_frontmatter_bounds(text: str) -> tuple[int, int] | None:
+    lines = text.splitlines()
+    cursor = 0
+    while cursor < len(lines):
+        s = lines[cursor].strip()
+        if s.startswith("<!--") and s.endswith("-->"):
+            cursor += 1
+            continue
+        if s == "":
+            cursor += 1
+            continue
+        break
+    if cursor >= len(lines) or lines[cursor].strip() != "---":
+        return None
+    start = cursor + 1
+    for i in range(start, len(lines)):
+        if lines[i].strip() == "---":
+            return (start, i)
+    return None
+
+
+def extract_last_updated(text: str) -> str | None:
+    bounds = find_frontmatter_bounds(text)
+    if bounds is None:
+        return None
+    start, end = bounds
+    for line in text.splitlines()[start:end]:
+        if line.lstrip().startswith("last_updated:"):
+            value = line.split(":", 1)[1].strip().strip("'\"")
+            return value
+    return None
+
+
+def parse_date(value: str) -> date | None:
+    """Parse YYYY-MM or YYYY-MM-DD; return last day of month if no day given."""
+    m = DATE_RE.match(value)
+    if not m:
+        return None
+    year, month, day = int(m.group(1)), int(m.group(2)), m.group(3)
+    if day is None:
+        # Treat YYYY-MM as the LAST day of that month (most generous reading).
+        # Pick day 28 — safe for all months — then advance to month-end.
+        d = date(year, month, 28)
+    else:
+        d = date(year, month, int(day))
+    return d
+
+
+def months_diff(target: date, today: date) -> int:
+    """Approximate month difference (today − target). Negative if target is in the future."""
+    return (today.year - target.year) * 12 + (today.month - target.month)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--strict", action="store_true", help="Exit 1 if any file exceeds the error threshold")
+    parser.add_argument("--warn-months", type=int, default=6, help="Months before warning (default: 6)")
+    parser.add_argument("--error-months", type=int, default=12, help="Months before error (default: 12)")
+    parser.add_argument("--today", default=None, help="Override today's date (YYYY-MM-DD) — for testing")
+    args = parser.parse_args()
+
+    today = date.fromisoformat(args.today) if args.today else date.today()
+
+    warns: list[str] = []
+    errors: list[str] = []
+    skipped = 0
+    invalid = 0
+    fresh = 0
+
+    for path in sorted(KNOWLEDGE.rglob("*.md")):
+        text = path.read_text(encoding="utf-8")
+        last_updated = extract_last_updated(text)
+        rel = path.relative_to(ROOT)
+
+        if last_updated is None:
+            skipped += 1
+            continue
+
+        d = parse_date(last_updated)
+        if d is None:
+            invalid += 1
+            errors.append(f"{rel}: invalid last_updated format '{last_updated}'")
+            continue
+
+        diff = months_diff(d, today)
+        if diff >= args.error_months:
+            errors.append(f"{rel}: {diff} months stale (last_updated={last_updated})")
+        elif diff >= args.warn_months:
+            warns.append(f"{rel}: {diff} months old (last_updated={last_updated})")
+        else:
+            fresh += 1
+
+    total = fresh + len(warns) + len(errors) + skipped + invalid
+    print()
+    print(f"  Fresh (≤ {args.warn_months} months):       {fresh}")
+    print(f"  Warning (>{args.warn_months} months):      {len(warns)}")
+    print(f"  Stale  (>{args.error_months} months):      {len(errors)}")
+    print(f"  Skipped (no last_updated):  {skipped}")
+    print(f"  Invalid format:             {invalid}")
+    print(f"  Total knowledge files:      {total}")
+    print()
+
+    if warns and not args.strict:
+        print("⚠  Warnings:")
+        for w in warns[:10]:
+            print(f"   - {w}")
+        if len(warns) > 10:
+            print(f"   ... and {len(warns) - 10} more")
+
+    if errors:
+        print("✗  Stale files:")
+        for e in errors[:20]:
+            print(f"   - {e}")
+        if len(errors) > 20:
+            print(f"   ... and {len(errors) - 20} more")
+
+    if errors:
+        if args.strict:
+            sys.exit(1)
+        else:
+            print()
+            print("Use --strict to fail CI on stale files.")
+    else:
+        print("All knowledge files within freshness window ✓")
+
+
+if __name__ == "__main__":
+    main()

package/tools/migrations/add-version-frontmatter.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""One-shot migration: add `version`, `last_updated`, `stability` keys to
+the YAML frontmatter of every knowledge file.
+
+Behavior:
+  - Locates every .md file in knowledge/ that already has a frontmatter
+    block (between `---` markers, optionally preceded by an HTML comment
+    like `<!-- hand-written -->`).
+  - If `version` is already present, the file is skipped (idempotent).
+  - Otherwise inserts `version: 1.0.0`, `last_updated: 2026-05`, and
+    `stability: stable` BEFORE the closing `---` line. Existing keys
+    are preserved as-is.
+
+Usage:
+  python3 tools/migrations/add-version-frontmatter.py            # dry-run
+  python3 tools/migrations/add-version-frontmatter.py --write    # apply
+
+After running, verify with:
+  python3 tools/audit/frontmatter-check.py
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+KNOWLEDGE = ROOT / "knowledge"
+
+DEFAULT_VERSION = "1.0.0"
+DEFAULT_LAST_UPDATED = "2026-05"
+DEFAULT_STABILITY = "stable"
+
+
+def find_frontmatter_bounds(text: str) -> tuple[int, int] | None:
+    """Return (start_line_idx, end_line_idx) of frontmatter, exclusive of
+    the closing `---` line marker (so insertions go ABOVE end_line_idx).
+
+    Skips leading HTML comments and blank lines before the opening `---`.
+    Returns None if no frontmatter block found.
+    """
+    lines = text.splitlines()
+    cursor = 0
+
+    # Skip leading HTML comments + blank lines
+    while cursor < len(lines):
+        stripped = lines[cursor].strip()
+        if stripped.startswith("<!--") and stripped.endswith("-->"):
+            cursor += 1
+            continue
+        if stripped == "":
+            cursor += 1
+            continue
+        break
+
+    # Now expect opening `---`
+    if cursor >= len(lines) or lines[cursor].strip() != "---":
+        return None
+
+    start = cursor + 1
+    # Find closing `---`
+    for i in range(start, len(lines)):
+        if lines[i].strip() == "---":
+            return (start, i)
+    return None
+
+
+def has_version_key(text: str, start: int, end: int) -> bool:
+    lines = text.splitlines()
+    for line in lines[start:end]:
+        if line.lstrip().startswith("version:"):
+            return True
+    return False
+
+
+def insert_version_keys(text: str, start: int, end: int) -> str:
+    lines = text.splitlines(keepends=True)
+    insertion = (
+        f"version: {DEFAULT_VERSION}\n"
+        f"last_updated: {DEFAULT_LAST_UPDATED}\n"
+        f"stability: {DEFAULT_STABILITY}\n"
+    )
+    # Insert before the closing `---` line (line index `end`)
+    lines.insert(end, insertion)
+    return "".join(lines)
+
+
+def process_file(path: Path, write: bool) -> str:
+    """Returns one of: 'skip-no-frontmatter', 'skip-already-versioned',
+    'updated', 'would-update'."""
+    text = path.read_text(encoding="utf-8")
+    bounds = find_frontmatter_bounds(text)
+    if bounds is None:
+        return "skip-no-frontmatter"
+
+    start, end = bounds
+    if has_version_key(text, start, end):
+        return "skip-already-versioned"
+
+    new_text = insert_version_keys(text, start, end)
+    if write:
+        path.write_text(new_text, encoding="utf-8")
+        return "updated"
+    return "would-update"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--write", action="store_true", help="Apply changes (without this, dry-run)")
+    args = parser.parse_args()
+
+    files = sorted(KNOWLEDGE.rglob("*.md"))
+    counts = {"updated": 0, "would-update": 0, "skip-already-versioned": 0, "skip-no-frontmatter": 0}
+
+    for path in files:
+        result = process_file(path, args.write)
+        counts[result] += 1
+
+    print()
+    if args.write:
+        print(f"  ✓ Updated:                    {counts['updated']}")
+    else:
+        print(f"  Would update:                 {counts['would-update']}")
+    print(f"  Skipped (already versioned):  {counts['skip-already-versioned']}")
+    print(f"  Skipped (no frontmatter):     {counts['skip-no-frontmatter']}")
+    print(f"  Total scanned:                {sum(counts.values())}")
+    print()
+    if not args.write and counts["would-update"] > 0:
+        print("Re-run with --write to apply.")
+
+
+if __name__ == "__main__":
+    main()