skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/converters/skills/mermaid-render/scripts/render_mermaid.py

@@ -0,0 +1,486 @@
+#!/usr/bin/env python3
+"""Lint Mermaid diagrams for the errors that stop them rendering, then render them.
+
+Stdlib only, Python 3.9+.
+
+Lint catches, with line numbers: an unknown diagram type on the first line, unbalanced
+brackets or quotes in node labels, unquoted parentheses or brackets inside a label, the
+reserved word `end` used as a flowchart node id, a missing or single-dash arrow, and a
+subgraph (or sequence `alt`/`loop`/... block) with no `end`.
+
+Render uses `mmdc` (mermaid-cli) for .svg/.png/.pdf when it is on PATH. Without it, the
+script writes a standalone .html that draws the diagrams with a pinned Mermaid from
+jsDelivr, which needs network when the file is opened.
+
+Usage:
+    python3 render_mermaid.py diagram.mmd                  # lint only
+    python3 render_mermaid.py diagram.mmd -o diagram.svg   # lint, then render
+    python3 render_mermaid.py design.md -o figs/arch.svg   # every ```mermaid fence -> arch-1.svg, arch-2.svg ...
+    python3 render_mermaid.py design.md -o design.html     # one HTML page with every diagram
+"""
+
+import argparse
+import base64
+import difflib
+import hashlib
+import html
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+MERMAID_VERSION = "11.4.1"
+MERMAID_URL = "https://cdn.jsdelivr.net/npm/mermaid@%s/dist/mermaid.esm.min.mjs" % MERMAID_VERSION
+MERMAID_INIT = ('import mermaid from "%s";'
+                'mermaid.initialize({startOnLoad:true,securityLevel:"strict"});' % MERMAID_URL)
+MERMAID_INIT_HASH = base64.b64encode(hashlib.sha256(MERMAID_INIT.encode("utf-8")).digest()).decode("ascii")
+
+# Diagram keywords Mermaid 11.4 recognises on the first line.
+DIAGRAM_TYPES = [
+    "flowchart", "graph", "sequenceDiagram", "classDiagram", "classDiagram-v2", "stateDiagram",
+    "stateDiagram-v2", "erDiagram", "journey", "gantt", "pie", "quadrantChart", "requirementDiagram",
+    "gitGraph", "C4Context", "C4Container", "C4Component", "C4Dynamic", "C4Deployment", "mindmap",
+    "timeline", "zenuml", "sankey-beta", "xychart-beta", "block-beta", "packet-beta",
+    "architecture-beta", "kanban",
+]
+DIRECTIONS = {"TB", "TD", "BT", "RL", "LR"}
+FLOW_KEYWORDS = ("classDef", "class", "style", "linkStyle", "click", "direction", "accTitle",
+                 "accDescr", "title")
+SEQ_OPEN = ("loop", "alt", "opt", "par", "critical", "break", "rect", "box")
+SEQ_MIDDLE = {"else": ("alt",), "and": ("par",), "option": ("critical",)}
+
+# Node shapes, longest opener first. Each maps to the closers that may end it.
+SHAPES = [("(((", (")))",)), ("((", ("))",)), ("([", ("])",)), ("[[", ("]]",)), ("[(", (")]",)),
+          ("[/", ("/]", "\\]")), ("[\\", ("\\]", "/]")), ("{{", ("}}",)), ("[", ("]",)),
+          ("(", (")",)), ("{", ("}",)), (">", ("]",))]
+ID_RE = re.compile(r"[^\W](?:[\w.]|-(?=\w))*", re.U)
+LINK_RE = re.compile(r"\s*(?:<|(?<=\s)[ox](?=[-=]))?(?:-{2,}|={2,}|-\.+-|~{3,})(?:[->ox](?!\w))?>?\s*")
+
+
+class Issue:
+    def __init__(self, line, level, msg):
+        self.line, self.level, self.msg = line, level, msg
+
+
+def strip_edge_labels(s):
+    s = re.sub(r"\|[^|]*\|", " ", s)                                              # -->|label|
+    s = re.sub(r"-\.(?=[^.\->\s]|\s+[^.\->])\s*([^\n]*?)\s*\.-+>?", " -.-> ", s)  # -. label .->
+    s = re.sub(r"(?<![-<.=])--(?!-|>|[ox]\s)\s*([^-|>\n][^|>\n]*?)\s*(?:-{2,}>|-{3,})", " --> ", s)
+    s = re.sub(r"(?<![=<])==(?!=|>)\s*([^=|>\n][^|>\n]*?)\s*(?:={2,}>|={3,})", " ==> ", s)
+    return s
+
+
+def split_statements(line):
+    """Split on ; outside quotes."""
+    out, cur, q = [], "", False
+    for ch in line:
+        if ch == '"':
+            q = not q
+        if ch == ";" and not q:
+            out.append(cur)
+            cur = ""
+        else:
+            cur += ch
+    out.append(cur)
+    return [s for s in out if s.strip()]
+
+
+def scan_nodes(part, ln, issues):
+    """Walk one link-free chunk: node ids, their shapes, & separators. Returns node ids."""
+    i, n = 0, len(part)
+    ids, need_sep = [], False
+    while i < n:
+        c = part[i]
+        if c.isspace():
+            i += 1
+            continue
+        if c == "&":
+            need_sep = False
+            i += 1
+            continue
+        m = ID_RE.match(part, i)
+        if not m:
+            if c in ")]}":
+                issues.append(Issue(ln, "error", "closing `%s` with no matching opening bracket" % c))
+            elif c in "([{":
+                issues.append(Issue(ln, "error", "a shape `%s` with no node id before it" % c))
+            elif c == '"':
+                issues.append(Issue(ln, "error", "a quoted label must sit inside a shape, as id[\"label\"]"))
+            elif part.startswith("->", i) or part.startswith("=>", i):
+                issues.append(Issue(ln, "error", "`%s` is not a flowchart arrow; use `-->` (or `==>`)"
+                                    % part[i:i + 2]))
+                i += 2
+                need_sep = False
+                continue
+            else:
+                issues.append(Issue(ln, "error", "unexpected `%s`" % c))
+            return ids
+        nid = m.group(0)
+        if need_sep:
+            issues.append(Issue(ln, "error", "no arrow between `%s` and `%s`; join them with `-->`"
+                                % (ids[-1], nid)))
+        ids.append(nid)
+        if nid == "end":
+            issues.append(Issue(ln, "error", "`end` is reserved in flowcharts and breaks the diagram; "
+                                "use `End`, `END` or `done` as the node id"))
+        i = m.end()
+        if part.startswith("@{", i):
+            j = part.find("}", i)
+            if j < 0:
+                issues.append(Issue(ln, "error", "`@{` shape block is never closed with `}`"))
+                return ids
+            i = j + 1
+        else:
+            for opener, closers in SHAPES:
+                if not part.startswith(opener, i):
+                    continue
+                i += len(opener)
+                if part[i:i + 1] == '"':
+                    j = part.find('"', i + 1)
+                    if j < 0:
+                        issues.append(Issue(ln, "error", "unbalanced quote in the label of `%s`" % nid))
+                        return ids
+                    i = j + 1
+                    while i < n and part[i] == " ":
+                        i += 1
+                    hit = [cl for cl in closers if part.startswith(cl, i)]
+                    if not hit:
+                        issues.append(Issue(ln, "error", "label of `%s` opens with `%s` but does not close "
+                                            "with `%s` after the quotes" % (nid, opener, closers[0])))
+                        return ids
+                    i += len(hit[0])
+                else:
+                    found = [(part.find(cl, i), cl) for cl in closers if part.find(cl, i) >= 0]
+                    if not found:
+                        issues.append(Issue(ln, "error", "unbalanced brackets: `%s%s` is never closed with `%s`"
+                                            % (nid, opener, closers[0])))
+                        return ids
+                    pos, cl = min(found)
+                    label = part[i:pos]
+                    bad = sorted({ch for ch in label if ch in '()[]{}"'})
+                    if bad:
+                        issues.append(Issue(ln, "error", "label of `%s` has unquoted %s; wrap the label in "
+                                            "quotes: %s%s\"%s\"%s" % (nid, " ".join("`%s`" % b for b in bad),
+                                                                    nid, opener, label.replace('"', "'"), cl)))
+                    i = pos + len(cl)
+                break
+        m2 = re.match(r":::[\w-]+", part[i:])
+        if m2:
+            i += m2.end()
+        need_sep = True
+    return ids
+
+
+def lint_flowchart(lines, issues):
+    stack = []
+    for ln, raw in lines:
+        s = raw.strip()
+        if not s or s.startswith("%%"):
+            continue
+        word = s.split()[0]
+        if word == "subgraph":
+            stack.append(ln)
+            rest = s[len("subgraph"):].strip()
+            if rest.count('"') % 2:
+                issues.append(Issue(ln, "error", "unbalanced quote in the subgraph title"))
+            elif re.match(r'^"[^"]*"$', rest):
+                pass
+            elif re.match(r"^[^\W][\w.-]*\s*[\[({>]", rest, re.U):
+                scan_nodes(rest, ln, issues)              # subgraph id[label]
+            elif re.search(r"[\[\](){}]", rest):
+                issues.append(Issue(ln, "error", "subgraph title has unquoted brackets; write "
+                                    "subgraph id[\"%s\"]" % rest.replace('"', "'")))
+            continue
+        if s == "end":
+            if stack:
+                stack.pop()
+            else:
+                issues.append(Issue(ln, "error", "`end` with no open subgraph"))
+            continue
+        if word in FLOW_KEYWORDS or word.startswith(("accTitle:", "accDescr")):
+            continue
+        for stmt in split_statements(s):
+            if stmt.count('"') % 2:
+                issues.append(Issue(ln, "error", "unbalanced double quote"))
+                continue
+            if re.search(r"(?:-{2,}|={2,})[ox][A-Za-z0-9_]", stmt):
+                issues.append(Issue(ln, "warning", "`--o`/`--x` followed by a letter is read as a circle or "
+                                    "cross arrowhead; add a space if the node id starts with o or x"))
+            for lab in re.findall(r"\|([^|]*)\|", stmt):
+                inner = lab.strip()
+                bad = sorted({ch for ch in inner if ch in "()[]{}"})
+                if bad and not (inner.startswith('"') and inner.endswith('"')):
+                    issues.append(Issue(ln, "error", "arrow label |%s| has unquoted %s; quote it: |\"%s\"|"
+                                        % (inner, " ".join("`%s`" % b for b in bad), inner)))
+            body = strip_edge_labels(stmt)
+            parts = LINK_RE.split(body)
+            if len(parts) > 1 and (not parts[0].strip() or not parts[-1].strip()):
+                issues.append(Issue(ln, "error", "an arrow with no node on one side"))
+            for part in parts:
+                if part.strip():
+                    scan_nodes(part, ln, issues)
+    for ln in stack:
+        issues.append(Issue(ln, "error", "subgraph opened here has no matching `end`"))
+
+
+def lint_sequence(lines, issues):
+    stack = []
+    for ln, raw in lines:
+        s = raw.strip()
+        if not s or s.startswith("%%"):
+            continue
+        word = s.split()[0]
+        if word in SEQ_OPEN:
+            stack.append((word, ln))
+        elif word in SEQ_MIDDLE:
+            if not stack or stack[-1][0] not in SEQ_MIDDLE[word]:
+                issues.append(Issue(ln, "error", "`%s` outside a `%s` block" % (word, SEQ_MIDDLE[word][0])))
+        elif s == "end":
+            if stack:
+                stack.pop()
+            else:
+                issues.append(Issue(ln, "error", "`end` with no open loop/alt/opt/par/critical/break/rect/box"))
+        elif re.search(r"(?:-{1,2}>>?|-{1,2}[x)])", s) and ":" not in s and not s.startswith(("participant", "actor", "Note", "note", "autonumber", "activate", "deactivate", "create", "destroy", "title", "link", "links")):
+            issues.append(Issue(ln, "error", "message without `: text`; write `A->>B: what is sent`"))
+    for word, ln in stack:
+        issues.append(Issue(ln, "error", "`%s` block opened here has no matching `end`" % word))
+
+
+def lint_braces(lines, issues):
+    depth, opened = 0, []
+    for ln, raw in lines:
+        s = re.sub(r'"[^"]*"', "", raw)
+        # erDiagram cardinality markers such as ||--o{ and }|..|{ are not braces
+        s = re.sub(r"(?:\|o|\|\||\}o|\}\|)(?:--|\.\.)(?:o\||\|\||o\{|\|\{)", " ", s)
+        if s.strip().startswith("%%"):
+            continue
+        for ch in s:
+            if ch == "{":
+                depth += 1
+                opened.append(ln)
+            elif ch == "}":
+                if depth == 0:
+                    issues.append(Issue(ln, "error", "`}` with no matching `{`"))
+                else:
+                    depth -= 1
+                    opened.pop()
+    for ln in opened:
+        issues.append(Issue(ln, "error", "`{` opened here is never closed"))
+
+
+def lint(text, first_line=1):
+    """Lint one diagram. first_line is the file line number of the diagram's first line."""
+    issues = []
+    lines = [(first_line + k, l) for k, l in enumerate(text.split("\n"))]
+    k = 0
+    # skip front matter (--- ... ---), %%{init}%% directives and comments
+    while k < len(lines) and not lines[k][1].strip():
+        k += 1
+    if k < len(lines) and lines[k][1].strip() == "---":
+        k += 1
+        while k < len(lines) and lines[k][1].strip() != "---":
+            k += 1
+        k += 1
+    while k < len(lines) and (not lines[k][1].strip() or lines[k][1].strip().startswith("%%")):
+        k += 1
+    if k >= len(lines):
+        return [Issue(first_line, "error", "the diagram is empty")], None
+    ln, head = lines[k]
+    words = head.strip().split()
+    kind = words[0].rstrip(";:")
+    if kind not in DIAGRAM_TYPES:
+        guess = difflib.get_close_matches(kind, DIAGRAM_TYPES, n=1, cutoff=0.6)
+        hint = " Did you mean `%s`?" % guess[0] if guess else " Start with one of: flowchart, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, gantt."
+        issues.append(Issue(ln, "error", "unknown diagram type `%s` on the first line.%s" % (kind, hint)))
+        return issues, None
+    body = lines[k + 1:]
+    if kind in ("flowchart", "graph"):
+        if len(words) > 1 and words[1].rstrip(";") not in DIRECTIONS:
+            issues.append(Issue(ln, "error", "unknown direction `%s`; use TD, TB, BT, LR or RL" % words[1]))
+        lint_flowchart(body, issues)
+    elif kind == "sequenceDiagram":
+        lint_sequence(body, issues)
+    elif kind in ("classDiagram", "classDiagram-v2", "stateDiagram", "stateDiagram-v2", "erDiagram"):
+        lint_braces(body, issues)
+    if not any(l.strip() and not l.strip().startswith("%%") for _, l in body) and kind not in ("pie",):
+        issues.append(Issue(ln, "warning", "the diagram has a type but no content"))
+    return issues, kind
+
+
+# ---------------------------------------------------------------- input
+
+def extract_fences(text):
+    """Return [(first_line_number, diagram_text)] for every ```mermaid / ~~~mermaid fence."""
+    out = []
+    lines = text.split("\n")
+    i = 0
+    while i < len(lines):
+        m = re.match(r"^\s{0,3}(`{3,}|~{3,})\s*mermaid\b", lines[i])
+        if m:
+            fence = m.group(1)
+            start = i + 2  # 1-based line number of the first diagram line
+            body = []
+            i += 1
+            while i < len(lines) and not re.match(r"^\s{0,3}%s%s*\s*$" % (re.escape(fence), re.escape(fence[0])), lines[i]):
+                body.append(lines[i])
+                i += 1
+            if i >= len(lines):
+                out.append((start, "\n".join(body), "unclosed"))
+            else:
+                out.append((start, "\n".join(body), None))
+        i += 1
+    return out
+
+
+# ---------------------------------------------------------------- render
+
+def html_page(diagrams, title):
+    csp = ("default-src 'none'; script-src 'sha256-%s' https://cdn.jsdelivr.net; "
+           "style-src 'unsafe-inline'; img-src data: https:; font-src data: https:; "
+           "connect-src https://cdn.jsdelivr.net" % MERMAID_INIT_HASH)
+    figs = []
+    for k, (label, text) in enumerate(diagrams, 1):
+        figs.append('<figure><pre class="mermaid">%s</pre><figcaption>%s</figcaption></figure>'
+                    % (html.escape(text), html.escape(label)))
+    return """<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="%s">
+<title>%s</title>
+<style>
+body{font-family:-apple-system,'Segoe UI',Helvetica,Arial,sans-serif;margin:2rem auto;max-width:72rem;padding:0 1rem;color:#222}
+figure{margin:0 0 2.5rem;border:1px solid #e3e3e3;border-radius:6px;padding:1rem}
+figcaption{font-size:.85rem;color:#666;margin-top:.5rem}
+pre.mermaid{text-align:center;background:#fff;margin:0}
+.note{font-size:.85rem;color:#666}
+@media print{figure{break-inside:avoid;border:0}.note{display:none}}
+</style>
+</head>
+<body>
+<p class="note">Drawn by Mermaid %s loaded from cdn.jsdelivr.net; this page needs network when opened.</p>
+%s
+<script type="module">%s</script>
+</body>
+</html>
+""" % (csp, html.escape(title), MERMAID_VERSION, "\n".join(figs), MERMAID_INIT)
+
+
+def run_mmdc(exe, text, out_path):
+    with tempfile.TemporaryDirectory() as tmp:
+        src = Path(tmp) / "diagram.mmd"
+        src.write_text(text, encoding="utf-8")
+        cmd = [exe, "-i", str(src), "-o", str(out_path)]
+        if out_path.suffix.lower() == ".png":
+            cmd += ["-b", "white", "-s", "2"]
+        try:
+            proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=180, check=False)
+        except subprocess.TimeoutExpired:
+            return "mmdc timed out after 180 s"
+        if proc.returncode != 0:
+            return mmdc_error((proc.stderr or proc.stdout).decode("utf-8", "replace"))
+    return None
+
+
+def mmdc_error(raw):
+    """Mermaid's own message (from "Error:" up to the stack trace), not the stack trace:
+    mmdc prints a browser-library trace after the parse error, and the parse error is the
+    part a person can act on."""
+    lines = raw.strip().splitlines()
+    start = next((k for k, l in enumerate(lines) if l.lstrip().startswith("Error")), 0)
+    keep = []
+    for l in lines[start:]:
+        if re.match(r"^\s+at\s", l) or re.search(r"\((https?|file)://[^)]*\)\s*$", l):
+            break
+        keep.append(l.rstrip())
+    msg = "\n".join(keep[:8]).strip()
+    return msg or raw.strip()[-800:]
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Lint Mermaid diagrams, then render to svg/png/pdf (mmdc) or html.")
+    ap.add_argument("input", help=".mmd/.mermaid file with one diagram, or .md with ```mermaid fences")
+    ap.add_argument("-o", "--output", help="out.svg | out.png | out.pdf | out.html. Leave out to lint only.")
+    ap.add_argument("--force", action="store_true", help="render even when lint finds errors")
+    a = ap.parse_args(argv)
+
+    src = Path(a.input)
+    if not src.is_file():
+        sys.exit("error: input not found: %s" % a.input)
+    try:
+        text = src.read_text(encoding="utf-8-sig").replace("\r\n", "\n")
+    except UnicodeDecodeError:
+        sys.exit("error: %s is not UTF-8 text" % a.input)
+
+    if src.suffix.lower() in (".md", ".markdown"):
+        fences = extract_fences(text)
+        if not fences:
+            sys.exit("error: no ```mermaid fences found in %s" % a.input)
+        diagrams = fences
+    else:
+        diagrams = [(1, text, None)]
+
+    errors = warnings = 0
+    for k, (start, body, flag) in enumerate(diagrams, 1):
+        issues, kind = lint(body, start)
+        if flag == "unclosed":
+            issues.insert(0, Issue(start - 1, "error", "the ```mermaid fence is never closed"))
+        label = "diagram %d (%s)" % (k, kind or "unknown type") if len(diagrams) > 1 else (kind or "diagram")
+        if not issues:
+            print("%s: %s: ok" % (src.name, label))
+        for it in sorted(issues, key=lambda x: x.line):
+            print("%s:%d: %s: %s" % (src.name, it.line, it.level, it.msg))
+            if it.level == "error":
+                errors += 1
+            else:
+                warnings += 1
+    print("lint: %d diagram(s), %d error(s), %d warning(s)" % (len(diagrams), errors, warnings))
+
+    if not a.output:
+        return 1 if errors else 0
+    if errors and not a.force:
+        sys.stdout.flush()
+        print("not rendering: fix the errors above, or rerun with --force", file=sys.stderr)
+        return 1
+
+    out = Path(a.output)
+    if not out.parent.exists():
+        sys.exit("error: output folder does not exist: %s" % out.parent)
+    ext = out.suffix.lower()
+    if ext not in (".svg", ".png", ".pdf", ".html", ".htm"):
+        sys.exit("error: output must end in .svg, .png, .pdf or .html")
+    many = len(diagrams) > 1
+    labels = ["%s, diagram %d (line %d)" % (src.name, k, d[0]) if many else src.name
+              for k, d in enumerate(diagrams, 1)]
+
+    exe = shutil.which("mmdc") if ext in (".svg", ".png", ".pdf") else None
+    if exe:
+        failed = 0
+        for k, (start, body, _) in enumerate(diagrams, 1):
+            target = out.with_name("%s-%d%s" % (out.stem, k, out.suffix)) if many else out
+            err = run_mmdc(exe, body, target)
+            if err:
+                failed += 1
+                print("mmdc failed on %s:\n%s" % (labels[k - 1], err), file=sys.stderr)
+            else:
+                print("wrote %s" % target)
+        return 1 if failed else 0
+
+    target = out if ext in (".html", ".htm") else out.with_suffix(".html")
+    target.write_text(html_page([(labels[k], d[1]) for k, d in enumerate(diagrams)], src.name), encoding="utf-8")
+    if ext not in (".html", ".htm"):
+        print("mmdc (mermaid-cli) is not on PATH, so no %s was written. Wrote %s instead: it draws "
+              "the diagram(s) with Mermaid %s from cdn.jsdelivr.net and needs network when opened. "
+              "For %s output: npm install -g @mermaid-js/mermaid-cli, then rerun."
+              % (ext, target, MERMAID_VERSION, ext))
+    else:
+        print("wrote %s (%d diagram(s); draws with Mermaid %s from cdn.jsdelivr.net, needs network when opened)"
+              % (target, len(diagrams), MERMAID_VERSION))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

