burgess 0.1.0

package/skills/burgess/references/schemas.md

@@ -0,0 +1,216 @@
+# Burgess Schemas
+
+Canonical formats for everything in a Burgess strategy repo. Every skill reads this file before writing anything. All state is plain markdown + YAML — nothing a human can't read in a diff.
+
+## Repo layout
+
+Everything lives in a `strategy/` directory (its own git repo, or inside the product repo):
+
+```
+strategy/
+├── evidence/                    # THE PRODUCT — the evidence base
+│   ├── sources.yaml             # registry of every source document/interview
+│   ├── items/                   # one file per evidence item (atomized claims)
+│   │   └── ev-0001.md           # naming: ev-NNNN, monotonic, never reused
+│   └── intake/                  # interview transcripts & answered gap questions
+│       └── intake-2026-07-12.md
+├── decisions/                   # decision log — human judgments, citable
+│   └── dec-001.md               # naming: dec-NNN, monotonic
+├── projections/                 # REGENERABLE — never hand-edited
+│   ├── themes.md
+│   ├── positioning.md
+│   ├── messaging.md             # Phase 2
+│   ├── vision.md                # Phase 3
+│   ├── brand-platform.md        # Phase 3
+│   └── assets/                  # Phase 3
+├── reviews/                     # red-team outputs, one per run, append-only
+│   └── review-2026-07-12.md
+├── scripts/
+│   └── check_stale.py           # copied from the burgess skill at scaffold time
+├── gap-report.md                # always current; regenerated on every ingest/intake
+└── manifest.yaml                # DAG state: hashes, staleness, approval status
+```
+
+## Evidence item — `evidence/items/ev-NNNN.md`
+
+One atomized claim per file. Atomization is what makes staleness tractable: a new document changes *specific items*, not "the context." Granularity rule: prefer more, smaller items; when in doubt, split. A claim that bundles a pain and a capability is two items.
+
+```markdown
+---
+id: ev-0042
+type: user_pain        # user_pain | jtbd | capability | limitation | metric | market |
+                       # competitive | customer_language | winloss | culture | economic
+claim: "Compliance review is where agent pilots stall; teams cannot answer scope-and-authority questions defensibly."
+source: prd            # key into sources.yaml
+location: "§1, §3.1"   # structured identifiers cite directly: "FR-18", "SM-5", "§3.1"
+confidence: stated     # stated | inferred | assumption | secondhand
+date_observed: 2026-07-10   # when the source asserted it (NOT ingestion date)
+tags: [governance, icp-failed-pilot]
+status: active         # active | superseded | disputed
+superseded_by: null    # ev-id when superseded
+---
+Optional prose: verbatim quote from the source, extraction notes, why the
+confidence tag was chosen. Verbatim customer language goes here in full —
+it is the raw material for messaging.
+```
+
+Confidence semantics:
+- `stated` — explicit in an available source.
+- `inferred` — reasonable deduction; the prose says from what.
+- `assumption` — needs human confirmation; downstream use must carry `[A]`.
+- `secondhand` — carried by an available doc on behalf of an unavailable one. May support claims but **never solely** support a differentiator or headline claim.
+
+Item type notes: `customer_language` items must preserve the verbatim quote in the prose body. `winloss` items name the deal outcome and what the buyer chose instead. `culture` items record observed behavior (postmortem practice, privacy stances in architecture) — they feed values in Phase 3.
+
+## Source registry — `evidence/sources.yaml`
+
+```yaml
+sources:
+  - key: prd
+    title: "PRD: Seelray (4795621b-prd.md)"
+    kind: prd            # prd | architecture | interview | winloss | transcript |
+                         # support | review | analyst | other
+    date: 2026-07-10
+    sha256: "<hash of the file if available>"
+    availability: available          # available | referenced_unavailable
+  - key: spec-v0.4
+    title: "Product Specification v0.4"
+    kind: architecture
+    date: null
+    sha256: null
+    availability: referenced_unavailable   # gets an entry so secondhand citations resolve
+```
+
+Referenced-but-unavailable companion docs get registry entries; items citing what an available doc says *on their behalf* use `confidence: secondhand` with `source:` set to the carrying (available) document.
+
+## Intake transcript — `evidence/intake/intake-YYYY-MM-DD.md`
+
+Append-only. Registered in `sources.yaml` (`kind: interview`, key `intake-YYYY-MM-DD`). Format: frontmatter (`date`, `participants`, `driven_by: gap-report`), then Q/A pairs verbatim. Answers are then atomized into evidence items with `source: intake-YYYY-MM-DD`, `confidence: stated`.
+
+## Decision record — `decisions/dec-NNN.md`
+
+```markdown
+---
+id: dec-003
+decides: "v1 market category"
+choice: "Subsegment: agent governance for regulated organisations, from documented authority"
+rejected:
+  - "head-on AI governance platform"
+  - "new category: authority intelligence"
+rationale: "Budget line already exists; new-category economics unjustifiable at n=1-3."
+decided_by: null               # ALWAYS null when an agent proposes; only a human fills it
+date: 2026-07-12
+inputs: [ev-0042, ev-0107, gap-report#q3]
+affects: [projections/positioning.md]
+---
+Optional prose: fuller argument, tradeoffs, review notes.
+```
+
+Agents PROPOSE decision records, leaving `decided_by: null`. An unfilled decision blocks `status: approved` on any artifact that cites it — but not `draft` generation. The `rejected` list is mandatory when proposing: the rejections are what make the choice reviewable.
+
+## Projection frontmatter
+
+Every file in `projections/` (and each file in `projections/assets/`) begins:
+
+```yaml
+---
+artifact: positioning     # themes | positioning | messaging | vision | brand-platform | assets
+status: draft             # draft | approved — only a human flips to approved
+date: 2026-07-12
+depends_on: [themes, decisions]   # manifest node names
+open_questions: []        # anything needing human input; [A]-tagged claims must appear here
+proposed_decisions: []    # dec-ids proposed by this generation, awaiting decided_by
+---
+```
+
+## Citation grammar (used in all projections)
+
+- `[E: ev-0042]` — cites an evidence item (the item carries source/location/confidence).
+- `[E: ev-0042, ev-0107]` — multiple items.
+- **Nothing but ids inside the brackets.** Annotations go outside: `[E: ev-0042] (secondhand, supporting only)` — never `[E: ev-0042 — secondhand]`. The checker rejects annotated tokens as malformed.
+- `[D: dec-003]` — cites a human decision.
+- `[I]` — inference by the generating agent; state inline what it is inferred from.
+- `[A]` — assumption awaiting confirmation; must also appear in the artifact's `open_questions`.
+
+Rules: projections cite items; items cite sources — two hops, each simple. Items with `confidence: secondhand` never *solely* support a differentiator or headline claim. A projection sentence carrying a factual claim with none of these tags is a defect the red team must flag. `gap-report#qN` anchors may be referenced in prose and in decision `inputs` — they are pointers to open questions, not evidence, and never substitute for an `[E:]` tag.
+
+## Gap report — `gap-report.md`
+
+Regenerated (in place) on every ingest and intake; git history is its archive. Structure: frontmatter (`date`, `sources_covered`), then a table per missing evidence type:
+
+| Missing evidence | Why it matters downstream | Question the team can answer | Value/effort |
+
+Evidence types to check: customer language, competitive alternatives, win/loss, market data, usage/commercial ground truth, culture/values evidence. Each gap gets a stable anchor (`q1`, `q2`, …) so decisions can cite `gap-report#q3`. Tier by value-per-effort — win/loss notes and ~5 sales-call transcripts buy more positioning truth than almost anything else; the report says so explicitly.
+
+## Manifest — `manifest.yaml`
+
+```yaml
+version: 1
+nodes:
+  evidence:
+    kind: source
+    paths: [evidence/items, evidence/sources.yaml]
+  decisions:
+    kind: source
+    paths: [decisions]
+  themes:
+    kind: projection
+    file: projections/themes.md
+    depends_on: [evidence]
+    input_hash: null      # recorded by check_stale.py --record at generation
+    output_hash: null     # hand-edit detection
+    generated: null
+  positioning:
+    kind: projection
+    file: projections/positioning.md
+    depends_on: [themes, decisions]
+    input_hash: null
+    output_hash: null
+    generated: null
+  messaging:
+    kind: projection
+    file: projections/messaging.md
+    depends_on: [positioning]
+    input_hash: null
+    output_hash: null
+    generated: null
+  vision:
+    kind: projection
+    file: projections/vision.md
+    depends_on: [themes, decisions]
+    input_hash: null
+    output_hash: null
+    generated: null
+  brand-platform:
+    kind: projection
+    file: projections/brand-platform.md
+    depends_on: [vision, positioning, messaging]
+    input_hash: null
+    output_hash: null
+    generated: null
+  assets:
+    kind: projection
+    file: projections/assets
+    depends_on: [messaging, brand-platform]
+    input_hash: null
+    output_hash: null
+    generated: null
+```
+
+This exact content is the scaffold template — write it verbatim on first run (it is valid before anything is generated).
+
+### Hash rules (implemented by `scripts/check_stale.py` — never compute by hand)
+
+- File hash: sha256 of raw bytes. Directory hash: sha256 over `relpath\n<file-hash>\n` for files sorted by path.
+- `evidence` node hash: directory hash over `evidence/items/` **excluding items whose `status:` is `superseded`**, plus `sources.yaml`. (Flipping an item to superseded changes membership, so downstream goes stale — correct. Editing an already-superseded item does not — also correct.) `evidence/intake/` is excluded: transcripts affect nothing until atomized into items.
+- `decisions` node hash: directory hash over `decisions/`.
+- Projection node current hash: file (or directory, for `assets`) hash of its output.
+- `input_hash` of a node: sha256 over `"{dep}={current hash of dep}\n"` for its `depends_on`, sorted.
+- **Stale** = recorded `input_hash` ≠ the same computation today. Computed, never asserted.
+- **Hand-edited** = projection's current hash ≠ recorded `output_hash`. Projections are regenerated, not edited; a hand-edit means information is trapped outside the evidence base.
+
+After regenerating any projection, run `python scripts/check_stale.py --record <node>` to record its hashes. Regenerating an `approved` artifact demotes it to `draft` in its own frontmatter (the human re-approves the projection of new evidence).
+
+## Review — `reviews/review-YYYY-MM-DD.md`
+
+One per red-team run, append-only (suffix `-2`, `-3` for multiple runs in a day). Frontmatter: `date`, `artifacts_reviewed`, `run_reason` (post-regeneration | on-demand). Body per the red-team skill: vertical coherence table (pass/fail with break point), horizontal consistency checks, adversarial personas (severity-rated, no pass/fail), findings table routed to owning artifacts.

