burgess 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Burgess contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# Burgess
+
+**An evidence-first strategy engine, delivered as agent skills.**
+
+The Cambrian explosion produced a thousand wild body plans — and we only know any of it happened because one evidence bed preserved everything: the **Burgess Shale**. Every claim paleontology makes about that era traces back to specimens in that shale, dated and in place.
+
+Your strategy deck is a reconstruction. Burgess is the fossil bed it's reconstructed from.
+
+Burgess turns your company's documents and interviews into a living, provenance-linked **evidence base** — and projects vision, positioning, messaging, and brand from it as cheap, regenerable artifacts. When new evidence lands (a win/loss report, five sales-call transcripts, a churned customer's exit interview), staleness propagates mechanically through a dependency graph and the affected artifacts regenerate — with humans approving the decisions, never the mechanics.
+
+Strategy documents rot because the evidence behind each claim was never captured — only the conclusions were. Burgess inverts the asset:
+
+- **The evidence base is the product.** Every user pain, capability, limitation, customer quote, win/loss reason, and competitive fact — atomized, source-linked, confidence-tagged, dated.
+- **Artifacts are projections.** Positioning, messaging, web copy: regenerable renderings of the evidence through established frameworks (Dunford positioning, Collins & Porras vision, message house).
+- **Everything is plain markdown + YAML in git.** Diffable positioning is the killer feature: *"here is the diff to our differentiation claims since March, and the evidence that changed."*
+- **Humans decide; the system drafts and argues.** Every judgment call becomes a decision record with rejected alternatives; a red team attacks every regeneration.
+
+## Install
+
+**Via npm:**
+
+```bash
+npm install -g burgess
+burgess install              # -> ~/.claude/skills (Claude Code, all projects)
+
+# or without installing anything globally:
+npx burgess install
+```
+
+Options: `--project` (this repo's `.claude/skills/` only), `--codex` (`~/.agents/skills/`), `--dest DIR`, `--force`.
+
+**Manually:** copy the folders in `skills/` into `~/.claude/skills/` (Claude Code) or `~/.agents/skills/` (Codex). Both use the same open SKILL.md standard.
+
+> Upgrading from the `vision-workflow` bundle or the `groundwork` working-name build? Remove those folders — Burgess supersedes them and competing bundles will answer the same requests.
+
+## Get started
+
+Open Claude Code in your product repo (or a fresh repo for strategy) and say:
+
+> **"set up burgess"**
+
+The orchestrator scaffolds a `strategy/` directory and guides you from there:
+
+- **Have documents?** *"Ingest these docs"* — PRDs, architecture docs, decks, transcripts, win/loss notes.
+- **Nothing written down?** *"Interview me"* — for early-stage teams the founder interview **is** ingestion, and it's the highest-density evidence source you have.
+- **Coming back later?** *"Where were we?"* — the orchestrator reads the manifest and tells you what exists, what's stale, and what needs a human decision.
+
+The first thing Burgess produces is not strategy — it's the **gap report**: an honest account of what your evidence *cannot* support yet, with the highest-value questions to answer next (win/loss notes and ~5 sales-call transcripts buy more positioning truth than almost anything else).
+
+## The pipeline
+
+| Skill | What it does |
+|---|---|
+| `burgess` | Orchestrator: scaffolds the repo, detects state, runs steps in order, enforces checkpoints and staleness |
+| `ingest-evidence` | Atomizes documents into typed, cited evidence items; regenerates the gap report |
+| `intake-interview` | Gap-driven founder/leadership interview; answers become evidence items |
+| `derive-themes` | Problem/strength/risk themes; competitive-alternatives map; differentiator vs table-stakes test |
+| `derive-positioning` | Dunford five-component positioning; category and beachhead as proposed decision records |
+| `derive-messaging` | Message house, per-ICP benefits from real customer language, pitches, objection handling |
+| `generate-vision` | Purpose + values discovered from behavior; envisioned future with pillars and milestones |
+| `build-brand-platform` | Voice with do/don't pairs; value pillars with proof; the prohibited-claims list |
+| `generate-assets` | Web copy, deck outline, internal explainer — message-house claims only |
+| `red-team` | Adversarial pass after every regeneration: citation chains, tense scan, skeptic personas |
+
+Start with the wedge (ingest → interview → themes → positioning → red team). Messaging, vision, brand, and assets come when you're ready — positioning churns weekly; brand churns yearly.
+
+## What your strategy repo looks like
+
+```
+strategy/
+├── evidence/           # THE FOSSIL BED
+│   ├── sources.yaml    #   registry of every source (incl. referenced-but-unavailable)
+│   ├── items/          #   one file per claim: ev-0001.md ... typed, cited, confidence-tagged
+│   └── intake/         #   interview transcripts (append-only)
+├── decisions/          # human judgments with rationale + rejected alternatives (dec-001.md ...)
+├── projections/        # REGENERABLE — never hand-edited
+├── reviews/            # red-team output, one per run (append-only)
+├── scripts/check_stale.py   # staleness + citation checker (stdlib Python, CI-ready)
+├── gap-report.md       # always current: what the evidence can't support yet
+└── manifest.yaml       # the dependency DAG: hashes, staleness, generation records
+```
+
+## The git workflow
+
+- **Branch per strategy change.** New evidence batch or decision → branch → regenerate affected projections → PR. The PR diff *is* the strategy review.
+- **Never hand-edit projections.** Fix the evidence or the decision, regenerate. `check_stale.py` detects hand-edits.
+- **Approval = merge + status flip.** A human flips `status: approved` in frontmatter and fills `decided_by` on decisions. Agents never do.
+- **Commit prefixes** keep the log readable as a changelog: `evidence:`, `decision:`, `regen:`, `review:`.
+- **CI:** run `python strategy/scripts/check_stale.py` — non-zero exit if anything is stale, hand-edited, or has broken citations.
+
+## Citation grammar
+
+Projections cite evidence items and decisions; items cite sources. Two hops, each simple.
+
+- `[E: ev-0042]` — evidence item (carries source, location, confidence, date)
+- `[D: dec-003]` — human decision record
+- `[I]` — inference by the drafting agent (says from what)
+- `[A]` — assumption awaiting confirmation (must appear in `open_questions`)
+
+A factual sentence in a projection with none of these tags is a defect the red team flags. Secondhand evidence never solely supports a differentiator or headline claim.
+
+## A worked example
+
+`examples/seelray/` contains a complete Burgess run against a real ~600-line PRD — evidence base, gap report, themes, positioning with proposed decision records, a staleness cascade triggered by a win/loss batch, red-team reviews (including one catching planted defects), and a delete-and-regenerate acceptance test. Its git log reads as a strategy changelog.
+
+## License
+
+MIT

package/bin/burgess.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * Burgess installer — copies the Burgess agent skills into your
+ * Claude Code or Codex skills directory. No dependencies, no telemetry.
+ *
+ *   npx burgess install             # ~/.claude/skills (Claude Code, personal)
+ *   npx burgess install --project   # ./.claude/skills (this repo only)
+ *   npx burgess install --codex     # ~/.agents/skills (Codex)
+ *   npx burgess install --dest DIR  # anywhere else
+ */
+
+"use strict";
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+const SKILLS_SRC = path.join(__dirname, "..", "skills");
+const args = process.argv.slice(2);
+const cmd = args.find((a) => !a.startsWith("-")) || "help";
+const has = (flag) => args.includes(flag);
+const val = (flag) => {
+  const i = args.indexOf(flag);
+  return i !== -1 && args[i + 1] ? args[i + 1] : null;
+};
+
+function targetDir() {
+  if (val("--dest")) return path.resolve(val("--dest"));
+  const codex = has("--codex");
+  if (has("--project")) return path.resolve(codex ? ".agents/skills" : ".claude/skills");
+  return path.join(os.homedir(), codex ? ".agents/skills" : ".claude/skills");
+}
+
+function skillNames() {
+  return fs
+    .readdirSync(SKILLS_SRC, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+}
+
+function install() {
+  const dest = targetDir();
+  fs.mkdirSync(dest, { recursive: true });
+  const names = skillNames();
+  const skipped = [];
+  const installed = [];
+  for (const name of names) {
+    const to = path.join(dest, name);
+    if (fs.existsSync(to) && !has("--force")) {
+      skipped.push(name);
+      continue;
+    }
+    fs.rmSync(to, { recursive: true, force: true });
+    fs.cpSync(path.join(SKILLS_SRC, name), to, { recursive: true });
+    installed.push(name);
+  }
+  console.log(`\nBurgess skills -> ${dest}\n`);
+  if (installed.length) console.log(`  installed: ${installed.join(", ")}`);
+  if (skipped.length)
+    console.log(
+      `  skipped (already exist): ${skipped.join(", ")}\n` +
+        `  re-run with --force to overwrite them`
+    );
+
+  // Older bundles overlap in scope; flag them if present. "groundwork" was
+  // Burgess's working name before publication.
+  const legacy = ["vision-workflow", "ingest-context", "derive-strategic-themes",
+    "generate-messaging", "generate-brand-assets", "groundwork"].filter((n) =>
+    fs.existsSync(path.join(dest, n))
+  );
+  if (legacy.length)
+    console.log(
+      `\n  note: found older bundle folders (${legacy.join(", ")}).\n` +
+        `  Burgess supersedes them — consider removing those folders so\n` +
+        `  two workflows don't compete to answer the same requests.`
+    );
+
+  console.log(`
+Get started
+-----------
+1. Open ${has("--codex") ? "Codex" : "Claude Code"} in your product repo (or an empty repo for strategy).
+2. Say: "set up burgess" — the orchestrator scaffolds a strategy/ directory
+   and guides you from there.
+3. Have documents? Say "ingest these docs". Have nothing written down?
+   Say "interview me" — the intake interview IS ingestion for early-stage teams.
+
+The first thing you get is a gap report: an honest account of what your
+evidence can't yet support, and the highest-value questions to answer next.
+`);
+}
+
+function uninstall() {
+  const dest = targetDir();
+  const removed = [];
+  for (const name of skillNames()) {
+    const to = path.join(dest, name);
+    if (fs.existsSync(to)) {
+      fs.rmSync(to, { recursive: true, force: true });
+      removed.push(name);
+    }
+  }
+  console.log(removed.length ? `removed from ${dest}: ${removed.join(", ")}` : `nothing to remove in ${dest}`);
+}
+
+function list() {
+  console.log("Burgess skills in this package:\n");
+  for (const name of skillNames()) {
+    const skillMd = path.join(SKILLS_SRC, name, "SKILL.md");
+    let desc = "";
+    try {
+      const m = fs.readFileSync(skillMd, "utf8").match(/^description:\s*(.+)$/m);
+      if (m) desc = m[1].split(". ")[0] + ".";
+    } catch {}
+    console.log(`  ${name.padEnd(22)} ${desc}`);
+  }
+}
+
+function help() {
+  console.log(`
+burgess — evidence-first strategy skills for Claude Code / Codex
+
+Usage:
+  burgess install [--project] [--codex] [--dest DIR] [--force]
+  burgess uninstall [--project] [--codex] [--dest DIR]
+  burgess list
+
+Targets:
+  (default)   ~/.claude/skills        Claude Code, all your projects
+  --project   ./.claude/skills        Claude Code, this repo only
+  --codex     ~/.agents/skills        Codex (combine with --project for ./.agents/skills)
+  --dest DIR  anywhere
+
+Then open your agent and say "set up burgess".
+`);
+}
+
+({ install, uninstall, list, help }[cmd] || help)();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "burgess",
+  "version": "0.1.0",
+  "description": "Burgess: an evidence-first strategy engine as agent skills. Turn documents and interviews into a provenance-linked evidence base; project positioning, messaging, vision, and brand from it as regenerable, diffable artifacts.",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "agent-skills",
+    "positioning",
+    "strategy",
+    "messaging",
+    "brand",
+    "product-marketing"
+  ],
+  "bin": {
+    "burgess": "bin/burgess.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"if(!process.env.npm_config_global)console.log('Run: npx burgess install   (or burgess help)')\""
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/skills/build-brand-platform/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: build-brand-platform
+description: Assemble a brand platform from Burgess's vision, positioning, and messaging — purpose and values inherited verbatim, personality and voice with do/don't examples, value pillars with proof, usage guidelines, and the prohibited-claims list that enforces every upstream guardrail downstream. Use this skill whenever the user asks for a brand platform, brand guidelines, brand voice, tone of voice, brand personality, or "how should we sound" — after vision and positioning exist, or standalone with a warning that style without strategy doesn't hold.
+---
+
+# Build Brand Platform
+
+The brand platform wraps the strategy into an identity system anyone — marketer, founder, agency, or AI — can apply consistently. Its authority comes from **inheritance**: purpose and values from vision, pillars from positioning, proof from evidence. The platform adds *expression* (personality, voice, governance), never new strategy. Its sharpest tooth is the prohibited-claims list — the mechanism by which every evidence guardrail upstream reaches every future writer and tool. Formats in the burgess skill's `references/schemas.md`.
+
+## Inputs
+
+Read `projections/vision.md`, `projections/positioning.md`, `projections/messaging.md`, and the decisions they cite; run `python scripts/check_stale.py` first. **Standalone without upstream artifacts:** gather the minimum interactively (what the company exists to do, top differentiators with proof, 2–3 adjectives for how it wants to sound), record via `intake-interview`'s steps, and warn plainly: a platform without underlying positioning is style without strategy.
+
+## Procedure
+
+1. **Inherit purpose and values.** Copy `core_purpose` and `core_values` from `projections/vision.md` **verbatim in meaning**. If customer-facing phrasing must differ from internal wording, show both and note the translation — meaning must not drift. Never re-derive purpose here; two competing purposes is how brands become incoherent. If vision.md doesn't exist, this section is blocked, not improvised — offer to run `generate-vision`.
+2. **Personality and voice (3–5 traits).** Traits that express the values and fit the ICPs (a developer-tools brand and a healthcare brand earn trust with different registers). Per trait: one **Do** (an example sentence in-voice) and one **Don't** (the near-miss anti-pattern — the exaggerated or off-key version). The don'ts are what make voice guidelines usable; without them every trait reads as "confident but friendly" mush.
+3. **Value pillars — reasons to believe (3–5).** Take the differentiation pillars from positioning and attach concrete proof points `[E:]`. Every pillar answers "says who?" with something checkable.
+4. **Usage guidelines.** How the voice flexes by context: website (persuasive), docs (plain, precise), sales (direct), employer brand (candid). Same personality, different register.
+5. **Prohibited claims.** Compile the specific list downstream writers and AI tools must never use:
+   - claims the evidence base cannot support (name them — "fastest", "only platform that…"),
+   - claims contradicting known `limitation` items (enumerate each limitation marketing could be tempted to contradict),
+   - superlatives without proof ("best", "leading", "guaranteed"),
+   - compliance-sensitive phrasing (certifications not held, regulated-industry promises),
+   - **past-tense results language for anything not shipped and measured** ("we've demonstrated", "proven with customers") — for pre-launch products this is the list's most load-bearing entry,
+   - custody/scope precision rules where the evidence draws a boundary (e.g., a claim true of one tier but not the default).
+   Be specific, not generic — a prohibited-claims list that could apply to any company enforces nothing.
+
+## Output
+
+Write `projections/brand-platform.md`: frontmatter per schema (`artifact: brand-platform`, `depends_on: [vision, positioning, messaging]`), sections: **Purpose** (inherited; translation noted), **Values** (inherited), **Personality & Voice** (per trait: Do / Don't), **Value Pillars** (table: pillar, proof points `[E:]`), **Usage Guidelines**, **Prohibited Claims**.
+
+Then: `python scripts/check_stale.py --record brand-platform`, commit `regen: brand-platform`, run `red-team` — which from now on scans everything against the prohibited-claims list.
+
+## Guardrails
+
+- Purpose and values inherited verbatim in meaning; only surface phrasing may adapt, with the translation shown.
+- Every value pillar carries at least one cited proof point.
+- The prohibited-claims list must cover every known limitation from the evidence base that marketing could contradict — walk the `limitation` items one by one and check.
+
+## Checkpoint
+
+Present the personality traits with their Do/Don't pairs and the full prohibited-claims list — the two sections humans most need to own. Ask whether legal/compliance should review the prohibited list before assets are generated; record the answer as a decision.

package/skills/burgess/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: burgess
+description: Orchestrates Burgess, the evidence-first strategy engine — turns a company's documents and interviews into a provenance-linked evidence base and projects positioning, messaging, vision, and brand from it. Use this skill whenever the user wants to set up or run Burgess, asks "where were we" on strategy work, wants a status check on their strategy repo, mentions turning docs/PRDs/interviews into positioning or vision, asks what's stale or needs regenerating, or wants to start the guided strategy process. Also trigger on first contact with a repo containing a strategy/ directory with a manifest.yaml.
+---
+
+# Burgess Orchestrator
+
+Burgess inverts the usual strategy asset: the durable product is the **evidence base** — atomized, provenance-linked, confidence-tagged claims — and every strategy artifact (themes, positioning, messaging, vision, brand) is a cheap, regenerable **projection** of it. Your job as orchestrator: know the state, run the right skill next, enforce the checkpoints, keep the staleness math honest, and make the whole thing feel guided rather than bureaucratic.
+
+Read `references/schemas.md` (formats), `references/conventions.md` (working rules), and `references/frameworks.md` (grounding) before running anything you haven't run this session. Those three files are shared by every Burgess skill.
+
+## The pipeline
+
+| Step | Skill | Reads | Writes |
+|---|---|---|---|
+| Ingest | `ingest-evidence` | source docs | `evidence/`, `gap-report.md` |
+| Interview | `intake-interview` | `gap-report.md` | `evidence/intake/`, new items, `gap-report.md` |
+| Themes | `derive-themes` | evidence | `projections/themes.md` |
+| Positioning | `derive-positioning` | themes, decisions | `projections/positioning.md`, proposed decisions |
+| Messaging (P2) | `derive-messaging` | positioning | `projections/messaging.md` |
+| Vision (P3) | `generate-vision` | themes, decisions | `projections/vision.md` |
+| Brand (P3) | `build-brand-platform` | vision, positioning, messaging | `projections/brand-platform.md` |
+| Assets (P3) | `generate-assets` | messaging, brand | `projections/assets/` |
+| Red team | `red-team` | any projections | `reviews/review-<date>.md` |
+
+If a step's skill is not installed, follow this skill's `references/` directly — the references are canonical; the skills are packaging.
+
+## First run: scaffold and guide
+
+If no `strategy/` directory with a `manifest.yaml` exists:
+
+1. **Ask where it lives** — its own repo or a `strategy/` directory in the current repo (default: `strategy/` here).
+2. **Scaffold**: create the layout from `references/schemas.md` (§Repo layout); write `manifest.yaml` verbatim from the schema template; write an empty `sources.yaml` (`sources: []`); copy `scripts/check_stale.py` from this skill's `scripts/` into `strategy/scripts/`; write a `.gitattributes` containing `* text=auto eol=lf` (staleness hashes are computed over file bytes — line-ending rewrites across machines would fake staleness).
+3. **Git**: if not already in a git repo, recommend `git init` — diffable strategy is the point. First commit: `evidence: scaffold burgess strategy repo`.
+4. **Route by what they have.** Ask one question: "Do you have documents (PRD, architecture docs, decks, transcripts) — or should we start by talking?" Documents → `ingest-evidence`. Nothing yet → `intake-interview` standalone (for early-stage companies the founder interview IS ingestion). Never make a documents-less user feel they're missing a prerequisite.
+
+Tell the user what got created and what happens next in one short paragraph, not a lecture.
+
+## Every run: detect state first
+
+1. Run `python scripts/check_stale.py` in the strategy repo before doing anything.
+2. Report a status table: each node — exists? status (draft/approved)? stale? — plus open `proposed_decisions` awaiting `decided_by`, open `open_questions`, and the top unanswered gap-report questions.
+3. Confirm scope: continue where things left off, run a specific step, ingest new material, or red-team. When the user asks "where were we", this table *is* the answer — lead with the single most useful next action.
+
+## Running steps
+
+- Run skills in dependency order; never generate downstream of a stale input without telling the user (proceeding on stale/draft inputs is allowed, recorded in `open_questions`).
+- After any skill writes a projection: run `python scripts/check_stale.py --record <node>`, then run `red-team` against the changed artifacts (every regeneration, not just finales), then commit with the right prefix (`regen:`, `review:`).
+- Regenerating an `approved` artifact: set its frontmatter back to `draft` and tell the user why (new evidence means the human re-approves the projection of it).
+- New evidence mid-stream (user drops in win/loss notes, transcripts): route to `ingest-evidence`, then report the staleness cascade and offer regeneration in dependency order.
+
+## Checkpoints
+
+After each artifact: present a summary, its `open_questions`, and its `proposed_decisions`; ask the human to approve, correct, or answer. Corrections are evidence — route them through `intake-interview` capture (they become items), never silent edits.
+
+**Waived runs** ("just run it all"): checkpoints are recorded, not held. Questions land in `open_questions`, proposed decisions stay undecided, everything stays `draft`, and the run ends with a single consolidated sign-off list: every decision awaiting `decided_by`, every `[A]`, every gap accepted. Do not soften this list — the waiver deferred the decisions; it didn't make them.
+
+**Approval**: only humans flip `status: approved` or fill `decided_by`. When the user says "approved", tell them exactly which frontmatter line to change (or make the edit at their explicit direction, quoting their approval in the commit message: `decision: dec-003 decided by <name>`).
+
+## Hand-edit warnings
+
+When `check_stale.py` reports HAND-EDITED: someone changed a projection directly. Don't regenerate over it — the edit is information trapped in the wrong layer. Show the diff vs. what was recorded, ask what evidence or decision the edit reflects, capture that in `evidence/` or `decisions/`, then regenerate.
+
+## Phasing
+
+Phase 1 (evidence, gap report, intake, themes, positioning, red team) is the wedge — it churns weekly and delivers value with zero projections generated. Offer Phase 2 (messaging) once positioning is approved; Phase 3 (vision, brand, assets) when the user asks or when messaging is settled. Don't push the full pipeline on a user who came for positioning.

package/skills/burgess/references/conventions.md

@@ -0,0 +1,64 @@
+# Burgess Conventions
+
+Working rules every skill follows. These encode failure modes observed in live testing — each rule exists because its absence produced a specific defect.
+
+## The prime directive
+
+**The evidence base is the product; artifacts are projections.** Any strategy artifact must be regenerable from `evidence/` + `decisions/` alone. If regenerating an artifact would lose information, that information belonged in an evidence item or a decision record — put it there first, then regenerate.
+
+## Never hand-edit projections
+
+A wrong claim in `positioning.md` is fixed by correcting or adding evidence items or decision records, then regenerating. Hand-edits trap information outside the evidence base and die on the next regeneration. `check_stale.py` detects hand-edits (current hash ≠ recorded `output_hash`); when it flags one, help the user move the edit's substance into evidence/decisions before regenerating over it.
+
+## Humans decide; agents draft and argue
+
+- Agents never write `status: approved` in any frontmatter. Ever.
+- Agents never fill `decided_by` on a decision record. They propose with `decided_by: null` and mandatory `rejected` alternatives.
+- Every judgment call (market category, beachhead, horizon, values, "may pre-launch claims ship?") becomes a PROPOSED decision record — not prose in an artifact.
+- An unfilled decision blocks `approved` on artifacts citing it, but never blocks `draft` generation.
+- Regeneration honors existing decision records, decided or proposed: cite them, don't re-propose duplicates. A new record on an already-covered question exists only to argue for changing the old one, and names it. Same evidence + same decisions → same conclusions is the regenerability contract.
+
+## Checkpoint discipline and waived runs
+
+After generating any artifact: present it with its `open_questions` and `proposed_decisions`, and hold for human review. When the user says "just run it all" (a **waived run**), checkpoints are *recorded, not held*: every checkpoint question lands in `open_questions`, everything stays `draft`, and the run ends with one consolidated sign-off list. Never simulate approval; never soften the sign-off list because the user waived checkpoints — the waiver defers decisions, it doesn't make them.
+
+## Pre-launch rule
+
+"Current capability" means **shipped and demonstrated**. For pre-launch products, committed spec scope may ground positioning, but every such claim must be:
+1. phrased prospectively (never "we've demonstrated", "proven with customers"),
+2. labeled as committed scope, and
+3. gated on a recorded human decision: "may this ship before launch evidence exists?" — propose the decision record; don't decide it.
+
+Past-tense results claims for unshipped capability are automatic HIGH red-team findings. This exact defect occurred in live testing; the tense scan is not optional.
+
+## Conflicts and supersession
+
+Two sources disagree → mark **both** items `disputed`, surface for human resolution, cite both until resolved. Never silently pick one. A newer version of the same source → mark old items `superseded`, link `superseded_by`; superseded items stay on disk (provenance) but leave the evidence hash.
+
+## Staleness
+
+Run `python scripts/check_stale.py` (in the strategy repo) **before and after** any operation. Before: report what's stale so the user isn't building on sand. After: `--record` the nodes you regenerated, and commit `manifest.yaml` in the same commit as the projection it records — they change together or the tree drifts. Draft artifacts citing undecided decisions produce checker *warnings* by design — they block approval, not drafting, and the run still reports clean; don't chase them. Offer regeneration in dependency order: evidence → themes → positioning → messaging → vision → brand-platform → assets. Regenerating an `approved` artifact demotes it to `draft`.
+
+## Red team on every regeneration
+
+Drift compounds silently in long generation chains. After any projection regenerates, run the `red-team` skill against the changed artifact set — as part of the pipeline, not as a finale. On-demand runs against any artifact subset are also fine.
+
+## Git workflow
+
+- **Branch per strategy change.** New evidence batch or decision → branch → regenerate affected projections → PR. The PR diff *is* the strategy review: reviewers see exactly which claims changed and which evidence moved them.
+- **Approval = merge + status flip.** A human flips `status: approved` in artifact frontmatter (and fills `decided_by`) in the PR. Agents never do.
+- **Commit prefixes** so the strategy log reads like a changelog:
+  - `evidence:` — new/changed evidence items, sources, intake transcripts
+  - `decision:` — decision records proposed or decided
+  - `regen:` — projections regenerated (say from what: `regen: positioning after ev-0107..0112`)
+  - `review:` — red-team output
+- `reviews/` and `evidence/intake/` are append-only; `gap-report.md` and projections are current-state (git history is their archive).
+- If the strategy repo isn't under git yet, recommend `git init` at scaffold time — diffable positioning is the killer feature, and it needs git.
+
+## Language discipline
+
+Neutral, factual language in evidence items, gap reports, and themes. Persuasive language only downstream of positioning. Marketing spin in an evidence item is a defect: it launders opinion into the layer everything else trusts.
+
+## Standalone invocation
+
+Every skill runs solo. When upstream inputs are missing, gather the minimum interactively, then **record what you gathered as intake evidence** (transcript + atomized items), never as untracked context. Standalone runs still update the manifest and gap report — there is no off-the-books mode.

package/skills/burgess/references/frameworks.md

@@ -0,0 +1,39 @@
+# Framework Grounding
+
+Established strategy frameworks each skill rests on. These are settled for Burgess — do not re-litigate them mid-run. Each note says what the framework is and why the skill uses it that way, so a skill can explain its rules when a user pushes back.
+
+## Themes: affinity mapping (KJ method)
+
+Clustering many observations into 3–7 named themes is affinity mapping / thematic analysis — long-established synthesis practice; 3–7 clusters matches working-memory guidance. Themes are named by the **customer's problem**, not the product's feature ("teams can't trust hand-offs", not "workflow automation"), because problem-named themes survive product pivots and feature-named ones don't.
+
+## Competitive analysis: Dunford's competitive alternatives
+
+The competitive unit of analysis is **what customers would actually do instead** — which includes the status quo, spreadsheets, manual process, building in-house, hiring someone, and doing nothing — not just named competitor products (April Dunford, *Obviously Awesome*). The status quo is usually the biggest competitor; a map with only named products is incomplete. Consequence, applied mechanically: a strength shared by the main alternatives is **TABLE STAKES**, never a differentiator, however central it is to the product. The alternatives map is built *before* strength classification so the test has something to test against. This defeats flattery bias — the failure mode where everything becomes a differentiator.
+
+## Positioning: Dunford's five components, in order
+
+Derive: competitive alternatives → unique attributes → value → best-fit customers → market category. The order matters because each answer constrains the next; positioning is a set of interdependent choices, not blanks in a template. Dunford is explicitly critical of *starting* from the Moore fill-in-the-blanks statement ("For [ICP] who [need]…") — it assumes each blank has one obvious answer. The Moore statement is only ever an optional **summary output**, written last. Market-category options: head-on (existing category), subsegment/niche (usually the right answer), new category (rare, expensive to educate — strong justification required). Record rejected categories with reasons; the rejections make the choice reviewable.
+
+## Beachhead: Moore's bowling pin (optional, early-stage)
+
+For early-stage products: a beachhead niche with outsized value plus a bowling-pin expansion path to adjacent segments (Geoffrey Moore, *Crossing the Chasm*). Optional; a recommendation, not a product constraint — always a proposed decision record.
+
+## Vision: Collins & Porras core ideology + envisioned future
+
+Vision = **core ideology** (core purpose — why the org exists beyond making money — plus 3–5 core values) + **envisioned future** (vivid destination at a horizon, strategic pillars, milestones) (Collins & Porras, "Building Your Company's Vision", HBR 1996). Purpose and values are *discovered from behavior*, not invented — a value with no behavioral evidence (from `culture` evidence items) is marked ASPIRATIONAL for human confirmation. Purpose/values are stable; the envisioned future is a bet with a date. Positioning describes the market **today** and must be winnable now — merely *consistent with* the vision, never derived from it. Optional stress test: a future press release (Amazon PR/FAQ practice) — if it's boring, the vision is too.
+
+## Messaging: the message house
+
+One roof (master value proposition), 3–5 walls (key messages, one per differentiation pillar), proof-point foundation — so every downstream asset 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. Benefit bullets come from `customer_language` evidence items; where none exist they are engineered from internal language and flagged `engineered — validate with customers` so nobody mistakes them for validated copy.
+
+## Brand: inheritance + prohibited claims
+
+Brand platform structure (purpose, values, personality, voice as trait + do + don't, value pillars with proof, governance) follows mainstream brand-identity practice (Aaker's identity system; Keller's insistence that every claimed benefit carries proof). Purpose and values are **inherited verbatim in meaning** from vision — one source of truth; two competing purposes is how brands become incoherent. The **prohibited-claims list** is the downstream enforcement mechanism: claims the evidence can't support, claims contradicting known limitations, unproven superlatives, compliance-sensitive phrasing, and past-tense results language for unshipped capability. It's what makes the evidence guardrails enforceable by every future writer and tool.
+
+## Red team: the pre-mortem
+
+An adversarial pass is standard QA for strategy (Klein's pre-mortem). For AI-generated strategy it is essential: the chain is long and drift accumulates. Personas argue **hard** — a skeptical target customer, the strongest competitive alternative writing a counter-pitch, a skeptical board member. Personas produce severity-rated findings, never pass/fail; the value of the pass is proportional to how hard it argues.
+
+## Gap-first ingestion
+
+Documents describe the product from the inside. Positioning and vision also need outside-in evidence: customer language, competitive alternatives, win/loss, market data (Dunford; JTBD research per Christensen/Ulwick). The single biggest failure mode of "positioning from the PRD" is inside-out positioning that describes the architecture instead of the customer's problem. So ingestion always produces the gap report, and the intake interview is the front door for filling it — for early-stage companies the founder interview is the highest-density corpus, and the documents are supporting evidence for what it surfaces.