skilldrop_cli/data/packs/core/loops/ship-a-draft/LOOP.md

@@ -0,0 +1,77 @@
+---
+name: ship-a-draft
+description: Take raw mess to a stakeholder-ready artifact by wrapping any skilldrop generator in the two passes either side of it — structured intake before, critique and machine-residue scrub after. Use when the user has notes, a transcript, or a ticket and wants a finished document rather than a first draft.
+---
+
+# ship-a-draft
+
+A **wrapper**, not a lifecycle loop. Its centre stage is whichever generator the user actually
+needs — an ADR, a design doc, a runbook, a deck, an exec summary. The wrapper contributes the
+two passes every generator otherwise leaves to chance: collect the input properly before, and
+check the argument and the surface after.
+
+## Stages
+
+| # | Stage | Type | Skills | Gate |
+|---|---|---|---|---|
+| 1 | `intake` | generate | [`brief-intake`](../../skills/brief-intake/SKILL.md) | — |
+| 2 | `draft` | generate | any generator (`*`) | — |
+| 3 | `critique` | verify | [`doc-critique`](../../skills/doc-critique/SKILL.md) | **G4** review |
+| 4 | `polish` | verify | [`output-hygiene`](../../skills/output-hygiene/SKILL.md) | — |
+
+## How to run this wrapper
+
+1. **Pick the generator first.** The brief is shaped *for a target*, so `draft` is chosen
+   before `intake` runs, not after. `brief-intake`'s own routing table maps trigger phrases to
+   targets; use it.
+2. **Collect once.** Run `brief-intake`. Every field is tagged `[explicit]` / `[implied]` /
+   `[inferred]` / `[missing]`, and its "Missing for downstream" section predicts what the
+   chosen generator will refuse to start without. Resolve those before drafting.
+3. **Draft.** Run the chosen generator on the brief. It is a normal skilldrop skill with its
+   own quality bar — this wrapper does not override it.
+4. **Critique at G4.** Run `doc-critique`, which dispatches to the same rubric the generator
+   was held to. `MAJOR REWRITE` returns to `intake` (not to `draft` — a rewrite usually means
+   the input was wrong, not the prose). `WRONG ARTIFACT` leaves the wrapper entirely.
+5. **Polish last.** Run `output-hygiene` only once the argument is settled. It is a surface
+   pass; running it on a draft that is about to be rewritten wastes it.
+
+## Verdicts
+
+Defined in [`contracts/terminals.json`](../../../../contracts/terminals.json). G4 emits the critique
+vocabulary. `SHIP WITH CHANGES` carries its changes forward to `polish`; it does not mean the
+changes are optional.
+
+## When a stage's skill is not installed
+
+Name the missing skill and skilldrop as its source, do the minimal inline version of that
+stage, and say the stage ran degraded. Do not skip G4 — an unreviewed artifact is the failure
+mode this wrapper exists to prevent.
+
+## Run log (opt-in)
+
+Only when the environment variable `SKILLDROP_LOOP_LOG` is set to a file path: after each
+gate's verdict, append one JSON line to that file. Nothing else is recorded, and nothing is
+sent anywhere. When the variable isn't set, or you can't read it, skip this section.
+
+```bash
+printf '%s\n' '{"ts":"2026-10-01T14:03:00Z","loop":"ship-a-draft","stage":"critique","gate":"G4","verdict":"SHIP IT","round":1}' >> "$SKILLDROP_LOOP_LOG"
+```
+
+Fields: `ts` (UTC), `loop`, `stage`, `gate` (`null` for a stage without one), `verdict` (the
+gate's exact word), and `round` (1 for the first attempt, counting returns under the cap).
+`skilldrop loop-stats` summarises the file: which gates pass first time, which loop back, and
+which end in `BLOCKED`.
+
+## Quality bar
+
+- **The generator is chosen before intake runs.** A brief collected for no particular target is a summary, and downstream will reject it for missing fields.
+- **`polish` runs after the argument is settled, never before.** Scrubbing prose that is about to be rewritten is wasted work and hides the rewrite.
+- **A `[missing]` tag is resolved or stated, never silently filled.** Fabricating a goal, an owner, or a decision corrupts every downstream artifact.
+- **Every run ends by naming what was not touched.** `output-hygiene`'s "Not touched" section is part of the deliverable, not an appendix.
+
+## Anti-patterns to avoid
+
+- ❌ **Running `polish` as the whole review.** Clean prose with a broken argument still fails; that is what G4 is for.
+- ❌ **Skipping `intake` because the input "is already structured."** A Slack thread that looks organized is still untagged — nobody downstream can tell what was inferred.
+- ❌ **Looping `critique` → `draft` instead of `critique` → `intake`.** Re-drafting from the same incomplete brief reproduces the same gaps with new words.
+- ❌ **Treating `WRONG ARTIFACT` as a severe `MAJOR REWRITE`.** It is a redirect: the user wanted a different document, and revising this one cannot get there.

skilldrop_cli/data/packs/core/loops/ship-a-draft/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "turn these notes into something I can send",
+    "should_trigger": true
+  },
+  {
+    "query": "run ship-a-draft on this transcript",
+    "should_trigger": true
+  },
+  {
+    "query": "take this ticket to a finished document",
+    "should_trigger": true
+  },
+  {
+    "query": "polish this draft and check the argument",
+    "should_trigger": true
+  },
+  {
+    "query": "implement this feature",
+    "should_trigger": false
+  },
+  {
+    "query": "gate my pull request",
+    "should_trigger": false
+  },
+  {
+    "query": "what should our OKRs be?",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/core/loops/ship-a-draft/evals/evals.json

@@ -0,0 +1,25 @@
+{
+  "loop_name": "ship-a-draft",
+  "evals": [
+    {
+      "id": "picks-the-generator-before-collecting",
+      "prompt": "Run ship-a-draft on this Slack thread — I need something the exec team can read.",
+      "assertions": [
+        "Chooses the target generator (exec-summary) BEFORE running intake, because the brief is shaped for a target",
+        "Runs brief-intake and tags every field explicit / implied / inferred / missing",
+        "Runs doc-critique at G4 against the same rubric the generator was held to",
+        "Runs output-hygiene last, only once the argument is settled",
+        "Reports what output-hygiene did not touch"
+      ]
+    },
+    {
+      "id": "major-rewrite-returns-to-intake",
+      "prompt": "The critique on my draft came back MAJOR REWRITE. Continue the ship-a-draft wrapper.",
+      "assertions": [
+        "Routes back to `intake`, not to `draft`, because G4's revise_to names intake",
+        "Explains that re-drafting from the same incomplete brief reproduces the same gaps",
+        "Does not run output-hygiene on a draft that is about to be rewritten"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/core/loops/ship-a-draft/loop.json

@@ -0,0 +1,41 @@
+{
+  "$comment": "RFC-0028. This wrapper is docs/knowledge-work-pipeline.mmd promoted from a hand-maintained diagram into the machine-readable source that diagram is now generated from. It is a wrapper, not a loop: the generator at its centre is chosen at run time from whichever artifact the user actually wants.",
+  "name": "ship-a-draft",
+  "version": "0.2.0",
+  "description": "Take raw mess to a stakeholder-ready artifact by wrapping any skilldrop generator in the two passes either side of it — structured intake before, critique and machine-residue scrub after. Use when the user has notes, a transcript, or a ticket and wants a finished document rather than a first draft.",
+  "entrypoint": "LOOP.md",
+  "kind": "wrapper",
+  "cap": 3,
+  "stages": [
+    {
+      "id": "intake",
+      "type": "generate",
+      "intent": "Collect the raw input once, into the shape the chosen generator expects, tagging every field explicit / implied / inferred / missing.",
+      "skills": ["brief-intake"]
+    },
+    {
+      "id": "draft",
+      "type": "generate",
+      "intent": "Run the generator the brief was shaped for. Any artifact skill is legal here — that choice is the wrapper's whole point.",
+      "skills": ["*"]
+    },
+    {
+      "id": "critique",
+      "type": "verify",
+      "intent": "Review the draft against the same rubric the generator was held to.",
+      "skills": ["doc-critique"],
+      "gate": {
+        "id": "G4",
+        "kind": "review",
+        "verdicts": ["SHIP IT", "SHIP WITH CHANGES", "MAJOR REWRITE", "WRONG ARTIFACT", "BLOCKED"],
+        "revise_to": "intake"
+      }
+    },
+    {
+      "id": "polish",
+      "type": "verify",
+      "intent": "Strip what the machine left behind before the artifact leaves the building. Surface pass only — never a substitute for the critique above.",
+      "skills": ["output-hygiene"]
+    }
+  ]
+}