@keighleykodric/weeve 0.1.0

package/WORKFLOW.md

@@ -0,0 +1,354 @@
+# WORKFLOW.md — Cross-pack rhythm
+
+How ideas move from raw capture through to shipped code. This is the canonical doc for the cross-pack workflow. All sibling pack READMEs cite this file.
+
+---
+
+## The rhythm in one sentence
+
+> Capture raw ideas in your preferred tool. Each lane's intake skill routes them. Lanes process their slice. Recommendations accumulate. Pilot synthesizes and ships.
+
+---
+
+## The full flow
+
+```
+Your capture tool (notes, daily log, Obsidian, etc.)
+    ↓ raw capture
+*-intake skills (per pack)
+    ↓ scoped rows with stable IDs
+Pack main skills (primitives, zones, layers, campaigns)
+    ↓ structured findings
+<pack>-recommendations.md (the recommendations file)
+    ↓ one file per pack in docs/<pack>/
+/pilot-roadmap
+    ↓ merged, tiered, conflict-surfaced
+docs/pilot/pilot-roadmap.md
+    ↓
+/pilot-ship
+    ↓ N items per day, guardrails, PR
+shipped code
+```
+
+---
+
+## Step by step
+
+### Step 1 — Raw capture
+
+Every idea, observation, or strategic thought gets captured first — in whatever tool you use. A daily note, an Obsidian vault, a plain text file. The goal is capture, not routing — get it down before it evaporates.
+
+```
+User-to-user referral program — tight community, peer vouching,
+low CAC. Maps to Compass doctrine + Layers+ Layer 4-7 + Maven channel strategy.
+```
+
+This goes in your project notes. You can also skip straight to Step 2 and capture directly via intake skills.
+
+> **Tip:** [Claudette](https://github.com/keighleykodric/claudette) is a personal CLI companion built for this workflow — `/research`, `/todo`, `/focus` commands that feed naturally into Weeve's intake skills. Not required, but designed to pair well.
+
+### Step 2 — Route to lanes via intake skills
+
+Once captured, route the idea to the lanes that own slices of it. Each lane has an intake skill that accepts raw intent — paste in whatever context you have — and writes a scoped row with a stable ID.
+
+**What to include with your intake:** The more context you provide, the better the intake skill can scope the work. Include any of:
+- The idea or observation in your own words
+- Links to relevant docs, tickets, or threads
+- File paths or folder references in your codebase
+- Screenshots, error messages, or user feedback
+- Ticket/issue IDs from your project tracker
+
+The intake skill will ask clarifying questions if it needs more.
+
+```
+/compass-intake    → CI-prefixed row → routes to compass-position / compass-move
+/layers-plus-intake → LI-prefixed row → routes to layers-plus-strategy / surface
+/ally-intake       → AI-prefixed row → routes to ally zone audit
+/rubric-intake     → RI-prefixed row → routes to rubric-components / patterns
+/maven-intake      → MI-prefixed row → routes to maven-campaign-plan / deliverable
+```
+
+One idea may produce intake rows in multiple packs if it spans strategy, product, and channel.
+
+### Step 3 — Packs process their slice
+
+Each pack's main skills process the intake rows. They write findings to their output files under `docs/<pack>/` in the consumer project.
+
+- Compass primitives + lenses → findings in `compass-*.md`
+- Layers+ layers → findings in `layers-plus-*.md`
+- Ally zones → findings in `ally-*.md`
+- Rubric zones → findings in `rubric-*.md`
+- Maven phases → findings in `maven-*.md`
+
+Each pack is autonomous — it doesn't need the others to run.
+
+### Step 4 — Recommendations: the shared output format
+
+Each pack writes a `<pack>-recommendations.md` file — the recommendations file Pilot reads. This file is the distilled, tiered, prioritized output of all the pack's work. It's the only file Pilot needs from each pack.
+
+```
+docs/compass/compass-recommendations.md
+docs/layers-plus/layers-plus-recommendations.md
+docs/ally/ally-recommendations.md
+docs/rubric/rubric-recommendations.md
+docs/maven/maven-recommendations.md
+```
+
+### Step 5 — Pilot synthesizes: /pilot-roadmap
+
+`/pilot-roadmap` reads all `<pack>-recommendations.md` files present, merges them into one prioritized backlog, surfaces cross-pack conflicts, and writes `docs/pilot/pilot-roadmap.md`.
+
+Items are tiered: Now → Next → Watch. Cross-pack conflicts are surfaced explicitly — Pilot does not silently pick a side.
+
+### Step 6 — Pilot ships: /pilot-ship
+
+`/pilot-ship` picks N items from the roadmap, executes against guardrails (constraints, design system health, accessibility health), and opens or updates a PR.
+
+One daily batch, one check-in, one PR.
+
+---
+
+## The worked example — user-to-user referral
+
+A strategic idea decomposed across the full system. This is the canonical illustration of how a cross-cutting idea flows. The route-then-decompose pattern is identical for any cross-functional setting: a SaaS team routing a growth initiative across strategy and delivery, a consulting firm coordinating an engagement across strategy and operations, a nonprofit aligning programme design with communications and fundraising.
+
+### The idea
+
+Existing users send a personalized referral link to a peer who isn't on the platform. Link carries context (referrer ID, prefilled profile, voucher message). Recipient lands on a guided signup that knows who sent them. Referring user sees status updates. Reward: free month per successful referral.
+
+### Why it spans multiple packs
+
+| Pack | Its slice |
+| --- | --- |
+| Compass | Strategic bet: is referral the right growth wedge? Which doctrine supports it? |
+| Layers+ | Product surface: how does referral become a first-class product object? |
+| Maven | Channel: how do we announce the program and sustain referral messaging? |
+
+### How it flows
+
+| Step | Tool | What happens |
+| --- | --- | --- |
+| 1 | Your notes / capture tool | Raw capture: "User-to-user referral program — tight community, peer vouching, low CAC." Lands in project notes. |
+| 2 | `/compass-intake` | Strategic slice captured: "Codify referral-as-growth-wedge as doctrine; specific move = build user-to-user invite mechanic." Writes CI-prefixed row. |
+| 3 | `/compass-doctrine`, `/compass-move` | Process intake. Writes doctrine row (D-prefixed) and move row (M-prefixed). |
+| 4 | `/layers-plus-intake` | Product slice: "Build referral as first-class product surface — Layer 4 strategic bet, Layers 5-7 implementation." Writes LI-prefixed row. |
+| 5 | `/layers-plus-strategy`, `/layers-plus-conceptual-model`, `/layers-plus-interaction-flow`, `/layers-plus-surface` | Each layer processes its scoped rows. |
+| 6 | `/maven-intake` | Channel slice: "Plan referral program announcement + ongoing referral messaging." Writes MI-prefixed row. |
+| 7 | `/maven-campaign-plan`, `/maven-deliverable` | Process intake. Writes campaign plan and deliverable rows. |
+| 8 | `/compass-recommendations`, `/layers-plus-recommendations`, `/maven-recommendations` | Each pack writes its prioritized recommendations. |
+| 9 | `/pilot-roadmap` | Reads all three recommendations files. Synthesizes one backlog. Referral shows as one tracked initiative with strategy, product, and channel slices. |
+| 10 | `/pilot-ship` | Picks N items, executes, opens PR. |
+
+### Key pattern
+
+Single-pack ideas exist ("add a tooltip on the time-window picker" → Layers+ only). Most strategic ideas don't. The route-then-decompose pattern handles both:
+
+- A tooltip change is one intake row.
+- A growth wedge is six.
+
+**Heuristic:** if you're not sure where it lands, ask "what's the *highest* tier this touches?" Start there and let it cascade. The referral idea's highest tier is Compass (strategic bet about *how we grow*). Start there.
+
+---
+
+## First-run order
+
+When setting up the system from scratch, run packs in this order. Each step produces inputs that make the next step richer.
+
+```
+1.  Compass    — establish strategic position and growth doctrine
+2.  Layers+    — evaluate product design against that strategy
+3.  Felt       — audit user research posture; feeds observed-behaviour and user-needs
+4.  Ally       — audit accessibility on the existing surface
+5.  Rubric     — audit design system health
+6.  Maven      — develop marketing positioning and brand voice
+7.  Pitch      — audit revenue health and GTM execution (reads Maven positioning)
+8.  Pilot      — synthesize all recommendations files
+```
+
+**Why this order:** Compass sets the strategic frame; Layers+ uses it. Felt runs after Layers+ because its research output (felt-research.md, felt-personas.md) feeds directly into layers-plus-observed-behaviour and layers-plus-user-needs confidence ratings — run Layers+ first to know what research questions are open, then run Felt to answer them. Ally and Rubric are parallel (order between them doesn't matter). Maven reads Compass and Layers+ outputs for positioning context. Pitch runs after Maven — it checks whether the positioning is landing in deals and co-owns the Marketing→Sales lead handoff. Pilot reads all. (Forge/Helm/Verify/Guard can run in parallel after Layers+; see PITCH-LANE.md for the full 11-lane sequencing.)
+
+Packs can be run in any order — this sequence is the recommended path for a first full run, not a hard dependency.
+
+---
+
+## Within-pack sequences
+
+Cross-pack order is in the First-run order section above. Within each pack, skills run in a defined sequence. Steps marked _(optional)_ can be skipped on first run and added on re-runs or when the area is relevant.
+
+### Compass
+
+```
+/compass-intro          — onboarding; load once per project
+/compass-orient         — broad diagnostic; shows which primitives are missing
+/compass-position       — what you have, who your customers are, which markets
+/compass-context        — external forces, trends, competitor moves
+/compass-doctrine       — operating principles and anti-patterns
+/compass-choice         — active strategic choices and decisions
+/compass-move           — strategic moves in flight
+Lens skills (pick relevant ones):
+  /compass-wardley      — Wardley map; evolution and ecosystem position
+  /compass-jtbd         — Jobs-to-be-done; primary market and outcomes
+  /compass-7powers      — 7 Powers; defensibility check
+  /compass-market-research  — (optional) external signal probe
+/compass-recommendations — tiered move list from all lens outputs
+```
+
+### Layers+
+
+```
+/layers-plus-intro      — onboarding; load once per project
+/layers-plus-orient     — broad diagnostic across all seven layers
+/layers-plus-user-needs — formalise user needs and job stories
+/layers-plus-domain     — domain concepts, terminology, constraints
+/layers-plus-conceptual-model — product objects, relationships, key attributes
+/layers-plus-interaction-flow — task flows, decision points, failure paths
+/layers-plus-surface    — screens, UI surfaces, component inventory
+/layers-plus-observed-behaviour  — (optional) user research synthesis
+/layers-plus-strategy   — opportunity map tied to user needs
+/layers-plus-recommendations — prioritised improvement list
+```
+
+### Felt
+
+```
+/felt-intro             — onboarding; load once per project
+/felt-orient            — broad diagnostic across all seven research zones
+Zone skills (run the zone with the biggest gap first):
+  /felt-research        — generative research coverage audit
+  /felt-testing         — usability and evaluative test coverage audit
+  /felt-data            — analytics instrumentation and funnel audit
+  /felt-journey         — journey map coverage and pain point catalogue
+  /felt-personas        — segment definitions and JTBD validity audit
+  /felt-synthesis       — affinity maps, themes, HMW statements
+  /felt-feedback        — NPS, CSAT, support tickets, app reviews
+Ad hoc:
+  /felt-intake          — capture research requests and observations any time
+Output (on demand from zone data):
+  /felt-report          — stakeholder-ready research readout
+  /felt-recommendations — tiered research gap list (Pilot reads this)
+Maintenance:
+  /felt-triage          — walk open findings; close / defer / dismiss
+  /felt-check           — verify closed findings are actually resolved
+  /felt-tickets         — push findings to task management
+  /felt-dashboard       — HTML visual status dashboard
+```
+
+### Ally
+
+```
+/ally-intro             — onboarding and zone framework; load once per project
+/ally-map               — route inventory + broad pass across all 7 zones
+/ally-landscape         — bottleneck analysis; recommends which zone to address next
+Zone skills (run the zones landscape recommends first):
+  /ally-bones           — semantic structure, landmarks, relationships
+  /ally-flow            — keyboard nav, focus management, wayfinding
+  /ally-signal          — contrast, text alternatives, media
+  /ally-control         — input, touch, pointer, errors, forms
+  /ally-ease            — time limits, language, reading level
+  /ally-calm            — flashing, harmful motion, sensory overwhelm
+  /ally-reach           — AT compatibility, screen readers, name/role/value
+Output (on demand from audit data):
+  /ally-plan            — ally-recommendations.md (Pilot reads this)
+  /ally-status          — team health snapshot
+  /ally-report          — org/leadership progress view
+```
+
+### Rubric
+
+```
+/rubric-intro           — onboarding; load once per project
+/rubric-gap [topic]     — (optional) trace a gap cascade before the zone audits
+Zone audits (run in order; each builds on the last):
+  /rubric-tokens        — foundations: CSS tokens, colour, spacing
+  /rubric-components    — component inventory and conformance
+  /rubric-patterns      — layout patterns, page templates
+  /rubric-voice         — copy tone, vocabulary, Tier 1/2/3 conventions
+/rubric-audit           — full sweep across all four zones
+/rubric-recommendations — prioritised system improvements (Pilot reads this)
+```
+
+### Maven
+
+```
+/maven-intake           — route raw observations to Maven; writes stable IDs
+/maven-positioning      — ICP, problem statement, unique attribute
+/maven-brand-voice      — tone, vocabulary, voice rules
+/maven-channel-monitor  — (optional) monitor live channel signals
+/maven-campaign-plan    — campaign design for a specific motion
+Deliverables (on demand):
+  /maven-deliverable    — one-pager, case study, or other artifact
+  /maven-social         — platform-specific social posts
+  /maven-email          — email sequence
+  /maven-battlecard     — competitive battlecard
+  /maven-seo            — keyword and content gap analysis
+/maven-recommendations  — prioritised marketing improvements (Pilot reads this)
+```
+
+### Pitch
+
+```
+/pitch-intake           — route raw sales observations (deals, objections, patterns)
+/pitch-orient           — diagnostic sweep; surfaces bottleneck zone
+Zone audits (run weekly or on trigger):
+  /pitch-pipeline       — stage distribution, velocity, stall rate, coverage
+  /pitch-icp            — deal-level ICP fit and qualification discipline
+  /pitch-conversion     — stage-to-stage drop-off, deal size, time-to-close
+  /pitch-competitive    — win/loss patterns, battlecard accuracy
+  /pitch-outreach       — sequence performance, channel mix, positioning alignment
+  /pitch-proposal       — discovery quality, demo effectiveness, reference coverage
+  /pitch-pricing        — discount discipline, pricing floor, pricing power
+  /pitch-leads          — marketing → sales handoff (co-owned with Maven)
+  /pitch-forecast       — commit-to-close rate, methodology health
+  /pitch-handoff        — sales → CS handoff quality, early churn indicators
+/pitch-recommendations  — prioritised sales moves (Pilot reads this)
+```
+
+---
+
+## Cadence
+
+| Pack | Typical cadence |
+| --- | --- |
+| Ally | Weekly (change detection) |
+| Rubric | Weekly (drift detection) |
+| Felt | On-demand (after each research study; quarterly hygiene sweep) |
+| Layers+ | Monthly or on-demand (deeper, slower-changing) |
+| Compass | Quarterly (strategic position) |
+| Maven | On-demand (campaign-driven) |
+| Pitch | Weekly (pipeline, conversion, forecast); on-trigger for competitive, pricing, handoff |
+| Pilot `/roadmap` | After any pack refreshes its recommendations |
+| Pilot `/ship` | Daily (autonomous batch) |
+
+---
+
+## Roadmap refresh triggers
+
+`/pilot-roadmap` should be re-run when one of three trigger types fires. Running it on an arbitrary schedule produces noise; running it only when these triggers fire keeps it signal-dense.
+
+**Milestone trigger** — re-run after any of:
+- A pack completes a run and writes a new `<pack>-recommendations.md`
+- A ship batch closes (all Now items shipped → re-read to confirm and promote Next items)
+- A new pack is installed or an existing pack is significantly revised
+
+**Signal trigger** — re-run immediately when a Watch item escalates:
+- Any P-W item fires (competitor announcement, platform shift, external adopter feedback)
+- A constraint in `docs/business.md` changes (e.g., a legal or business blocker resolves)
+- A significant blocking finding is confirmed that wasn't in the current roadmap
+
+**Time-based floor** — re-run at minimum once per quarter, even if no milestone or signal trigger has fired. Quarterly runs catch slow drift: Watch items that have aged past their revisit date, Next items whose effort estimates are now stale, constraints that have silently become unblocked.
+
+**Who triggers it:** The Pilot operator (see GOVERNANCE.md § Roles). On teams, any pack owner can request a re-run by opening a PR to update their `<pack>-recommendations.md` and tagging the Pilot operator for review.
+
+**What happens after a re-run:** Compare the new `pilot-roadmap.md` diff against the prior version. If any Now items changed tier, or any new conflicts surfaced, notify pack owners before starting the next `/pilot-ship` batch.
+
+---
+
+## Pack independence
+
+Every pack works standalone. The workflow above is opt-in, not required. A designer can run Layers+ alone. A strategist can run Compass alone. Cross-pack references are citations — each pack degrades gracefully when sibling outputs are absent.
+
+**The one exception:** Pilot needs at least one pack to have written a `<pack>-recommendations.md` file. With no packs writing recommendations, Pilot has nothing to synthesize. This is stated plainly in Pilot's README.
+
+---
+
+*Maintained in [keighleykodric/weeve-pilot](https://github.com/keighleykodric/weeve-pilot). All sibling pack READMEs cite this file.*

package/bin/weeve.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+const { execSync } = require("child_process");
+
+const ORG = "keighleykodric";
+
+const LANES = {
+  // Strategy & Product
+  compass: "Strategic positioning — Wardley, JTBD, 7 Powers",
+  "layers-plus": "Product design — 7-layer evaluation",
+  felt: "UX research — personas, journeys, synthesis",
+
+  // Design & Accessibility
+  ally: "Accessibility — WCAG 2.2 AA across 7 zones",
+  rubric: "Design system — tokens, components, patterns",
+
+  // Engineering & Operations
+  forge: "Engineering health — architecture, code health, CI/CD",
+  helm: "Platform ops — deploy, rollback, monitoring, SLOs",
+  verify: "QA — test strategy, regression, release readiness",
+  guard: "Security — threat model, secrets, auth, compliance",
+
+  // Go-to-Market
+  maven: "Marketing — positioning, brand voice, campaigns",
+  pitch: "Sales — pipeline, ICP, conversion, pricing",
+
+  // Orchestration
+  pilot: "Synthesis — reads all lanes, writes the roadmap",
+};
+
+const PRESETS = {
+  all: Object.keys(LANES),
+  core: ["compass", "layers-plus", "ally", "rubric", "pilot"],
+  strategy: ["compass", "layers-plus", "maven", "pilot"],
+  engineering: ["forge", "helm", "verify", "guard", "pilot"],
+  product: ["compass", "layers-plus", "ally", "rubric", "felt", "pilot"],
+  gtm: ["compass", "maven", "pitch", "pilot"],
+};
+
+const cmd = process.argv[2];
+const args = process.argv.slice(3);
+
+function run(command) {
+  try {
+    execSync(command, { stdio: "inherit" });
+  } catch {
+    process.exit(1);
+  }
+}
+
+function installLanes(lanes) {
+  const invalid = lanes.filter((l) => !LANES[l]);
+  if (invalid.length) {
+    console.error(`Unknown lane(s): ${invalid.join(", ")}`);
+    console.error(`Run 'weeve list' to see available lanes.`);
+    process.exit(1);
+  }
+
+  console.log(`\nInstalling ${lanes.length} lane(s)...\n`);
+  for (const lane of lanes) {
+    const repo = `${ORG}/weeve-${lane}`;
+    console.log(`  + ${lane} — ${LANES[lane]}`);
+    run(`npx skills add ${repo}`);
+  }
+  console.log(`\nDone. Run /pilot-intro to get started.\n`);
+}
+
+switch (cmd) {
+  case "add":
+  case "install": {
+    if (!args.length) {
+      console.error("Usage: weeve add <lane|preset> [lane2] [lane3]...");
+      console.error("       weeve add all");
+      console.error("       weeve add core");
+      console.error("Run 'weeve presets' to see preset groups.");
+      process.exit(1);
+    }
+
+    // Check if first arg is a preset
+    if (args.length === 1 && PRESETS[args[0]]) {
+      const preset = args[0];
+      console.log(`Preset: ${preset} (${PRESETS[preset].join(", ")})`);
+      installLanes(PRESETS[preset]);
+    } else {
+      installLanes(args);
+    }
+    break;
+  }
+
+  case "list":
+  case "lanes": {
+    console.log("\nAvailable lanes:\n");
+    const maxLen = Math.max(...Object.keys(LANES).map((k) => k.length));
+    for (const [name, desc] of Object.entries(LANES)) {
+      console.log(`  ${name.padEnd(maxLen + 2)}${desc}`);
+    }
+    console.log();
+    break;
+  }
+
+  case "presets": {
+    console.log("\nPresets:\n");
+    for (const [name, lanes] of Object.entries(PRESETS)) {
+      console.log(`  ${name.padEnd(14)}${lanes.join(", ")}`);
+    }
+    console.log("\nUsage: weeve add <preset>\n");
+    break;
+  }
+
+  case "help":
+  case undefined:
+  case "--help":
+  case "-h": {
+    console.log(`
+weeve — Cross-functional alignment system
+
+Commands:
+  weeve add <lane> [lane2...]   Install one or more lanes
+  weeve add <preset>            Install a preset group of lanes
+  weeve list                    Show all available lanes
+  weeve presets                 Show preset groups
+
+Examples:
+  weeve add compass ally pilot  Install three lanes
+  weeve add core                Install core preset (compass, layers-plus, ally, rubric, pilot)
+  weeve add all                 Install everything
+
+Presets:
+  all          Every lane
+  core         compass, layers-plus, ally, rubric, pilot
+  strategy     compass, layers-plus, maven, pilot
+  engineering  forge, helm, verify, guard, pilot
+  product      compass, layers-plus, ally, rubric, felt, pilot
+  gtm          compass, maven, pitch, pilot
+`);
+    break;
+  }
+
+  default:
+    console.error(`Unknown command: ${cmd}`);
+    console.error("Run 'weeve help' for usage.");
+    process.exit(1);
+}

package/docs/shared/SHIP-GATE.md

@@ -0,0 +1,113 @@
+# Ship gate protocol
+
+_The cross-functional quality gate that blocks `/pilot-ship` when critical findings are open._
+
+---
+
+## What gate-ship means
+
+A finding in any lane's recommendations file can carry a `gate-ship: true` field. When `/pilot-ship` runs, it scans the ship gate sections of Guard and Verify recommendations files. If any finding is marked `gate-ship: true` and its state is not `closed` or `accepted-risk`, the ship is blocked.
+
+**The gate is a hard stop, not an advisory.** `/pilot-ship` will not execute tasks in the affected area until the finding is resolved or an explicit operator override is recorded.
+
+---
+
+## Which lanes can trigger it
+
+Only two lanes have gate-ship authority by default:
+
+| Lane | Why | Typical triggers |
+|---|---|---|
+| **Guard** | Security findings that create active risk — credential exposure, supply chain compromise, missing controls on a live system | Critical-severity findings (🔴 Critical) |
+| **Verify** | Release readiness findings that mean the product is not safe to ship — no release process, no quality gate, untested critical path | Findings tagged `gate-ship: true` in `verify-release.md` |
+
+Other lanes (Forge, Helm, Ally, Rubric, Layers+, Maven, Felt, Compass) surface findings at 🔴 High / 🟡 Medium / 🟢 Low severity but do not gate ship. Their findings appear in the roadmap as Now / Next / Watch items. A 🔴 High finding from Ally is urgent but does not block — it becomes a Now item that `/pilot-ship` prioritises.
+
+---
+
+## Severity mapping
+
+| Finding severity | Gate behaviour |
+|---|---|
+| 🔴 Critical (Guard only) | **Blocks ship** — `gate-ship: true` by default |
+| 🔴 High | Now item in roadmap; does not gate ship |
+| 🟡 Medium | Next item; tracked with deadline |
+| 🟢 Low | Watch tier; not surfaced at ship time |
+
+Only Critical gates ship by default. If every High finding blocked, the gate would stop being credible. High findings belong on the next-batch punch list, not as a stop-everything signal.
+
+Verify's gate-ship works differently: any finding in `verify-release.md` can be explicitly tagged `gate-ship: true` regardless of severity — the release readiness zone owns that decision.
+
+---
+
+## How the block appears
+
+When `/pilot-ship` encounters an active gate-ship finding, it:
+
+1. Reports the finding in the check-in under `## Ship blocked`
+2. Lists the finding ID, pillar, severity, what it is, and why it blocks
+3. Stops execution for the affected area
+4. Does not proceed to task execution until the finding is resolved
+
+The block is per-area, not global. A Guard finding blocking compass and pilot repos does not block work in other repos. `/pilot-ship` will still execute tasks that don't touch the affected area.
+
+---
+
+## Override path
+
+An operator can override a gate-ship block. The override must include:
+
+1. **Recorded reason** — why shipping is acceptable despite the finding
+2. **Scope** — what area the override covers
+3. **Owner** — who made the decision
+
+The override is appended to the **Ship override history** table in the relevant recommendations file so the pattern becomes visible across runs. If the same finding is overridden repeatedly, the finding's severity or scope is wrong — surface it as a 🔴 item to fix the finding, not the override.
+
+```markdown
+## Ship override history
+
+| Date | Finding | Reason | Scope | Owner |
+|---|---|---|---|---|
+| 2026-05-25 | GR1 | Token rotated; audit log clean; gate lifted | compass, pilot | @operator |
+```
+
+---
+
+## Post-ship finding status
+
+Blocking findings do not auto-close on ship. When a gate-ship finding is resolved:
+
+1. The lane's `-check` skill verifies the fix (`/guard-check`, `/verify-check`)
+2. The finding state is updated to `closed` in the recommendations file
+3. The gate-ship field remains `true` but the state change lifts the block
+4. `/pilot-ship` reads the updated state on its next run and proceeds
+
+---
+
+## How to add gate-ship to a finding
+
+In a lane's recommendations skill spec, tag the finding:
+
+```markdown
+**gate-ship:** true
+**State:** open
+```
+
+The finding must also appear in a dedicated `## Ship gate` section at the top of the recommendations file so `/pilot-ship` can scan it without parsing the full document.
+
+---
+
+## Governance
+
+Changes to the gate-ship protocol (which lanes can trigger it, what severity level gates by default, override rules) are framework-level decisions. They should be:
+
+1. Documented here (this file is the canonical reference)
+2. Reflected in `lane-conventions.md` under the severity mapping section
+3. Communicated to all lane maintainers
+
+Adding gate-ship authority to a new lane requires a recorded decision in `docs/decisions.md` — it changes the power dynamics of Weeve.
+
+---
+
+_Source: `lane-conventions.md` severity mapping, Guard and Verify recommendations skill specs, `/pilot-ship` skill spec_
+_Generated by [pilot](https://github.com/keighleykodric/weeve-pilot) · 2026-05-25_