package/skills/burgess/scripts/check_stale.py

@@ -0,0 +1,400 @@
+#!/usr/bin/env python3
+"""Burgess staleness checker. Stdlib only; suitable for CI.
+
+Walks the dependency DAG in manifest.yaml, recomputes content hashes, and reports
+which projections are stale, hand-edited, or missing, plus citation resolution.
+Exit code is non-zero if anything needs attention.
+
+Usage:
+  python check_stale.py [--repo PATH] [--json]
+  python check_stale.py --record NODE[,NODE...]   # after regenerating those nodes
+  python check_stale.py --record all              # record every projection that exists
+
+Hash rules (see references/schemas.md):
+  file hash        = sha256(bytes)
+  dir hash         = sha256 over "relpath\\n<file-hash>\\n", files sorted by relpath
+  evidence node    = dir hash over evidence/items (excluding status: superseded) + sources.yaml
+  decisions node   = dir hash over decisions/
+  projection node  = file/dir hash of its output
+  input_hash(node) = sha256 over "dep=<current hash of dep>\\n" for depends_on, sorted
+  stale            = recorded input_hash != input_hash computed today
+  hand-edited      = current output hash != recorded output_hash
+"""
+
+import argparse
+import datetime
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path
+
+# ---------------------------------------------------------------- yaml subset
+
+def _scalar(tok):
+    tok = tok.strip()
+    if tok[:1] in ("'", '"'):
+        end = tok.find(tok[0], 1)
+        if end != -1:
+            return tok[1:end]
+    tok = tok.split(" #", 1)[0].rstrip()
+    if tok in ("null", "~", ""):
+        return None
+    return tok
+
+
+def _flow_list(tok):
+    inner = tok.strip()[1:-1].strip()
+    if not inner:
+        return []
+    return [_scalar(p) for p in inner.split(",")]
+
+
+def parse_yaml(text):
+    """Parse the restricted YAML subset Burgess writes: nested mappings by
+    2-space indent, scalar values, flow lists, block lists of scalars."""
+    lines = []
+    for raw in text.splitlines():
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        lines.append(raw.rstrip())
+
+    def parse_block(i, indent):
+        result = None
+        while i < len(lines):
+            line = lines[i]
+            cur = len(line) - len(line.lstrip(" "))
+            if cur < indent:
+                break
+            if cur > indent:
+                raise ValueError(f"unexpected indent at line: {line!r}")
+            body = line.strip()
+            if body.startswith("- "):
+                if result is None:
+                    result = []
+                if not isinstance(result, list):
+                    raise ValueError(f"mixed list/map at: {line!r}")
+                result.append(_scalar(body[2:]))
+                i += 1
+                continue
+            if result is None:
+                result = {}
+            if not isinstance(result, dict):
+                raise ValueError(f"mixed list/map at: {line!r}")
+            key, _, rest = body.partition(":")
+            rest = rest.strip()
+            if rest.startswith("#"):
+                rest = ""
+            elif rest and rest[0] not in ("'", '"'):
+                rest = rest.split(" #", 1)[0].rstrip()
+            if rest == "":
+                child, i2 = parse_block(i + 1, indent + 2)
+                result[key.strip()] = child if child is not None else None
+                i = i2
+            elif rest.startswith("["):
+                result[key.strip()] = _flow_list(rest)
+                i += 1
+            else:
+                result[key.strip()] = _scalar(rest)
+                i += 1
+        return result, i
+
+    parsed, _ = parse_block(0, 0)
+    return parsed or {}
+
+
+def emit_yaml(node, indent=0):
+    pad = "  " * indent
+    out = []
+    if isinstance(node, dict):
+        for k, v in node.items():
+            if isinstance(v, dict):
+                out.append(f"{pad}{k}:")
+                out.append(emit_yaml(v, indent + 1))
+            elif isinstance(v, list):
+                items = ", ".join("null" if x is None else str(x) for x in v)
+                out.append(f"{pad}{k}: [{items}]")
+            elif v is None:
+                out.append(f"{pad}{k}: null")
+            else:
+                out.append(f"{pad}{k}: {v}")
+    return "\n".join(out)
+
+# ---------------------------------------------------------------- frontmatter
+
+FM_RE = re.compile(r"\A---\s*\n(.*?)\n---\s*\n", re.S)
+
+
+def frontmatter_field(path, field):
+    """Extract a top-level scalar field from a file's YAML frontmatter."""
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    m = FM_RE.match(text)
+    if not m:
+        return None
+    fm = m.group(1)
+    fmatch = re.search(rf"^{re.escape(field)}:\s*(.*)$", fm, re.M)
+    if not fmatch:
+        return None
+    return _scalar(fmatch.group(1).split(" #")[0])
+
+# ---------------------------------------------------------------- hashing
+
+def file_hash(path):
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def dir_hash(paths_and_names):
+    h = hashlib.sha256()
+    for name, p in sorted(paths_and_names, key=lambda t: t[0]):
+        h.update(f"{name}\n{file_hash(p)}\n".encode())
+    return h.hexdigest()
+
+
+def evidence_hash(repo):
+    items_dir = repo / "evidence" / "items"
+    entries = []
+    active = 0
+    if items_dir.is_dir():
+        for p in sorted(items_dir.glob("*.md")):
+            if frontmatter_field(p, "status") == "superseded":
+                continue
+            active += 1
+            entries.append((f"items/{p.name}", p))
+    src = repo / "evidence" / "sources.yaml"
+    if src.is_file():
+        entries.append(("sources.yaml", src))
+    return dir_hash(entries), active
+
+
+def decisions_hash(repo):
+    d = repo / "decisions"
+    entries = [(p.name, p) for p in sorted(d.glob("*.md"))] if d.is_dir() else []
+    return dir_hash(entries), len(entries)
+
+
+def output_hash(repo, rel):
+    p = repo / rel
+    if p.is_file():
+        return file_hash(p)
+    if p.is_dir():
+        entries = [(str(q.relative_to(p)).replace("\\", "/"), q)
+                   for q in sorted(p.rglob("*")) if q.is_file()]
+        if entries:
+            return dir_hash(entries)
+    return None
+
+# ---------------------------------------------------------------- citations
+
+E_CITE = re.compile(r"\[E:\s*([^\]]+)\]")
+D_CITE = re.compile(r"\[D:\s*([^\]]+)\]")
+
+
+def check_citations(repo, projection_files):
+    resolved, broken, warnings = 0, [], []
+    for rel in projection_files:
+        p = repo / rel
+        files = [p] if p.is_file() else (sorted(p.rglob("*.md")) if p.is_dir() else [])
+        for f in files:
+            text = f.read_text(encoding="utf-8", errors="replace")
+            fname = str(f.relative_to(repo)).replace("\\", "/")
+            approved = frontmatter_field(f, "status") == "approved"
+            for m in E_CITE.finditer(text):
+                for tok in (t.strip() for t in m.group(1).split(",")):
+                    if not re.fullmatch(r"ev-\d{4}", tok):
+                        broken.append(f"{fname}: malformed evidence citation '{tok}'")
+                        continue
+                    item = repo / "evidence" / "items" / f"{tok}.md"
+                    if not item.is_file():
+                        broken.append(f"{fname}: cites {tok} but evidence/items/{tok}.md does not exist")
+                    else:
+                        resolved += 1
+                        if frontmatter_field(item, "status") == "superseded":
+                            warnings.append(f"{fname}: cites {tok}, which is superseded"
+                                            f" by {frontmatter_field(item, 'superseded_by')}")
+            for m in D_CITE.finditer(text):
+                for tok in (t.strip() for t in m.group(1).split(",")):
+                    if not re.fullmatch(r"dec-\d{3}", tok):
+                        broken.append(f"{fname}: malformed decision citation '{tok}'")
+                        continue
+                    dec = repo / "decisions" / f"{tok}.md"
+                    if not dec.is_file():
+                        broken.append(f"{fname}: cites {tok} but decisions/{tok}.md does not exist")
+                        continue
+                    resolved += 1
+                    if frontmatter_field(dec, "decided_by") in (None, ""):
+                        msg = f"{fname}: cites {tok}, which has no decided_by (undecided)"
+                        if approved:
+                            broken.append(msg + " -- an approved artifact may not rest on an undecided decision")
+                        else:
+                            warnings.append(msg + " -- blocks approval, not drafting")
+    return resolved, broken, warnings
+
+# ---------------------------------------------------------------- main
+
+def find_repo(arg):
+    if arg:
+        repo = Path(arg)
+        if (repo / "manifest.yaml").is_file():
+            return repo
+        sys.exit(f"error: no manifest.yaml in {repo}")
+    for cand in (Path("."), Path("strategy")):
+        if (cand / "manifest.yaml").is_file():
+            return cand
+    sys.exit("error: no manifest.yaml found here or in ./strategy -- run the burgess "
+             "orchestrator to scaffold, or pass --repo")
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Burgess staleness checker")
+    ap.add_argument("--repo", help="path to the strategy repo (default: . or ./strategy)")
+    ap.add_argument("--record", help="comma-separated projection nodes to record after "
+                                     "regeneration, or 'all'")
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    args = ap.parse_args()
+
+    repo = find_repo(args.repo)
+    manifest_path = repo / "manifest.yaml"
+    manifest = parse_yaml(manifest_path.read_text(encoding="utf-8"))
+    nodes = manifest.get("nodes") or {}
+    if not nodes:
+        sys.exit(f"error: manifest {manifest_path} has no nodes")
+
+    ev_hash, n_items = evidence_hash(repo)
+    dec_hash, n_decs = decisions_hash(repo)
+
+    current = {}
+    for name, spec in nodes.items():
+        if (spec or {}).get("kind") == "source":
+            current[name] = ev_hash if name == "evidence" else dec_hash
+        else:
+            current[name] = output_hash(repo, spec.get("file", ""))
+
+    def input_hash(spec):
+        deps = spec.get("depends_on") or []
+        payload = "".join(f"{d}={current.get(d)}\n" for d in sorted(deps))
+        return hashlib.sha256(payload.encode()).hexdigest()
+
+    # ---- record mode
+    if args.record:
+        wanted = ([n for n, s in nodes.items() if (s or {}).get("kind") != "source"
+                   and current.get(n)] if args.record == "all"
+                  else [t.strip() for t in args.record.split(",")])
+        today = datetime.date.today().isoformat()
+        for name in wanted:
+            spec = nodes.get(name)
+            if not isinstance(spec, dict) or spec.get("kind") == "source":
+                sys.exit(f"error: '{name}' is not a projection node in the manifest")
+            if current.get(name) is None:
+                sys.exit(f"error: cannot record '{name}' -- {spec.get('file')} does not exist")
+            spec["input_hash"] = input_hash(spec)
+            spec["output_hash"] = current[name]
+            spec["generated"] = today
+        with manifest_path.open("w", encoding="utf-8", newline="\n") as fh:
+            fh.write(emit_yaml(manifest) + "\n")
+        print(f"recorded: {', '.join(wanted)}")
+        return 0
+
+    # ---- report mode
+    # Staleness propagates transitively: a projection whose dependency is stale
+    # is itself stale, even if that dependency's file hasn't been regenerated yet.
+    direct_stale, stale_cache = {}, {}
+    for name, spec in nodes.items():
+        spec = spec or {}
+        if spec.get("kind") != "source" and spec.get("input_hash") not in (None, "") \
+                and current.get(name) is not None:
+            direct_stale[name] = input_hash(spec) != spec.get("input_hash")
+
+    def is_stale(name, trail=()):
+        if name in trail:
+            sys.exit(f"error: dependency cycle in manifest at '{name}'")
+        if name in stale_cache:
+            return stale_cache[name]
+        spec = nodes.get(name) or {}
+        result = False
+        if name in direct_stale:
+            result = direct_stale[name] or any(
+                is_stale(d, trail + (name,)) for d in (spec.get("depends_on") or [])
+                if (nodes.get(d) or {}).get("kind") != "source")
+        stale_cache[name] = result
+        return result
+
+    report, problems = [], []
+    for name, spec in nodes.items():
+        spec = spec or {}
+        if spec.get("kind") == "source":
+            count = f"{n_items} active items + sources.yaml" if name == "evidence" \
+                    else f"{n_decs} records"
+            report.append({"node": name, "state": "source", "detail": count,
+                           "hash": current[name][:12]})
+            continue
+        rel = spec.get("file", "")
+        cur = current.get(name)
+        status = None
+        p = repo / rel
+        if p.is_file():
+            status = frontmatter_field(p, "status")
+        if spec.get("input_hash") in (None, "") and cur is None:
+            report.append({"node": name, "state": "not generated", "detail": rel})
+            continue
+        if spec.get("input_hash") in (None, "") and cur is not None:
+            report.append({"node": name, "state": "UNRECORDED",
+                           "detail": f"{rel} exists but was never recorded -- "
+                                     f"run --record {name}"})
+            problems.append(f"{name}: unrecorded")
+            continue
+        if cur is None:
+            report.append({"node": name, "state": "MISSING",
+                           "detail": f"recorded in manifest but {rel} is absent"})
+            problems.append(f"{name}: missing output")
+            continue
+        edited = cur != spec.get("output_hash")
+        state = "FRESH"
+        detail = f"status: {status or '?'}; generated {spec.get('generated')}"
+        if edited:
+            state = "HAND-EDITED"
+            detail = (f"{rel} changed since generation -- projections are regenerated, "
+                      f"not edited; move the edit into evidence/decisions")
+            problems.append(f"{name}: hand-edited")
+        if is_stale(name):
+            deps = spec.get("depends_on") or []
+            via = [d for d in deps if stale_cache.get(d)]
+            state = "STALE" if not edited else "STALE+HAND-EDITED"
+            detail = (f"stale via {', '.join(via)} (transitive)" if not direct_stale[name]
+                      else f"dependency changed since generation "
+                           f"(depends_on: {', '.join(deps)})")
+            problems.append(f"{name}: stale")
+        report.append({"node": name, "state": state, "detail": detail})
+
+    proj_files = [s.get("file") for n, s in nodes.items()
+                  if (s or {}).get("kind") != "source" and current.get(n)]
+    resolved, broken, warnings = check_citations(repo, proj_files)
+    broken = list(dict.fromkeys(broken))
+    warnings = list(dict.fromkeys(warnings))
+    problems.extend(broken)
+
+    if args.json:
+        print(json.dumps({"repo": str(repo), "nodes": report,
+                          "citations": {"resolved": resolved, "broken": broken,
+                                        "warnings": warnings},
+                          "clean": not problems}, indent=2))
+    else:
+        print(f"burgess staleness report -- {repo}")
+        width = max(len(r["node"]) for r in report)
+        for r in report:
+            extra = f"  [{r['hash']}]" if r.get("hash") else ""
+            print(f"  {r['node']:<{width}}  {r['state']:<16} {r['detail']}{extra}")
+        print(f"citations: {resolved} resolved, {len(broken)} broken, "
+              f"{len(warnings)} warning(s)")
+        for b in broken:
+            print(f"  BROKEN: {b}")
+        for w in warnings:
+            print(f"  warn:   {w}")
+        print("clean" if not problems else f"NEEDS ATTENTION: {'; '.join(problems)}")
+    return 1 if problems else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/derive-messaging/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: derive-messaging
+description: Turn Burgess positioning into a message house (master value prop, key messages, proof points), per-ICP benefit bullets sourced from real customer language, investor and customer pitches, and objection responses. Use this skill whenever the user asks for messaging, value propositions, a pitch, benefit statements, sales talking points, or objection handling — after positioning exists, or standalone with a warning that messaging built without settled positioning gets rewritten.
+---
+
+# Derive Messaging
+
+Messaging is positioning made usable. The message house exists so every future asset — web page, deck, sales call — draws from the same small set of claims backed by the same proof, instead of each asset inventing its own. Messaging is downstream of positioning, never the reverse: if the positioning feels wrong while writing, stop and flag it; don't paper over it with copy. Formats in the burgess skill's `references/schemas.md`.
+
+## Inputs
+
+Read `projections/positioning.md` and the decision records it cites; run `python scripts/check_stale.py` first and surface staleness. Pull every `customer_language` evidence item — verbatim customer words are the scarcest and most valuable input to this skill. **Standalone without positioning:** gather the minimum interactively (target customer, top 2–3 differentiators with proof, main alternative), record via `intake-interview`'s steps, warn that this messaging is provisional, and put "run derive-positioning" in `open_questions`.
+
+## Procedure
+
+1. **Message house.**
+   - **Roof — master value proposition.** One sentence combining the ICP, the category frame `[D:]`, and the strongest value theme. Customer language, not architecture language.
+   - **Walls — key messages (3–5).** One per differentiation pillar. Each a claim a salesperson could say out loud without flinching — and without violating the pre-launch rule.
+   - **Foundation — proof points.** Under each key message, the concrete evidence that makes it credible, each with `[E:]` citations. A key message without a proof point is a wall without a foundation — cut it or flag it.
+2. **Benefit bullets per ICP (3–5 each).** Written in the customer's own words **where `customer_language` items exist — quote them**. Where they don't, engineer bullets from internal language and flag each one `engineered — validate with customers`. The flag is the honesty mechanism: nobody downstream may mistake engineered copy for validated copy. If every bullet is engineered, say so at the top and point at the gap report.
+3. **Two pitch variants.**
+   - **Investor pitch:** problem size, why now, the vision (from `projections/vision.md` if it exists — otherwise mark the slot open), why this team/approach wins. Market-size claims need `[E:]` or an explicit gap.
+   - **Customer pitch:** their pain, the value, the proof, the ask. No vision-speak — customers buy outcomes, not destinations.
+4. **Objections & responses.** From risk themes, known `limitation` items, and the alternatives map ("why not just use X?"). Evidence-based responses with honest caveats — a credible limitation acknowledged beats a limitation denied. Include the objections the red team's personas raised; they were free market research.
+
+## Output
+
+Write `projections/messaging.md`: frontmatter per schema (`artifact: messaging`, `depends_on: [positioning]`), sections: **Message House** (Roof / Walls / Foundation), **Benefit Bullets per ICP** (each bullet marked `customer language [E: ev-NNNN]` or `engineered — validate`), **Investor Pitch**, **Customer Pitch**, **Objections & Responses** (table: objection, response, honest caveat).
+
+Then: `python scripts/check_stale.py --record messaging`, commit `regen: messaging`, run `red-team` against it.
+
+## Guardrails
+
+- Every claim traces to a proof point; every proof point to evidence. The master value prop must be recognizably the positioning's category + value — a new idea appearing here is positioning drift, not creativity.
+- Nothing may contradict known `limitation` items or claim capabilities positioning didn't.
+- Pre-launch rule applies in full: prospective phrasing, committed-scope labeling, no past-tense results claims — the red team's tense scan treats violations as automatic HIGH.
+- Secondhand evidence never solely supports a headline claim or key message.
+
+## Checkpoint
+
+Present the message house first — if the roof and walls are right, the rest is detail. List every `engineered` bullet for validation with real customers (and offer to add the validation questions to the gap report). In a waived run, record and continue.