armelhbobdad/oh-my-skills / .claude/skills/skf-refine-architecture
skf-refine-architecture
VerifiedRefines an architecture document against generated skills and a Verify Stack report. Use when the user requests to "refine the architecture against generated skills" or "refine an architecture doc with a VS report."
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.6 KB |
| customize.toml | config | 4.2 KB |
| references/compile.md | markdown | 17.6 KB |
| references/exit-codes.md | markdown | 5.6 KB |
| references/finding-storage.md | markdown | 3.3 KB |
| references/gap-analysis.md | markdown | 19.8 KB |
| references/health-check.md | markdown | 901 B |
| references/improvements.md | markdown | 5.3 KB |
| references/init.md | markdown | 18.2 KB |
| references/issue-detection.md | markdown | 8.1 KB |
| references/refinement-rules.md | markdown | 8.1 KB |
| references/report.md | markdown | 9.9 KB |
| scripts/skf-check-preservation.py | script | 74.2 KB |
scripts/skf-check-preservation.py
View on GitHub#!/usr/bin/env python3
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""Build, check and promote refine-architecture's refined document, and check
the refinement rules and the [VS] verdicts the steps classify with.
Compile (references/compile.md) never retypes the architecture document. It
stages an insertion plan, one entry per finding, and this script copies the
original line for line, puts each entry's block where its anchor says,
appends the Refinement Summary, checks that every original line survived and
writes the draft. The review's [C] promotes the draft through this script
too, so the output file is never replaced by a draft that lost a line.
Init (references/init.md) checks the refinement rules with `rules`, and
issue detection (references/issue-detection.md) joins the [VS] report's
verdict rows to the skill inventory and the document scope with `verdicts`,
so neither step applies a table rule or a join by hand.
RA's blocks. Every block the script adds sits between two marker lines, so a
later pass can set the whole annotation aside and write a fresh one:
<!-- RA:BEGIN <kind> <id> -->
...
<!-- RA:END -->
<kind> is gap, issue or improvement (an anchored entry), section (a fallback
section: <id> is the kind it collects) or summary (the Refinement Summary).
Setting RA's blocks aside removes each BEGIN line through the next END line,
outside fenced code. A BEGIN followed by another BEGIN before any END, and an
END with no BEGIN, are malformed: they stay in place as ordinary lines and
are reported, so a marker the user deleted never takes their text with it.
A document refined before the markers existed holds unmarked annotations:
when it has a `Refinement Summary` heading and at least one `RA:` heading or
RA callout (a blockquote whose first line names "Gap Identified by Refine
Architecture", "Issue Detected by Refine Architecture" or "Improvement
Suggested by Refine Architecture"), each `RA:` section and the Refinement
Summary section (to the next heading of the same or a higher level) and
each such callout are set aside too. Nothing marks where an older pass's
text ends, so such a section can hold a paragraph of the user's that follows
it: set_aside names every block set aside, by its lines in the file as
given, so the caller can show them instead of claiming they were checked.
Subcommands:
inspect --doc PATH [--stripped OUT] [-o JSON]
Report whether PATH holds an earlier RA pass and, with --stripped,
write a copy of it with RA's blocks set aside (the analysis input).
-o also writes the JSON to that file when the command succeeded.
JSON: {status: "ok", doc, previous_pass, signals[], marked_blocks,
legacy_blocks, malformed_markers[], lines_set_aside, set_aside[],
stripped}. set_aside holds {start, end, kind, first_line} per block,
kind "marked" or "legacy", first_line the text of its start line.
signals holds "ra-markers" (marked blocks, or malformed markers),
"legacy-annotations" and "refined-document" (the file name is
refined-architecture-*.md); previous_pass is true when any is there.
apply --original PATH --plan PLAN --draft OUT [-o JSON]
Check the plan, build the draft from PATH with RA's blocks set aside,
check that it preserves PATH, and write it to OUT. Nothing is written
when the plan has a problem or the check fails, so an earlier draft at
OUT stays as it was. -o also writes the JSON to that file, only when
the draft was written, so the file always describes the draft on disk.
JSON on success: {status: "ok", draft, counts, evidence, summary,
unverified_technologies[], placed[], fallback[], closed_fence_line,
preserved: true, missing: [], altered: [], lines_set_aside,
set_aside[]}. summary is the Refinement Summary as the draft holds
it, its placeholders filled.
check --original PATH --refined PATH
Set RA's blocks aside in both files and confirm the original's lines
appear in the refined file, in order and unchanged (a line's
terminator aside). Lines the refined file adds are allowed.
JSON: {status: "preserved" | "not-preserved", preserved, missing[],
missing_count, altered[], altered_count, added_count}. missing holds
{line, text}, altered {line, original, refined_line, refined}, with
line numbers in the files as given; each list keeps its first 50.
promote --original PATH --draft DRAFT --output OUT --timestamp TS [-o JSON]
Check DRAFT against PATH as check does, then rename an existing OUT to
<OUT stem>-<TS>.md (-2, -3 ... when that name is taken) and move DRAFT
to OUT. When the move fails, the earlier OUT is renamed back.
JSON: {status: "promoted", output, previous, preserved: true,
draft_removed}. draft_removed is false only when OUT is on another
file system and the draft, copied there, could not be deleted. -o
also writes the JSON to that file, only when the draft was promoted;
when that write fails, the draft and the earlier OUT are put back.
When a file cannot be put back, the error says where each one is.
context --inspect JSON --apply JSON --promote JSON -o OUT
Merge the records of inspect, apply and promote into the payload the
shared emitter writes the result contract from, and write it to OUT:
{status: "success", refined_path, previous_refined_path,
previous_pass, gap_count, issue_count, improvement_count,
unverified_count, result_contract: {skill, status, outputs, summary}}.
Prints {status: "ok", context: OUT}. A record that is missing or not
the JSON its subcommand wrote is an error (exit 2).
rules --rules PATH
Check the refinement rules file (the bundled references/
refinement-rules.md or a team's copy). It must hold the six tables
the steps read, each the first table under a heading of that title
(any level, case ignored): Gap Classification, Issue Classification,
Issue Severity, VS Report Integration, Improvement Classification and
Improvement Value. The first cell of each Issue Severity and
Improvement Value row names a tier, which becomes the summary count
{<tier>_count}, so a tier name starts with a letter and holds only the
letters A to Z, digits and spaces; no two tiers of the two tables
share a name, ignoring case and runs of spaces; and none is named Gap,
Issue, Improvement, Unverified or Skill, whose counts the summary
already holds. The VS Report Integration table has one row per
verdict token (Verified, Plausible, Risky, Blocked, case-sensitive),
and each row's Raises cell names one tier of Issue Severity, as a
whole word, ignoring case, or says No issue or None, never both:
what it bolds when it bolds a tier or No issue or None
(`A **Major** issue`, as the bundled rows do, or `**No issue**`),
else what its text names (`Major`, `No issue`).
JSON: {status: "ok" | "violations", rules, missing_tables[], tiers:
{issue[], improvement[]}, vs_raises: {<token>: <tier> | null},
violations[]}. A violation is {table, line, rule, detail}, line null
when it names no row; rule is table-missing, table-empty, tier-name,
tier-reserved, tier-duplicate, vs-token-unknown, vs-token-duplicate,
vs-token-unmapped or vs-raises.
verdicts --report PATH --generated-at TS --skills JSON --in-scope NAMES --rules PATH
Read the [VS] report's verdict rows again through the shared
feasibility-report reader, and join each to the skill inventory and
the document scope. --generated-at is the report's generatedAt when
the run started ("" when it had none), --skills a JSON array of the
inventory's skills, each a name or {name, aliases}, and --in-scope
the in-scope skill names, comma-separated. Each row's lib_a and lib_b
map to the skill of that name, ignoring case and runs of spaces, else
to the one skill that has it as an alias. A row whose two libraries
are two in-scope skills goes to in_scope with raises, the tier the
rules' VS Report Integration table maps its token to (null: no
issue); any other row goes to out_of_scope with reason
"no-inventory-skill" (a library names no single skill, such as a
[VS] cycle row's `cycle`), "same-skill" (both name one skill, such as
its name and an alias) or "out-of-scope" (two skills, one or both
outside the scope).
JSON: {status: "ok", report, generatedAt, overallVerdict, in_scope[],
out_of_scope[], issue_count}, each row {lib_a, lib_b, verdict,
rationale, skill_a, skill_b} plus raises or reason, in report order;
issue_count counts the in_scope rows that raise a tier. When the
report is no longer the one the run started from (it cannot be read,
breaks the feasibility-report contract or has another generatedAt),
or the rules no longer pass `rules` (they break a rule above or
cannot be read), it prints {status: "stale", problems: [{source,
detail}]} instead, source "report" or "rules".
The insertion plan (apply --plan) is one JSON object:
{
"entries": [
{"id": "gap-1", "kind": "gap", "anchor": "## Data Layer",
"skills": ["loro", "yjs"], "block": "#### RA: ...\\n\\n> [!NOTE] ..."},
{"id": "issue-1", "kind": "issue", "tier": "Critical",
"anchor": "Sync runs over gRPC.", "occurrence": 2, "block": "> [!WARNING] ..."},
{"id": "improvement-1", "kind": "improvement", "tier": "High",
"anchor": null, "block": "#### RA: Enhancement: ..."}
],
"summary": "## Refinement Summary\\n... {gap_count} ...",
"unverified_technologies": ["Redis"],
"skill_count": 4,
"tiers": {"issue": [...], "improvement": [...]},
"fallback_headings": {"gap": "...", "issue": "...", "improvement": "..."}
}
id unique, letters, digits, '.', '_' or '-' (it goes into the
BEGIN marker)
kind gap, issue or improvement
tier an issue's severity or an improvement's value, one of the
kind's tiers (default Critical, Major, Minor and High, Medium,
Low; "tiers" replaces them); a gap has none
anchor text one line of the document holds, outside its frontmatter,
or null for the kind's fallback section. It must occur on
exactly one line, unless "occurrence" (1-based) picks one of
the lines that hold it. An anchor that is an ATX heading
(`## API`) matches the headings of that level and title, so
`### API Gateway` never holds it; only when no heading does is
it matched as text.
skills the skills the finding cites (the Evidence Sources counts)
block the Markdown to insert, holding no RA marker and no unclosed
code fence. A gap or improvement block opens with its ATX
heading: the script sets that heading one level below the
heading that governs the anchor.
summary the Refinement Summary, holding no RA marker. The script fills
{gap_count}, {issue_count} and {improvement_count} (all three
are required, so no count is typed), {<tier>_count} for every
tier (lower case, spaces as '_': {critical_count}),
{unverified_count} (the length of unverified_technologies),
{unverified_technologies} (their names, comma-separated, or
"none"), {skill_count} (the plan's skill_count, the skills the
run used as evidence, when the plan gives it) and
{evidence_rows} (one `| <skill> | <count> |` row per cited
skill, most cited first). Any other {lower_case} placeholder
left in it is a problem.
Placement. An issue goes right after the block that holds its anchor: a
heading line, the enclosing paragraph, table or blockquote, the whole list
(a loose list's later items included, and a code fence indented under one
of its items, which belongs to the item) or the code fence. A gap or
improvement goes at the end of the section its anchor sits in (the anchor
heading's own section, or the nearest heading above the anchor line), before
the next heading of the same or a higher level. Entries placed at one point
keep this order: issues, gaps, improvements, each by tier and then by plan
order. Entries with a null anchor, or with no heading above the anchor, go
to the fallback sections appended at the end of the document (gaps, then
issues by severity, then improvements by value), and the Refinement Summary
comes last. A document that ends inside an unclosed code fence gets a
closing fence line first (closed_fence_line), so nothing RA adds lands in
the code. Original lines keep their bytes and terminators; added lines use
the document's own line ending.
apply's problems. When the plan cannot be applied, apply prints
{status: "problems", problems[]} and exits 1. Each problem has an id (null
for the plan itself), a reason and a detail: plan-invalid, entry-invalid,
tier-unknown, block-has-marker, block-unclosed-fence, block-no-heading,
anchor-not-found (with closest: the line that holds the longest part of the
anchor, its heading), anchor-ambiguous (with matches: each line and its
heading), occurrence-out-of-range, summary-has-marker,
summary-unclosed-fence, summary-count-typed and summary-placeholder.
Exit codes:
0 inspect, apply, check, promote, context, rules or verdicts succeeded
(check: preserved; rules: no violation)
1 apply: the plan has problems, or the draft would not preserve the
original (status "not-preserved"); check: not preserved; promote: the
draft does not preserve the original, and nothing was moved; rules:
the rules break a rule (status "violations"); verdicts: the report
changed or the rules no longer pass (status "stale")
2 a usage error (argparse prints it, no JSON), or a file that cannot be
read or is not UTF-8 text, or a context record that is not its
subcommand's JSON, or a --skills file that is not a JSON array of
skills ({status: "error", error})
3 a write failed ({status: "error", error}): the shared atomic writer is
missing or failed, or promote could not rename or move a file or write
its -o record (it puts the earlier output back first, and the error
names where each file is when it cannot); verdicts: the shared
feasibility-report reader is missing
Writes go through the shared skf-atomic-write.py, and verdicts reads the
report through the shared skf-validate-feasibility-report.py: both sit in
the shared scripts folder beside this skill's folder, installed and in a
dev checkout.
"""
from __future__ import annotations
import argparse
import difflib
import errno
import importlib.util
import json
import os
import re
import shutil
import subprocess
import sys
from pathlib import Path
from typing import NamedTuple
SHARED_SCRIPTS = Path(__file__).resolve().parent.parent.parent / "shared" / "scripts"
ATOMIC_WRITER = SHARED_SCRIPTS / "skf-atomic-write.py"
FEASIBILITY_READER = SHARED_SCRIPTS / "skf-validate-feasibility-report.py"
KINDS = ("gap", "issue", "improvement")
# Entries placed at one point, and the fallback sections, keep this order.
KIND_RANK = {"issue": 0, "gap": 1, "improvement": 2}
FALLBACK_ORDER = ("gap", "issue", "improvement")
DEFAULT_TIERS = {"issue": ["Critical", "Major", "Minor"], "improvement": ["High", "Medium", "Low"]}
DEFAULT_FALLBACK_HEADINGS = {
"gap": "RA: Additional Integration Paths",
"issue": "RA: Additional Issues Detected",
"improvement": "RA: Additional Improvements Suggested",
}
REQUIRED_PLACEHOLDERS = ("gap_count", "issue_count", "improvement_count")
LIST_CAP = 50
BEGIN_RE = re.compile(r"^\s{0,3}<!--\s*RA:BEGIN\b.*-->\s*$")
END_RE = re.compile(r"^\s{0,3}<!--\s*RA:END\s*-->\s*$")
MARKER_TEXT_RE = re.compile(r"<!--\s*RA:(?:BEGIN|END)\b")
FENCE_OPEN_RE = re.compile(r"^ {0,3}(`{3,}|~{3,})(.*)$")
HEADING_RE = re.compile(r"^ {0,3}(#{1,6})(?:[ \t]+(.*?))?[ \t]*$")
LIST_RE = re.compile(r"^\s{0,3}(?:[-*+]|\d{1,9}[.)])(?:\s|$)")
INDENT_RE = re.compile(r"^(?: {2,}|\t)\S")
QUOTE_RE = re.compile(r"^ {0,3}>")
PLACEHOLDER_RE = re.compile(r"\{([a-z][a-z0-9_]*)\}")
ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
TIMESTAMP_RE = re.compile(r"^\d{8}-\d{6}$")
REFINED_NAME_RE = re.compile(r"^refined-architecture-.+\.md$")
LEGACY_CALLOUTS = (
"Gap Identified by Refine Architecture",
"Issue Detected by Refine Architecture",
"Improvement Suggested by Refine Architecture",
)
SUMMARY_TITLE = "refinement summary"
# The tables the steps read from the refinement rules, in the file's order.
RULE_TABLES = ("Gap Classification", "Issue Classification", "Issue Severity", "VS Report Integration",
"Improvement Classification", "Improvement Value")
TIER_TABLES = (("issue", "Issue Severity"), ("improvement", "Improvement Value"))
VS_TABLE = "VS Report Integration"
VS_TOKENS = ("Verified", "Plausible", "Risky", "Blocked")
# A tier becomes the summary's {<tier>_count}, which PLACEHOLDER_RE fills only
# for a name of ASCII letters, digits and spaces that starts with a letter.
TIER_NAME_RE = re.compile(r"[A-Za-z][A-Za-z0-9 ]*")
RESERVED_COUNTS = (*REQUIRED_PLACEHOLDERS, "unverified_count", "skill_count")
TABLE_ROW_RE = re.compile(r"^ {0,3}\|")
TABLE_DELIM_RE = re.compile(r"^ {0,3}\|?\s*:?-+:?\s*(?:\|\s*:?-+:?\s*)*\|?\s*$")
CELL_SPLIT_RE = re.compile(r"(?<!\\)\|")
BOLD_RE = re.compile(r"\*\*(.+?)\*\*|__(.+?)__")
NO_ISSUE_RE = re.compile(r"(?<![A-Za-z0-9])(?:no\s+issue|none)(?![A-Za-z0-9])", re.IGNORECASE)
class DocError(Exception):
"""A file that cannot be read as UTF-8 text (exit 2)."""
class WriteError(Exception):
"""A write that failed (exit 3)."""
class HelperMissing(Exception):
"""A shared helper this script runs is not installed (exit 3)."""
class Line(NamedTuple):
number: int # 1-based, in the file the line was read from
text: str # without its terminator
end: str # "\n", "\r\n", or "" for a last line without one
class Structure(NamedTuple):
"""What each line of a document is, outside and inside its code fences."""
front: list[bool]
fence: list[bool] # a fence's opening, content and closing lines
fence_close: list[int] # for a fence line: the index of its closing line
level: list[int] # ATX heading level, 0 for any other line
open_fence: tuple[str, int] | None # (char, length) of a fence left open at the end
class Stripped:
"""A document with RA's blocks set aside, and what was set aside."""
def __init__(self) -> None:
self.kept: list[Line] = []
self.marked = 0
self.legacy = 0
self.malformed: list[int] = [] # 1-based line numbers
self.spans: list[dict] = [] # each block set aside: {start, end, kind, first_line}
# --------------------------------------------------------------------------
# Reading and writing
# --------------------------------------------------------------------------
def split_lines(text: str) -> list[Line]:
"""Split on \\n alone (a \\r before it belongs to the terminator)."""
lines = []
for number, piece in enumerate(re.findall(r"[^\n]*\n|[^\n]+\Z", text), start=1):
if piece.endswith("\r\n"):
lines.append(Line(number, piece[:-2], "\r\n"))
elif piece.endswith("\n"):
lines.append(Line(number, piece[:-1], "\n"))
else:
lines.append(Line(number, piece, ""))
return lines
def read_lines(path: str) -> list[Line]:
try:
data = Path(path).read_bytes()
except OSError as e:
raise DocError(f"{path}: {e.strerror or e}") from e
try:
return split_lines(data.decode("utf-8"))
except UnicodeDecodeError as e:
raise DocError(f"{path}: not UTF-8 text ({e.reason} at byte {e.start})") from e
def render(lines: list[Line]) -> str:
return "".join(line.text + line.end for line in lines)
def write_atomic(path: Path, data: bytes) -> None:
"""Write through the shared skf-atomic-write.py (temp file, fsync, rename)."""
if not ATOMIC_WRITER.is_file():
raise WriteError(f"the shared atomic writer is not installed: {ATOMIC_WRITER.as_posix()}")
proc = subprocess.run(
[sys.executable, str(ATOMIC_WRITER), "write", "--target", str(path)],
input=data,
capture_output=True,
check=False,
)
if proc.returncode != 0:
message = proc.stderr.decode("utf-8", "replace").strip()
try:
message = json.loads(message).get("message", message)
except (ValueError, AttributeError):
message = message.splitlines()[-1] if message else f"exit {proc.returncode}"
raise WriteError(f"{path.as_posix()}: {message}")
# --------------------------------------------------------------------------
# Markdown structure
# --------------------------------------------------------------------------
def scan(texts: list[str]) -> Structure:
n = len(texts)
front = [False] * n
if n and texts[0].strip() == "---":
for i in range(1, n):
if texts[i].strip() in ("---", "..."):
for j in range(i + 1):
front[j] = True
break
fence = [False] * n
fence_close = [-1] * n
level = [0] * n
open_fence = None
i = 0
while i < n:
if front[i]:
i += 1
continue
m = FENCE_OPEN_RE.match(texts[i])
if m and not (m.group(1)[0] == "`" and "`" in m.group(2)):
char, length = m.group(1)[0], len(m.group(1))
close_re = re.compile(r"^ {0,3}" + re.escape(char) + "{" + str(length) + r",}\s*$")
j = i + 1
while j < n and not close_re.match(texts[j]):
j += 1
last = min(j, n - 1)
if j >= n:
open_fence = (char, length)
for k in range(i, last + 1):
fence[k] = True
fence_close[k] = last
i = last + 1
continue
h = HEADING_RE.match(texts[i])
if h:
level[i] = len(h.group(1))
i += 1
return Structure(front, fence, fence_close, level, open_fence)
def heading_text(text: str) -> str:
h = HEADING_RE.match(text)
title = (h.group(2) or "") if h else ""
return re.sub(r"(?:^|[ \t]+)#+$", "", title).strip()
def nearest_heading(texts: list[str], st: Structure, index: int) -> int | None:
for i in range(index, -1, -1):
if st.level[i] and not st.fence[i]:
return i
return None
def section_end(st: Structure, start: int) -> int:
"""The index of the next heading of the same or a higher level, else the end."""
lvl = st.level[start]
for i in range(start + 1, len(st.level)):
if st.level[i] and not st.fence[i] and st.level[i] <= lvl:
return i
return len(st.level)
def _block_line(texts: list[str], st: Structure, i: int) -> bool:
return bool(texts[i].strip()) and not st.front[i] and not st.fence[i] and not st.level[i]
def _run_of(texts: list[str], st: Structure, i: int) -> tuple[int, int]:
"""The first and last index of the run of block lines that holds line i."""
start = end = i
while start > 0 and _block_line(texts, st, start - 1):
start -= 1
while end + 1 < len(texts) and _block_line(texts, st, end + 1):
end += 1
return start, end
def _fence_start(st: Structure, i: int) -> int:
"""The opening line of the code fence that holds line i."""
while i > 0 and st.fence[i - 1] and st.fence_close[i - 1] == st.fence_close[i]:
i -= 1
return i
def _indented_fence(texts: list[str], st: Structure, i: int) -> bool:
"""Line i is in a code fence whose opening line is indented, as under a list item."""
return st.fence[i] and INDENT_RE.match(texts[_fence_start(st, i)]) is not None
def _content_above(texts: list[str], st: Structure, i: int) -> int:
"""The nearest line above i that is not blank, hopping over indented fences."""
j = i - 1
while j >= 0:
if not texts[j].strip() and not st.fence[j]:
j -= 1
elif _indented_fence(texts, st, j):
j = _fence_start(st, j) - 1
else:
break
return j
def block_end(texts: list[str], st: Structure, a: int) -> int:
"""The last index of the paragraph, table, blockquote, list or fence that holds line a."""
n = len(texts)
if st.fence[a]:
close = st.fence_close[a]
if not _indented_fence(texts, st, a):
return close
# A fence indented under a list item belongs to that item's list.
j = _fence_start(st, a) - 1
while j >= 0 and not texts[j].strip() and not st.fence[j]:
j -= 1
if j >= 0 and (_block_line(texts, st, j) or _indented_fence(texts, st, j)):
return max(close, block_end(texts, st, j))
return close
start, end = _run_of(texts, st, a)
in_list = any(LIST_RE.match(texts[i]) for i in range(start, end + 1))
if not in_list and INDENT_RE.match(texts[start]):
# An indented paragraph after a blank line, or after a fence indented
# under an item, continues the list item above it.
j = _content_above(texts, st, start)
if j >= 0 and _block_line(texts, st, j):
above, _ = _run_of(texts, st, j)
in_list = INDENT_RE.match(texts[j]) is not None or any(
LIST_RE.match(texts[i]) for i in range(above, j + 1))
if in_list:
# A loose list goes on past a blank line while the next line is an
# item, indented under one, or opens a fence indented under one.
while True:
j = end + 1
while j < n and not texts[j].strip() and not st.fence[j]:
j += 1
if j < n and _indented_fence(texts, st, j):
end = st.fence_close[j]
continue
if j < n and _block_line(texts, st, j) and (LIST_RE.match(texts[j]) or INDENT_RE.match(texts[j])):
end = j
while end + 1 < n and _block_line(texts, st, end + 1):
end += 1
continue
break
return end
# --------------------------------------------------------------------------
# Setting RA's blocks aside
# --------------------------------------------------------------------------
def strip_ra(lines: list[Line]) -> Stripped:
texts = [line.text for line in lines]
st = scan(texts)
keep = [True] * len(lines)
result = Stripped()
open_at = None
for i, text in enumerate(texts):
if st.front[i] or st.fence[i]:
continue
if BEGIN_RE.match(text):
if open_at is not None:
result.malformed.append(lines[open_at].number)
open_at = i
elif END_RE.match(text):
if open_at is None:
result.malformed.append(lines[i].number)
else:
for j in range(open_at, i + 1):
keep[j] = False
result.marked += 1
result.spans.append(_span(lines[open_at], lines[i], "marked"))
open_at = None
if open_at is not None:
result.malformed.append(lines[open_at].number)
result.malformed.sort()
rest = [line for line, k in zip(lines, keep) if k]
spans = legacy_spans(rest)
result.legacy = len(spans)
result.spans += [_span(rest[start], rest[end - 1], "legacy") for start, end in spans]
result.spans.sort(key=lambda span: span["start"])
drop = {i for start, end in spans for i in range(start, end)}
result.kept = [line for i, line in enumerate(rest) if i not in drop]
return result
def _span(first: Line, last: Line, kind: str) -> dict:
return {"start": first.number, "end": last.number, "kind": kind, "first_line": first.text.strip()}
def legacy_spans(lines: list[Line]) -> list[tuple[int, int]]:
"""The unmarked annotations of a pass made before the markers existed."""
texts = [line.text for line in lines]
st = scan(texts)
summaries, heads, callouts = [], [], []
for i, text in enumerate(texts):
if st.front[i] or st.fence[i]:
continue
if st.level[i]:
title = heading_text(text)
if title.casefold() == SUMMARY_TITLE:
summaries.append(i)
elif title.startswith("RA:"):
heads.append(i)
elif QUOTE_RE.match(text) and any(name in text for name in LEGACY_CALLOUTS):
if i == 0 or not QUOTE_RE.match(texts[i - 1]):
callouts.append(i)
if not summaries or not (heads or callouts):
return []
spans = [(i, section_end(st, i)) for i in heads + summaries]
for i in callouts:
end = i
while end + 1 < len(texts) and QUOTE_RE.match(texts[end + 1]) and not st.fence[end + 1]:
end += 1
spans.append((i, end + 1))
merged: list[tuple[int, int]] = []
for start, end in sorted(spans):
if merged and start <= merged[-1][1]:
if end > merged[-1][1]:
merged[-1] = (merged[-1][0], end)
continue
merged.append((start, end))
return merged
# --------------------------------------------------------------------------
# The preservation check
# --------------------------------------------------------------------------
def check_preservation(original: list[Line], refined: list[Line]) -> dict:
a = strip_ra(original).kept
b = strip_ra(refined).kept
matcher = difflib.SequenceMatcher(None, [x.text for x in a], [y.text for y in b], autojunk=False)
missing, altered, added = [], [], 0
for tag, i1, i2, j1, j2 in matcher.get_opcodes():
if tag == "delete":
missing.extend(a[i1:i2])
elif tag == "insert":
added += j2 - j1
elif tag == "replace":
pairs = min(i2 - i1, j2 - j1)
altered.extend(zip(a[i1:i1 + pairs], b[j1:j1 + pairs]))
missing.extend(a[i1 + pairs:i2])
added += (j2 - j1) - pairs
missing.sort(key=lambda line: line.number)
preserved = not missing and not altered
return {
"status": "preserved" if preserved else "not-preserved",
"preserved": preserved,
"missing": [{"line": x.number, "text": x.text} for x in missing[:LIST_CAP]],
"missing_count": len(missing),
"altered": [
{"line": x.number, "original": x.text, "refined_line": y.number, "refined": y.text}
for x, y in altered[:LIST_CAP]
],
"altered_count": len(altered),
"added_count": added,
}
# --------------------------------------------------------------------------
# The insertion plan
# --------------------------------------------------------------------------
def _problem(entry_id, reason: str, detail: str, **extra) -> dict:
return {"id": entry_id, "reason": reason, "detail": detail, **extra}
def _fence_open(texts: list[str]) -> bool:
return scan(texts).open_fence is not None
def _placeholder(tier: str) -> str:
return re.sub(r"\s+", "_", tier.strip().lower()) + "_count"
def read_plan(path: str) -> dict:
try:
raw = Path(path).read_bytes().decode("utf-8")
except OSError as e:
raise DocError(f"{path}: {e.strerror or e}") from e
except UnicodeDecodeError as e:
raise DocError(f"{path}: not UTF-8 text ({e.reason} at byte {e.start})") from e
try:
return json.loads(raw)
except ValueError as e:
return {"__invalid__": f"{path}: not JSON ({e})"}
def check_plan(plan, base: list[Line]) -> tuple[list[dict], dict]:
"""Return (problems, resolved): the plan's problems and, when none, what apply needs."""
if not isinstance(plan, dict) or "__invalid__" in plan:
detail = plan.get("__invalid__") if isinstance(plan, dict) else "the plan must be a JSON object"
return [_problem(None, "plan-invalid", detail or "the plan must be a JSON object")], {}
problems: list[dict] = []
tiers = {kind: list(names) for kind, names in DEFAULT_TIERS.items()}
given = plan.get("tiers")
if given is not None:
if not isinstance(given, dict):
problems.append(_problem(None, "plan-invalid", "tiers must be an object"))
else:
for kind, names in given.items():
ok = (kind in tiers and isinstance(names, list) and names
and all(isinstance(t, str) and t.strip() for t in names)
and len({t.casefold() for t in names}) == len(names))
if not ok:
problems.append(_problem(None, "plan-invalid",
f"tiers.{kind} must be issue or improvement, with distinct names"))
else:
tiers[kind] = [t.strip() for t in names]
placeholders = [_placeholder(t) for kind in ("issue", "improvement") for t in tiers[kind]]
if len(set(placeholders)) != len(placeholders):
problems.append(_problem(None, "plan-invalid", "an issue tier and an improvement tier share a name"))
headings = dict(DEFAULT_FALLBACK_HEADINGS)
given = plan.get("fallback_headings")
if given is not None:
if not isinstance(given, dict) or not all(
k in headings and isinstance(v, str) and v.strip() and "\n" not in v for k, v in given.items()):
problems.append(_problem(None, "plan-invalid",
"fallback_headings maps gap, issue or improvement to one line of text"))
else:
headings.update({k: v.strip().lstrip("#").strip() for k, v in given.items()})
unverified = plan.get("unverified_technologies", [])
if not isinstance(unverified, list) or not all(isinstance(t, str) for t in unverified):
problems.append(_problem(None, "plan-invalid", "unverified_technologies must be a list of strings"))
unverified = []
skill_count = plan.get("skill_count")
if skill_count is not None and (not isinstance(skill_count, int) or isinstance(skill_count, bool)
or skill_count < 0):
problems.append(_problem(None, "plan-invalid", "skill_count must be a whole number from 0"))
skill_count = None
summary = plan.get("summary")
if not isinstance(summary, str) or not summary.strip():
problems.append(_problem(None, "plan-invalid", "summary must be the Refinement Summary's Markdown"))
summary = ""
entries = plan.get("entries")
if not isinstance(entries, list):
problems.append(_problem(None, "plan-invalid", "entries must be a list"))
entries = []
texts = [line.text for line in base]
st = scan(texts)
searchable = [i for i in range(len(texts)) if not st.front[i]]
seen: set[str] = set()
resolved_entries = []
for index, entry in enumerate(entries):
if not isinstance(entry, dict):
problems.append(_problem(None, "entry-invalid", f"entries[{index}] is not an object"))
continue
entry_id = entry.get("id")
if not isinstance(entry_id, str) or not ID_RE.match(entry_id):
problems.append(_problem(None, "entry-invalid",
f"entries[{index}]: id must be letters, digits, '.', '_' or '-'"))
continue
if entry_id in seen:
problems.append(_problem(entry_id, "entry-invalid", "the id is used twice"))
continue
seen.add(entry_id)
kind = entry.get("kind")
if kind not in KINDS:
problems.append(_problem(entry_id, "entry-invalid", "kind must be gap, issue or improvement"))
continue
tier = None
if kind in tiers:
given_tier = entry.get("tier")
match = [t for t in tiers[kind] if isinstance(given_tier, str) and t.casefold() == given_tier.strip().casefold()]
if not match:
problems.append(_problem(entry_id, "tier-unknown", f"tier must be one of {', '.join(tiers[kind])}"))
continue
tier = match[0]
skills = entry.get("skills", [])
if not isinstance(skills, list) or not all(isinstance(s, str) and s.strip() for s in skills):
problems.append(_problem(entry_id, "entry-invalid", "skills must be a list of skill names"))
continue
block = entry.get("block")
if not isinstance(block, str) or not block.strip():
problems.append(_problem(entry_id, "entry-invalid", "block must be the Markdown to insert"))
continue
block_lines = block.replace("\r\n", "\n").strip("\n").split("\n")
if MARKER_TEXT_RE.search(block):
problems.append(_problem(entry_id, "block-has-marker", "a block holds no RA:BEGIN or RA:END marker"))
continue
if _fence_open(block_lines):
problems.append(_problem(entry_id, "block-unclosed-fence", "the block opens a code fence it never closes"))
continue
if kind != "issue" and not HEADING_RE.match(next(t for t in block_lines if t.strip())):
problems.append(_problem(entry_id, "block-no-heading", "a gap or improvement block opens with its heading"))
continue
anchor_line = None
anchor = entry.get("anchor")
if anchor is not None:
if not isinstance(anchor, str) or not anchor.strip() or "\n" in anchor.strip():
problems.append(_problem(entry_id, "entry-invalid", "anchor must be one line of text, or null"))
continue
anchor = anchor.strip()
hits = _heading_hits(anchor, texts, st) or [i for i in searchable if anchor in texts[i]]
occurrence = entry.get("occurrence")
if occurrence is not None and (not isinstance(occurrence, int) or isinstance(occurrence, bool)
or occurrence < 1):
problems.append(_problem(entry_id, "entry-invalid", "occurrence must be a whole number from 1"))
continue
if not hits:
problems.append(_problem(entry_id, "anchor-not-found", "no line of the document holds the anchor",
anchor=anchor, closest=_closest(anchor, base, texts, st, searchable)))
continue
if occurrence is None and len(hits) > 1:
problems.append(_problem(entry_id, "anchor-ambiguous",
f"{len(hits)} lines hold the anchor: quote one that only one line holds, "
"or add occurrence", anchor=anchor,
matches=[_where(i, base, texts, st) for i in hits[:LIST_CAP]]))
continue
if occurrence is not None and occurrence > len(hits):
problems.append(_problem(entry_id, "occurrence-out-of-range",
f"occurrence {occurrence}, but {len(hits)} line(s) hold the anchor",
anchor=anchor))
continue
anchor_line = hits[(occurrence or 1) - 1]
resolved_entries.append({"index": index, "id": entry_id, "kind": kind, "tier": tier,
"skills": [s.strip() for s in skills], "lines": block_lines,
"anchor": anchor_line})
if summary:
summary_lines = summary.replace("\r\n", "\n").strip("\n").split("\n")
if MARKER_TEXT_RE.search(summary):
problems.append(_problem(None, "summary-has-marker", "the summary holds no RA:BEGIN or RA:END marker"))
if _fence_open(summary_lines):
problems.append(_problem(None, "summary-unclosed-fence", "the summary opens a code fence it never closes"))
found = set(PLACEHOLDER_RE.findall(summary))
typed = [name for name in REQUIRED_PLACEHOLDERS if name not in found]
if typed:
problems.append(_problem(None, "summary-count-typed",
"the summary must leave these counts to the script: "
+ ", ".join("{" + name + "}" for name in typed)))
known = set(REQUIRED_PLACEHOLDERS) | set(placeholders) | {"unverified_count", "unverified_technologies",
"evidence_rows"}
if skill_count is not None:
known.add("skill_count")
unknown = sorted(found - known)
if unknown:
problems.append(_problem(None, "summary-placeholder",
"fill these yourself or remove them: "
+ ", ".join("{" + name + "}" for name in unknown)))
resolved = {"entries": resolved_entries, "summary": summary, "tiers": tiers, "headings": headings,
"unverified": unverified, "skill_count": skill_count}
return problems, resolved
def _heading_hits(anchor: str, texts: list[str], st: Structure) -> list[int]:
"""The headings an ATX heading anchor names: same level, same title."""
h = HEADING_RE.match(anchor)
if not h:
return []
level, title = len(h.group(1)), heading_text(anchor)
return [i for i, lvl in enumerate(st.level)
if lvl == level and not st.fence[i] and not st.front[i] and heading_text(texts[i]) == title]
def _where(i: int, base: list[Line], texts: list[str], st: Structure) -> dict:
h = nearest_heading(texts, st, i)
return {"line": base[i].number, "text": texts[i], "heading": texts[h].strip() if h is not None else None}
def _closest(anchor: str, base: list[Line], texts: list[str], st: Structure, searchable: list[int]) -> dict | None:
best, best_size = None, 0
for i in searchable:
if not texts[i].strip():
continue
m = difflib.SequenceMatcher(None, anchor, texts[i], autojunk=False)
size = m.find_longest_match(0, len(anchor), 0, len(texts[i])).size
if size > best_size:
best, best_size = i, size
if best is None or best_size * 2 < len(anchor):
return None
return _where(best, base, texts, st)
# --------------------------------------------------------------------------
# Building the draft
# --------------------------------------------------------------------------
def _set_level(block: list[str], level: int) -> list[str]:
out = list(block)
for i, text in enumerate(out):
if text.strip():
m = HEADING_RE.match(text)
out[i] = "#" * level + " " + (m.group(2) or "").strip()
break
return out
def _region(kind: str, region_id: str, body: list[str]) -> list[str]:
return [f"<!-- RA:BEGIN {kind} {region_id} -->", "", *body, "", "<!-- RA:END -->"]
def compose(base: list[Line], resolved: dict) -> tuple[list[Line], dict]:
texts = [line.text for line in base]
st = scan(texts)
n = len(base)
newline = next((line.end for line in base if line.end), "\n")
rank = {kind: {t: r for r, t in enumerate(resolved["tiers"].get(kind, []))} for kind in KINDS}
at: dict[int, list[tuple[tuple, list[str], dict]]] = {}
fallback: dict[str, list[dict]] = {kind: [] for kind in KINDS}
for entry in resolved["entries"]:
a = entry["anchor"]
key = (KIND_RANK[entry["kind"]], rank[entry["kind"]].get(entry["tier"], 0), entry["index"])
if a is None:
fallback[entry["kind"]].append(entry)
continue
if entry["kind"] == "issue":
if st.level[a] and not st.fence[a]:
k = a + 1
else:
k = block_end(texts, st, a) + 1
body = entry["lines"]
else:
g = a if (st.level[a] and not st.fence[a]) else nearest_heading(texts, st, a)
if g is None:
fallback[entry["kind"]].append(entry)
continue
k = section_end(st, g)
body = _set_level(entry["lines"], min(st.level[g] + 1, 6))
at.setdefault(k, []).append((key, _region(entry["kind"], entry["id"], body), entry))
tail: list[list[str]] = []
fallback_ids: list[str] = []
for kind in FALLBACK_ORDER:
items = sorted(fallback[kind], key=lambda e: (rank[kind].get(e["tier"], 0), e["index"]))
if not items:
continue
fallback_ids += [e["id"] for e in items]
body = ["## " + resolved["headings"][kind]]
for e in items:
lines = e["lines"] if kind == "issue" else _set_level(e["lines"], 3)
body += ["", *lines]
tail.append(_region("section", kind, body))
tail.append(_region("summary", "refinement-summary", fill_summary(resolved)))
out: list[Line] = []
placed = []
def add(text: str) -> None:
if out and not out[-1].end:
out[-1] = Line(out[-1].number, out[-1].text, newline)
out.append(Line(len(out) + 1, text, newline))
def insert(k: int) -> None:
for _, region, entry in sorted(at.get(k, []), key=lambda item: item[0]):
placed.append({"id": entry["id"], "kind": entry["kind"], "line": len(out) + 1})
for text in region:
add(text)
for i, line in enumerate(base):
insert(i)
out.append(Line(len(out) + 1, line.text, line.end))
closed_fence_line = None
if st.open_fence is not None:
char, length = st.open_fence
add(char * length)
closed_fence_line = len(out)
insert(n)
for region in tail:
for text in region:
add(text)
# The last line keeps the document's own ending: none when it had none.
if out and base and not base[-1].end and out[-1].text == "<!-- RA:END -->":
out[-1] = Line(out[-1].number, out[-1].text, "")
info = {
"placed": placed,
"fallback": fallback_ids,
"closed_fence_line": closed_fence_line,
}
return out, info
def tally(resolved: dict) -> tuple[dict, dict]:
entries = resolved["entries"]
counts = {kind: sum(1 for e in entries if e["kind"] == kind) for kind in KINDS}
for kind in ("issue", "improvement"):
counts[f"{kind}_tiers"] = {t: sum(1 for e in entries if e["kind"] == kind and e["tier"] == t)
for t in resolved["tiers"][kind]}
counts["unverified"] = len(resolved["unverified"])
counts["skills"] = resolved["skill_count"]
evidence: dict[str, int] = {}
for e in entries:
for skill in dict.fromkeys(e["skills"]):
evidence[skill] = evidence.get(skill, 0) + 1
evidence = dict(sorted(evidence.items(), key=lambda item: (-item[1], item[0])))
return counts, evidence
def fill_summary(resolved: dict) -> list[str]:
counts, evidence = tally(resolved)
values = {"gap_count": counts["gap"], "issue_count": counts["issue"],
"improvement_count": counts["improvement"], "unverified_count": counts["unverified"],
"unverified_technologies": ", ".join(resolved["unverified"]) or "none",
"evidence_rows": "\n".join(f"| {skill} | {count} |" for skill, count in evidence.items())}
if counts["skills"] is not None:
values["skill_count"] = counts["skills"]
for kind in ("issue", "improvement"):
for tier, count in counts[f"{kind}_tiers"].items():
values[_placeholder(tier)] = count
text = PLACEHOLDER_RE.sub(lambda m: str(values.get(m.group(1), m.group(0))), resolved["summary"])
return text.replace("\r\n", "\n").strip("\n").split("\n")
# --------------------------------------------------------------------------
# Refinement rules and [VS] verdicts
# --------------------------------------------------------------------------
def _plain(cell: str) -> str:
"""A table cell without the bold, italic or code markers that wrap it."""
text = cell.strip()
while True:
for mark in ("**", "__", "`", "*", "_"):
if len(text) > 2 * len(mark) and text.startswith(mark) and text.endswith(mark):
text = text[len(mark):-len(mark)].strip()
break
else:
return text
def _cells(text: str) -> list[str]:
row = text.strip()
if row.startswith("|"):
row = row[1:]
if row.endswith("|") and not row.endswith("\\|"):
row = row[:-1]
return [cell.strip() for cell in CELL_SPLIT_RE.split(row)]
def rule_tables(texts: list[str]) -> dict[str, list[tuple[int, list[str]]]]:
"""{heading title, case folded: the data rows of the first table in its section}.
A section runs from its heading to the next heading of the same or a
higher level; frontmatter and fenced code are skipped. Each row is
(1-based line, cells). The first heading of a title wins.
"""
st = scan(texts)
usable = [not (st.front[i] or st.fence[i]) for i in range(len(texts))]
tables: dict[str, list[tuple[int, list[str]]]] = {}
for h, level in enumerate(st.level):
if not level or not usable[h]:
continue
key = _plain(heading_text(texts[h])).casefold()
if key in tables:
continue
end = section_end(st, h)
for i in range(h + 1, end - 1):
if usable[i] and usable[i + 1] and TABLE_ROW_RE.match(texts[i]) and TABLE_DELIM_RE.match(texts[i + 1]):
rows = []
j = i + 2
while j < end and usable[j] and TABLE_ROW_RE.match(texts[j]):
rows.append((j + 1, _cells(texts[j])))
j += 1
tables[key] = rows
break
return tables
def _violation(table: str, line, rule: str, detail: str) -> dict:
return {"table": table, "line": line, "rule": rule, "detail": detail}
def _named_tiers(text: str, severities: dict[str, str]) -> list[str]:
"""The tiers `text` names as whole words, ignoring case and runs of spaces, longest name first.
A longer tier's words are not read again as a shorter one (`Very High` is not also `High`).
"""
found: list[str] = []
taken: list[tuple[int, int]] = []
for tier in sorted(severities.values(), key=len, reverse=True):
words = r"\s+".join(re.escape(word) for word in tier.split())
for m in re.finditer(r"(?<![A-Za-z0-9])" + words + r"(?![A-Za-z0-9])", text, re.IGNORECASE):
if not any(m.start() < end and start < m.end() for start, end in taken):
taken.append(m.span())
if tier not in found:
found.append(tier)
return found
def vs_raised(cell: str, severities: dict[str, str]) -> tuple[list[str], bool]:
"""The tiers a VS Report Integration Raises cell names, and whether it says no issue.
What the cell bolds counts when it bolds a tier or No issue or None (`A **Major** issue`,
`**No issue**, whatever the rationale says`): the prose around it is not read. Otherwise
the tiers its text names as whole words count (`Major`, `A Critical issue`), and it says
no issue when its text says No issue or None, ignoring case. A cell that names a tier and
also says no issue, both in bold or both in its text, raises neither: check_rules reports it.
"""
bold = [(m.group(1) or m.group(2)).strip() for m in BOLD_RE.finditer(cell)]
named = [severities[_placeholder(b)] for b in bold if TIER_NAME_RE.fullmatch(b) and _placeholder(b) in severities]
no_issue = any(NO_ISSUE_RE.fullmatch(b) for b in bold)
if named or no_issue:
return list(dict.fromkeys(named)), no_issue
return _named_tiers(cell, severities), bool(NO_ISSUE_RE.search(cell))
def check_rules(path: str) -> dict:
"""Check the refinement rules file: the tables the steps read and the tier rules."""
texts = [line.text for line in read_lines(path)]
tables = rule_tables(texts)
violations = []
missing = [name for name in RULE_TABLES if name.casefold() not in tables]
for name in missing:
violations.append(_violation(name, None, "table-missing", f"lacks the {name} table"))
tiers: dict[str, list[str]] = {}
seen: dict[str, str] = {} # each tier's count placeholder: the tier that took it
for kind, table in TIER_TABLES:
rows = tables.get(table.casefold())
if rows is None:
continue
named = [(line, _plain(cells[0])) for line, cells in rows if _plain(cells[0])]
tiers[kind] = [name for _, name in named]
if not named:
violations.append(_violation(table, None, "table-empty", f"the {table} table names no tier"))
for line, name in named:
if not TIER_NAME_RE.fullmatch(name):
violations.append(_violation(table, line, "tier-name", f"tier `{name}` (line {line}) must start with "
"a letter and hold only the letters A to Z, digits and spaces"))
continue
key = _placeholder(name)
if key in RESERVED_COUNTS:
violations.append(_violation(table, line, "tier-reserved", f"tier `{name}` (line {line}) takes a "
"name whose count the Refinement Summary already holds"))
elif key in seen:
violations.append(_violation(table, line, "tier-duplicate", f"tier `{name}` (line {line}) has the "
f"same name as `{seen[key]}`, ignoring case"))
else:
seen[key] = name
severities = {_placeholder(t): t for t in tiers.get("issue", []) if TIER_NAME_RE.fullmatch(t)}
vs_raises: dict[str, str | None] = {}
rows = tables.get(VS_TABLE.casefold())
if rows is not None:
rowed = set()
for line, cells in rows:
token = _plain(cells[0])
if token not in VS_TOKENS:
violations.append(_violation(VS_TABLE, line, "vs-token-unknown", f"VS row `{token}` (line {line}) "
"is not a verdict token: `Verified`, `Plausible`, `Risky` or "
"`Blocked`, case-sensitive"))
continue
if token in rowed:
violations.append(_violation(VS_TABLE, line, "vs-token-duplicate",
f"VS token `{token}` has a second row (line {line})"))
continue
rowed.add(token)
named, no_issue = vs_raised(cells[1] if len(cells) > 1 else "", severities)
if named and no_issue:
violations.append(_violation(VS_TABLE, line, "vs-raises", f"VS row `{token}` (line {line}) names "
f"{', '.join(named)} and also says No issue or None: bold the one "
"it raises"))
elif len(named) == 1 or no_issue:
vs_raises[token] = named[0] if named else None
elif named:
violations.append(_violation(VS_TABLE, line, "vs-raises", f"VS row `{token}` (line {line}) names "
f"more than one tier of the Issue Severity table: {', '.join(named)}"))
else:
violations.append(_violation(VS_TABLE, line, "vs-raises", f"VS row `{token}` (line {line}) raises "
"neither a tier of the Issue Severity table nor No issue"))
for token in VS_TOKENS:
if token not in rowed:
violations.append(_violation(VS_TABLE, None, "vs-token-unmapped",
f"no VS Report Integration row maps `{token}`"))
return {
"status": "violations" if violations else "ok",
"rules": Path(path).as_posix(),
"missing_tables": missing,
"tiers": {kind: tiers.get(kind, []) for kind, _ in TIER_TABLES},
"vs_raises": {token: vs_raises[token] for token in VS_TOKENS if token in vs_raises},
"violations": violations,
}
def load_feasibility_reader():
"""Import the shared feasibility-report reader, or None when it is missing."""
try:
if not FEASIBILITY_READER.is_file():
return None
except OSError:
return None # a folder on the way that cannot be searched
spec = importlib.util.spec_from_file_location("skf_validate_feasibility_report", FEASIBILITY_READER)
if spec is None or spec.loader is None:
return None
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
def _key(name: str) -> str:
return " ".join(name.split()).casefold()
def read_skill_terms(path: str) -> list[tuple[str, list[str]]]:
"""The --skills JSON array: (name, aliases) per skill, a plain string being a name."""
try:
raw = Path(path).read_bytes().decode("utf-8")
except OSError as e:
raise DocError(f"{path}: {e.strerror or e}") from e
except UnicodeDecodeError as e:
raise DocError(f"{path}: not UTF-8 text ({e.reason} at byte {e.start})") from e
try:
data = json.loads(raw)
except ValueError as e:
raise DocError(f"{path}: not JSON ({e})") from e
shape = f"{path}: not a JSON array of skills, each a name or {{name, aliases}}"
if not isinstance(data, list):
raise DocError(shape)
skills = []
for item in data:
if isinstance(item, str) and item.strip():
skills.append((item.strip(), []))
continue
if not isinstance(item, dict) or not isinstance(item.get("name"), str) or not item["name"].strip():
raise DocError(shape)
aliases = item.get("aliases") or []
if not isinstance(aliases, list) or not all(isinstance(a, str) for a in aliases):
raise DocError(shape)
skills.append((item["name"].strip(), [a for a in aliases if a.strip()]))
return skills
def skill_matcher(skills: list[tuple[str, list[str]]]):
"""A function from a library as a report names it to its inventory skill, or None.
A skill's name wins, ignoring case and runs of spaces; otherwise the one
skill that has the library as an alias. An alias two skills share names
neither.
"""
names: dict[str, str] = {}
aliases: dict[str, set[str]] = {}
for name, _ in skills:
names.setdefault(_key(name), name)
for name, terms in skills:
for term in terms:
aliases.setdefault(_key(term), set()).add(name)
def match(library: str) -> str | None:
key = _key(library)
if key in names:
return names[key]
owners = aliases.get(key, set())
return next(iter(owners)) if len(owners) == 1 else None
return match
def _report_problem(report: dict, code: int, generated_at: str) -> str | None:
"""Why the report is not the one the run started from, or None."""
if code == 2 or report.get("violation") == "io-error":
return f"it cannot be read again: {report.get('error') or 'unreadable'}"
if code != 0:
return "it no longer passes the feasibility-report contract"
found = report.get("generatedAt") or ""
if found != generated_at:
return f"its generatedAt is {found or 'empty'}, not {generated_at or 'empty'}: [VS] rewrote it during the run"
return None
def cmd_inspect(args) -> tuple[dict, int]:
lines = read_lines(args.doc)
stripped = strip_ra(lines)
signals = []
if stripped.marked or stripped.malformed:
signals.append("ra-markers")
if stripped.legacy:
signals.append("legacy-annotations")
if REFINED_NAME_RE.match(Path(args.doc).name):
signals.append("refined-document")
out = None
if args.stripped:
out = Path(args.stripped)
write_atomic(out, render(stripped.kept).encode("utf-8"))
return {
"status": "ok",
"doc": args.doc,
"previous_pass": bool(signals),
"signals": signals,
"marked_blocks": stripped.marked,
"legacy_blocks": stripped.legacy,
"malformed_markers": stripped.malformed,
"lines_set_aside": len(lines) - len(stripped.kept),
"set_aside": stripped.spans,
"stripped": out.as_posix() if out else None,
}, 0
def cmd_apply(args) -> tuple[dict, int]:
original = read_lines(args.original)
plan = read_plan(args.plan)
stripped = strip_ra(original)
problems, resolved = check_plan(plan, stripped.kept)
if problems:
return {"status": "problems", "problems": problems}, 1
draft, info = compose(stripped.kept, resolved)
check = check_preservation(original, draft)
if not check["preserved"]:
return {"status": "not-preserved", **{k: v for k, v in check.items() if k != "status"}}, 1
out = Path(args.draft)
write_atomic(out, render(draft).encode("utf-8"))
counts, evidence = tally(resolved)
return {
"status": "ok",
"draft": out.as_posix(),
"counts": counts,
"evidence": evidence,
"summary": "\n".join(fill_summary(resolved)),
"unverified_technologies": resolved["unverified"],
**info,
"preserved": True,
"missing": [],
"altered": [],
"lines_set_aside": len(original) - len(stripped.kept),
"set_aside": stripped.spans,
}, 0
def cmd_check(args) -> tuple[dict, int]:
result = check_preservation(read_lines(args.original), read_lines(args.refined))
return result, 0 if result["preserved"] else 1
def _free_name(output: Path, timestamp: str) -> Path:
candidate = output.with_name(f"{output.stem}-{timestamp}{output.suffix}")
n = 2
while candidate.exists() or candidate.is_symlink():
candidate = output.with_name(f"{output.stem}-{timestamp}-{n}{output.suffix}")
n += 1
return candidate
def cmd_promote(args) -> tuple[dict, int]:
draft_path, output = Path(args.draft), Path(args.output)
draft = read_lines(args.draft)
check = check_preservation(read_lines(args.original), draft)
if not check["preserved"]:
return {"status": "not-preserved", **{k: v for k, v in check.items() if k != "status"}}, 1
if output.exists() and not output.is_file():
raise WriteError(f"{output.as_posix()}: not a file")
previous = None
draft_removed = True
if output.exists():
previous = _free_name(output, args.timestamp)
try:
os.rename(output, previous)
except OSError as e:
raise WriteError(f"cannot rename {output.as_posix()}: {e.strerror or e}") from e
try:
output.parent.mkdir(parents=True, exist_ok=True)
try:
os.replace(draft_path, output)
except OSError as e:
if e.errno != errno.EXDEV:
raise
# Another file system: copy through the atomic writer, then drop the draft.
write_atomic(output, draft_path.read_bytes())
try:
draft_path.unlink()
except OSError:
draft_removed = False
except (OSError, WriteError) as e:
reason = e.strerror if isinstance(e, OSError) and e.strerror else str(e)
message = f"cannot move {draft_path.as_posix()} to {output.as_posix()}: {reason}"
if previous is not None:
try:
os.rename(previous, output)
except OSError as back:
message += (f"; the earlier output could not be renamed back ({back.strerror or back}), so it "
f"stays at {previous.as_posix()}, and the draft is at {draft_path.as_posix()}")
raise WriteError(message) from e
return {
"status": "promoted",
"output": output.as_posix(),
"previous": previous.as_posix() if previous else None,
"preserved": True,
"draft_removed": draft_removed,
}, 0
def _undo_promote(args, result: dict) -> str:
"""Put the draft and the earlier output back: the promotion's record could not be written.
Returns "" when both are back, else where each file was left.
"""
output, previous = Path(args.output).as_posix(), result.get("previous")
try:
shutil.move(output, args.draft)
except OSError as e:
left = f"the draft could not be moved back ({e.strerror or e}), so it stays at {output} as the refined document"
return left + (f", and the earlier output is at {previous}" if previous else "")
if previous:
try:
os.rename(previous, output)
except OSError as e:
return (f"the earlier output could not be renamed back ({e.strerror or e}), so it stays at {previous}, "
f"and the draft is back at {Path(args.draft).as_posix()}")
return ""
def _record(path: str, command: str, status: str, keys: tuple[str, ...]) -> dict:
"""A JSON record one of the other subcommands wrote with -o."""
try:
record = json.loads(Path(path).read_bytes().decode("utf-8"))
except OSError as e:
raise DocError(f"{path}: {e.strerror or e}") from e
except (UnicodeDecodeError, ValueError) as e:
raise DocError(f"{path}: not the JSON record {command} writes ({e})") from e
if not isinstance(record, dict) or record.get("status") != status or any(k not in record for k in keys):
raise DocError(f"{path}: not the record of a successful {command}")
return record
def cmd_context(args) -> tuple[dict, int]:
inspected = _record(args.inspect, "inspect", "ok", ("previous_pass",))
applied = _record(args.apply, "apply", "ok", ("counts",))
promoted = _record(args.promote, "promote", "promoted", ("output", "previous"))
counts = applied["counts"]
names = ("gap", "issue", "improvement", "unverified")
if not isinstance(counts, dict) or not all(isinstance(counts.get(k), int) for k in names):
raise DocError(f"{args.apply}: its counts lack {', '.join(names)}")
totals = {f"{k}_count": counts[k] for k in names}
payload = {
"status": "success",
"refined_path": promoted["output"],
"previous_refined_path": promoted["previous"],
"previous_pass": bool(inspected["previous_pass"]),
**totals,
"result_contract": {
"skill": "skf-refine-architecture",
"status": "success",
"outputs": [{"type": "report", "path": promoted["output"]}],
"summary": {**totals, "previous_refined_path": promoted["previous"]},
},
}
out = Path(args.out)
write_atomic(out, (json.dumps(payload, indent=2, ensure_ascii=False) + "\n").encode("utf-8"))
return {"status": "ok", "context": out.as_posix()}, 0
def cmd_rules(args) -> tuple[dict, int]:
result = check_rules(args.rules)
return result, 1 if result["violations"] else 0
def cmd_verdicts(args) -> tuple[dict, int]:
match = skill_matcher(read_skill_terms(args.skills))
in_scope = {_key(name) for name in args.in_scope.split(",") if name.strip()}
reader = load_feasibility_reader()
if reader is None:
raise HelperMissing(f"the shared feasibility-report reader is not installed: {FEASIBILITY_READER.as_posix()}")
problems = []
report, code = reader.validate_report(args.report)
problem = _report_problem(report, code, args.generated_at)
if problem:
problems.append({"source": "report", "detail": f"{Path(args.report).as_posix()}: {problem}"})
try:
rules = check_rules(args.rules)
except DocError as e:
problems.append({"source": "rules", "detail": str(e)})
else:
problems += [{"source": "rules", "detail": v["detail"]} for v in rules["violations"]]
if problems:
return {"status": "stale", "problems": problems}, 1
joined: list[dict] = []
left_out: list[dict] = []
for row in report["pairVerdicts"]:
skill_a, skill_b = match(row["lib_a"]), match(row["lib_b"])
entry = {**row, "skill_a": skill_a, "skill_b": skill_b}
if skill_a is None or skill_b is None:
left_out.append({**entry, "reason": "no-inventory-skill"})
elif skill_a == skill_b:
left_out.append({**entry, "reason": "same-skill"})
elif _key(skill_a) in in_scope and _key(skill_b) in in_scope:
joined.append({**entry, "raises": rules["vs_raises"].get(row["verdict"])})
else:
left_out.append({**entry, "reason": "out-of-scope"})
return {
"status": "ok",
"report": Path(report["path"]).as_posix(),
"generatedAt": report.get("generatedAt"),
"overallVerdict": report.get("overallVerdict"),
"in_scope": joined,
"out_of_scope": left_out,
"issue_count": sum(1 for row in joined if row["raises"] is not None),
}, 0
def _timestamp(value: str) -> str:
if not TIMESTAMP_RE.match(value):
raise argparse.ArgumentTypeError(f"{value!r} is not YYYYMMDD-HHmmss")
return value
def _build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
prog="skf-check-preservation",
description=(
"Build refine-architecture's draft from an insertion plan, check that a refined "
"document keeps every line of the original, promote the draft to the output file, "
"and stage the result contract's payload from the run's records. RA's marked "
"blocks (and the unmarked annotations of an older pass) are set aside in both "
"documents first. Also check the refinement rules, and join the [VS] report's "
"verdicts to the skill inventory and the document scope. Prints JSON."
),
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=(
"Examples:\n"
" uv run skf-check-preservation.py inspect --doc arch.md --stripped run/analysis-doc.md\n"
" uv run skf-check-preservation.py apply --original arch.md --plan run/insertion-plan.json "
"--draft forge/.skf-ra-draft-app.md -o run/apply.json\n"
" uv run skf-check-preservation.py check --original arch.md --refined refined.md\n"
" uv run skf-check-preservation.py promote --original arch.md --draft forge/.skf-ra-draft-app.md "
"--output docs/refined-architecture-app.md --timestamp 20261001-120000\n"
" uv run skf-check-preservation.py context --inspect run/inspect.json --apply run/apply.json "
"--promote run/promote.json --out run/result-context.json\n"
" uv run skf-check-preservation.py rules --rules references/refinement-rules.md\n"
" uv run skf-check-preservation.py verdicts --report forge/feasibility-report-app-latest.md "
"--generated-at 2026-10-01T10:00:00Z --skills run/skill-terms.json --in-scope loro,yjs "
"--rules references/refinement-rules.md"
),
)
sub = parser.add_subparsers(dest="command", required=True)
p = sub.add_parser("inspect", help="Detect an earlier RA pass and write the analysis copy.")
p.add_argument("--doc", required=True, help="the architecture document")
p.add_argument("--stripped", help="write the document with RA's blocks set aside here")
p.add_argument("-o", "--output-json", help="also write the JSON result here")
p.set_defaults(func=cmd_inspect)
p = sub.add_parser("apply", help="Build the draft from the insertion plan.")
p.add_argument("--original", required=True, help="the architecture document")
p.add_argument("--plan", required=True, help="the insertion plan (JSON)")
p.add_argument("--draft", required=True, help="where to write the draft")
p.add_argument("-o", "--output-json", help="also write the JSON result here")
p.set_defaults(func=cmd_apply)
p = sub.add_parser("check", help="Check that a refined document preserves the original.")
p.add_argument("--original", required=True, help="the architecture document")
p.add_argument("--refined", required=True, help="the refined document or draft")
p.set_defaults(func=cmd_check)
p = sub.add_parser("promote", help="Replace the output with the draft, keeping the earlier output.")
p.add_argument("--original", required=True, help="the architecture document")
p.add_argument("--draft", required=True, help="the draft to promote")
p.add_argument("--output", required=True, help="the refined document's path")
p.add_argument("--timestamp", required=True, type=_timestamp,
help="the run's timestamp, YYYYMMDD-HHmmss, for the earlier output's new name")
p.add_argument("-o", "--output-json", help="also write the JSON result here")
p.set_defaults(func=cmd_promote)
p = sub.add_parser("context", help="Merge the run's records into the result contract's payload.")
p.add_argument("--inspect", required=True, help="inspect's -o record")
p.add_argument("--apply", required=True, help="apply's -o record")
p.add_argument("--promote", required=True, help="promote's -o record")
p.add_argument("--out", required=True, help="where to write the payload")
p.set_defaults(func=cmd_context)
p = sub.add_parser("rules", help="Check the refinement rules: the six tables and the tier rules.")
p.add_argument("--rules", required=True, help="the refinement rules file")
p.set_defaults(func=cmd_rules)
p = sub.add_parser("verdicts", help="Join the [VS] report's verdicts to the inventory and the scope.")
p.add_argument("--report", required=True, help="the [VS] feasibility report the run uses")
p.add_argument("--generated-at", required=True,
help="the report's generatedAt when the run started, \"\" when it had none")
p.add_argument("--skills", required=True, help="JSON array of the inventory's skills, names or {name, aliases}")
p.add_argument("--in-scope", required=True, help="the in-scope skill names, comma-separated")
p.add_argument("--rules", required=True, help="the refinement rules file")
p.set_defaults(func=cmd_verdicts)
return parser
def main(argv: list[str] | None = None) -> int:
args = _build_parser().parse_args(argv)
try:
result, code = args.func(args)
except DocError as e:
result, code = {"status": "error", "error": str(e)}, 2
except (WriteError, HelperMissing) as e:
result, code = {"status": "error", "error": str(e)}, 3
text = json.dumps(result, indent=2, ensure_ascii=False)
if getattr(args, "output_json", None) and code == 0:
try:
write_atomic(Path(args.output_json), (text + "\n").encode("utf-8"))
except WriteError as e:
message = str(e)
if args.command == "promote":
left = _undo_promote(args, result)
message += f"; {left}" if left else ""
result, code = {"status": "error", "error": message}, 3
text = json.dumps(result, indent=2, ensure_ascii=False)
print(text)
return code
def _force_utf8(*streams) -> None:
"""Reconfigure stdout and stderr to UTF-8, keeping each stream's error handler.
A Windows console pipes them as cp1252, which cannot print every character
a document line or a path may hold.
"""
for stream in streams:
if hasattr(stream, "reconfigure"):
errors = getattr(stream, "errors", None)
if errors is None:
stream.reconfigure(encoding="utf-8")
else:
stream.reconfigure(encoding="utf-8", errors=errors)
if __name__ == "__main__":
_force_utf8(sys.stdout, sys.stderr)
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |