@keighleykodric/weeve 0.1.0

package/docs/shared/recommendations-schema.md

@@ -0,0 +1,363 @@
+---
+schema: recommendations
+version: v0.3
+date: 2026-05-24
+status: active
+---
+
+# Recommendations schema — v0.3
+
+*Authoritative versioned spec for the recommendations file format that all packs produce and Pilot reads.*
+
+This document is the authoritative spec. Every pack's recommendations skill writes a file that conforms to this shape. `/pilot-roadmap` reads those files and trusts them — it does not re-evaluate upstream sources. If a pack's output diverges from this spec, Pilot's merge step degrades silently.
+
+---
+
+## 1. File naming convention
+
+```
+docs/<pack>/<pack>-recommendations.md
+```
+
+| Pack | File path |
+|---|---|
+| Compass | `docs/compass/compass-recommendations.md` |
+| Layers+ | `docs/layers-plus/layers-plus-recommendations.md` |
+| Ally | `docs/ally/ally-recommendations.md` |
+| Rubric | `docs/rubric/rubric-recommendations.md` |
+| Maven | `docs/maven/maven-recommendations.md` |
+| Forge | `docs/forge/forge-recommendations.md` |
+| Helm | `docs/helm/helm-recommendations.md` |
+| Verify | `docs/verify/verify-recommendations.md` |
+| Guard | `docs/guard/guard-recommendations.md` |
+| Charter | `docs/charter/charter-recommendations.md` |
+| Anchor | `docs/anchor/anchor-recommendations.md` |
+| Ledger | `docs/ledger/ledger-recommendations.md` |
+| Roster | `docs/roster/roster-recommendations.md` |
+| Pitch | `docs/pitch/pitch-recommendations.md` |
+
+The filename is stable across re-runs. The skill overwrites in place; the roadmap always reads the latest snapshot.
+
+---
+
+## 2. Required sections
+
+Every recommendations file must contain these sections, in this order:
+
+1. **Summary block** — open findings counts by severity, current bottleneck, 1–2 sentence strategy statement
+2. **Tier 1** — act now (🔴 High findings or Compass T1 moves)
+3. **Tier 2** — plan for (🟡 Medium or Compass T2)
+4. **Tier 3** — watch (🟢 Low or Compass T3)
+5. **What's working — don't disrupt** — strengths the recommendations preserve
+6. **Manual checks required** — findings that need live testing or operator judgement
+7. **Out of scope / accepted exceptions** — deferred items with rationale and revisit trigger
+
+Optional sections (present in some packs, allowed in all):
+
+- **Cross-pillar citations** — where this pack's findings link to other packs
+- **Validation gaps** (Maven) — assumptions under 🔴 / 🟡 items not yet tested
+- **Evidence trace** (Compass) — source row IDs, confidence ratings, external signal count
+
+---
+
+## 3. Finding ID format
+
+Finding IDs must be stable across re-runs. If a finding is re-run and the underlying issue is unchanged, its ID does not change.
+
+### Format
+
+```
+<PACK-PREFIX><N>
+```
+
+Where `N` is a monotonically increasing integer within the pack's namespace. IDs are never reused for a different finding.
+
+### Registered pack prefixes
+
+| Pack | Prefix | Example |
+|---|---|---|
+| Compass / Strategy | `SR` | SR1, SR2 |
+| Layers+ / Tiers | `T1-`, `T2-`, `T3-` | T1-1, T2-3 |
+| Ally | `T1-`, `T2-`, `T3-` | T1-1, T2-2 |
+| Rubric | `RR` | RR1, RR2 |
+| Maven | `MR` | MR1, MR2 |
+| Forge | `FR` | FR1, FR2 |
+| Helm | `HR` | HR1, HR2 |
+| Verify | `VR` | VR1, VR2 |
+| Guard | `GR` | GR1, GR2 |
+| Charter | `CR` | CR1, CR2 |
+| Anchor | `AR` | AR1, AR2 |
+| Ledger | `LR` | LR1, LR2 |
+| Roster | `RO` | RO1, RO2 |
+| Pitch | `PR` | PR1, PR2 |
+| Felt | `FL` | FL1, FL2 |
+
+**Note on Layers+ and Ally sharing the `T1-`/`T2-`/`T3-` prefix:** both packs use tier-relative IDs rather than a pack-scoped prefix. When Pilot reads both files, it disambiguates by source file. Verbose mode tags items with their pillar: `[layers-plus:T1-1]` vs `[ally:T1-1]`. This is a known namespace collision — a future schema version may assign distinct prefixes to one or both packs.
+
+**Registering a new pack prefix:** add a row to the table above and increment the schema version.
+
+---
+
+## 4. Canonical finding shape
+
+This is the most important section. Every finding — whether written as a heading block (Compass/Maven style) or a table row (Layers+/Ally/Rubric style) — must carry these five fields.
+
+```
+id · severity · location · what's wrong · what to do
+```
+
+### Field definitions
+
+| Field | Required | Description |
+|---|---|---|
+| **id** | Yes | Stable pack-prefixed ID (see §3). Never changes between re-runs for the same finding. |
+| **severity** | Yes | 🔴 High / 🟡 Medium / 🟢 Low — consistent scale across all packs (see §5). |
+| **location** | Yes | File path, skill name, zone, route, or surface. Must be specific — not "everywhere" or "the codebase". |
+| **what's wrong** | Yes | One sentence describing the gap, drift, or risk. Describes the current state, not the desired state. |
+| **what to do** | Yes | One concrete action sentence. Describes the fix or move, not the problem. |
+| **evidence trace** | Optional | Source row IDs, confidence ratings, external signal count. Required for Compass lens skills. Recommended for any finding claiming Validated confidence. |
+| **gate-ship** | Optional | `true` / `false` (default: `false`). Set to `true` on findings that must be resolved before `/pilot-ship` proceeds. Only Guard and Verify set this by default; any lane may set it. `/pilot-ship` parses this field across all packs — do not use alternative names (`block`, `block-ship`, etc.). |
+
+### Heading-block format (Compass / Maven)
+
+```markdown
+### SR1 · Short title
+
+**Move:** What to do — one concrete sentence
+**Why now:** What erodes or compounds if this is deferred
+**Effort signal:** Low / Medium / High
+**Closes findings:** [finding IDs this move resolves]
+**Evidence:** [source row IDs, confidence, weight — e.g. "P2 (Hypothesis, Central) · 0 external signals"]
+```
+
+The `**Move:**` field satisfies **what to do**. The heading title + `**Move:**` context satisfies **what's wrong** (implied from the finding being surfaced at all; "Why now:" makes the gap explicit).
+
+### Table-row format (Layers+ / Ally / Rubric)
+
+```markdown
+| ID | Severity | Location | Finding | What to do | Effort |
+|---|---|---|---|---|---|
+| T1-1 | 🔴 High | [zone / file / path] | [one sentence — what's wrong] | [one sentence — what to fix] | M |
+```
+
+The columns map directly to the canonical shape. "Effort" is an extension field — allowed in all packs, not required by the schema.
+
+---
+
+## 5. Tier definitions
+
+| Tier | Name | Meaning | Compass label | Ally / Layers+ / Rubric / Maven label |
+|---|---|---|---|---|
+| T1 | Act now | Validated evidence of active erosion or a blocked user group. Deferring costs more. T1 findings must have at least one Validated input — Hypothesis-only evidence drops to T2. | T1 — Act now | 🔴 High |
+| T2 | Plan for | Gap or misalignment that will compound. Not urgent today. Schedule deliberately. | T2 — Plan for | 🟡 Medium |
+| T3 | Watch | Could escalate if an external signal changes. Review quarterly or on trigger. | T3 — Watch | 🟢 Low |
+
+The severity emoji (🔴 🟡 🟢) and the Compass tier labels are equivalent views of the same scale. Pilot maps them in both directions when building the merged roadmap.
+
+---
+
+## 6. Confidence / evidence notation
+
+Use these terms consistently in evidence traces and frontmatter:
+
+| Term | Meaning |
+|---|---|
+| **Validated** | Confirmed by observed output, user data, or external signal. Anchors T1 eligibility. |
+| **Working** | Hypothesis that has been partially tested or is grounded in consistent observed behaviour. T2 default. |
+| **Hypothesis** | Assumed but not yet tested. Cannot anchor a T1 finding without at least one Validated or Working co-source. |
+
+**Frontmatter usage (Maven pattern, optional for other packs):**
+
+```yaml
+foundation: validated | hypothesis | missing
+note: "Built without validated positioning. Treat as working hypothesis."
+```
+
+**Finding row usage:**
+
+Confidence is expressed in the evidence trace field: `"P2 (Hypothesis, Central) · 0 external signals"`. If a finding has no evidence trace, Pilot assumes Working confidence.
+
+---
+
+## 7. What Pilot reads — how `/pilot-roadmap` consumes this file
+
+`/pilot-roadmap` reads each pack's recommendations file as the authoritative source. It does not re-evaluate the upstream sources. The recommendations file is the unit of trust.
+
+**Extraction:** Pilot extracts per finding: ID, severity/tier, title, brief description, evidence trace, status (open / in-flight / closed / blocked). The canonical finding shape (§4) makes this extraction deterministic.
+
+**Tier mapping:**
+
+| Pack output | Roadmap tier |
+|---|---|
+| Compass T1 (Act now) | **Now** |
+| 🔴 High from any other pack | **Now** |
+| Compass T2 (Plan for) | **Next** |
+| 🟡 Medium from any other pack | **Next** |
+| Compass T3 (Watch) | **Watch** |
+| 🟢 Low from any other pack | **Watch** |
+| Closed or Retired | Dropped |
+
+**Validated-input gate:** if an item would land in **Now** but its evidence trace is Hypothesis-only or Assumed-only, Pilot demotes it to **Next** and adds a note. This gate is inherited from `/compass-recommendations` and applies across all pillars.
+
+**De-duplication:** if two packs surface findings that trace to the same source row or gap, Pilot collapses them into one roadmap item and notes that multiple pillars surfaced it. It does not write two items that rest on the same signal.
+
+**Conflict detection:** if two packs recommend opposing actions on the same surface, Pilot surfaces the conflict in the **Conflicts surfaced** section and does not silently pick a side.
+
+**Malformed file:** if a recommendations file is structurally unreadable (Pilot cannot extract IDs, tiers, or evidence), Pilot stops and surfaces the parse error. It does not write a degraded roadmap.
+
+---
+
+## 8. Current conformance
+
+Assessment against the canonical finding shape (§4): id · severity · location · what's wrong · what to do.
+
+### Compass (`/compass-recommendations`)
+
+**Status: Conformant with extensions.**
+
+Compass uses heading-block format. All five canonical fields are present:
+- ID: `SR<N>` prefix, stable.
+- Severity: implied by tier (T1 = High, T2 = Medium, T3 = Watch).
+- Location: "Closes findings: [lens finding IDs]" satisfies location indirectly. Location is lens-level, not file-path-level (expected for a strategy layer).
+- What's wrong: `**Why now:**` field.
+- What to do: `**Move:**` field.
+- Evidence trace: present and required (T1 moves must cite at least one Validated source).
+
+**Divergence:** Tier 3 uses a table format (signal to watch / trigger to escalate) rather than the heading-block format used for T1/T2. This is intentional and acceptable — T3 items are signals, not moves.
+
+---
+
+### Layers+ (`/layers-plus-roadmap`)
+
+**Status: Partially conformant — missing "what's wrong" (Finding) column.**
+
+Layers+ uses table-row format. The tier tables have: ID, Item (description), Layer(s), Effort, Findings closed.
+
+- ID: `T1-<N>` / `T2-<N>` / `T3-<N>` — conformant.
+- Severity: implied by tier placement — conformant.
+- Location: "Layer(s)" column satisfies location at the layer level — partially conformant (layer name, not file path or zone name).
+- What's wrong: **absent as a distinct column.** The "Item" column contains a fix description (what to do), not a gap description (what's wrong). The two-sided shape (gap + fix) is collapsed into one cell.
+- What to do: present in "Item" column.
+
+**Gap:** add a "Finding" column (what's wrong, one sentence) alongside the "Item" column (what to do). Without it, Pilot cannot extract the gap description for the **Why now** briefing in the roadmap.
+
+---
+
+### Ally (`/ally-plan`)
+
+**Status: Conformant with extensions.**
+
+Ally uses table-row format with: ID, Fix, WCAG, Zones, Routes, Effort, Findings closed.
+
+- ID: `T1-<N>` / `T2-<N>` / `T3-<N>` — conformant.
+- Severity: implied by tier — conformant.
+- Location: "Zones" + "Routes" columns provide richer location than the schema requires — conformant and exceeds minimum.
+- What's wrong: the "Findings closed" column links back to zone finding IDs, which carry the gap description in their source files. The recommendations file itself does not restate what's wrong in a dedicated column.
+- What to do: "Fix" column — conformant.
+- Extra: WCAG criterion column — an Ally-specific extension, not in schema but not conflicting.
+
+**Minor gap:** the "Finding" (what's wrong) is not restated inline in the recommendations table — it's in the source zone files. Pilot must follow the finding ID back to the zone file to get the gap sentence. Adding a brief "Finding" column to the tier tables (same as Layers+ gap above) would make the recommendations file self-contained.
+
+---
+
+### Rubric (`/rubric-status` → `rubric-recommendations.md`)
+
+**Status: Conformant (heading-block format, Compass-style).**
+
+Rubric uses heading-block format for T1/T2 and a table for T3. All five canonical fields are present:
+- ID: `RR<N>` — conformant.
+- Severity: implied by tier.
+- Location: "Closes findings:" field cites source finding IDs with file names — conformant.
+- What's wrong: "Why now:" field — conformant.
+- What to do: "Move:" field — conformant.
+- Evidence: present.
+
+**Note:** Rubric does not have a dedicated `/rubric-recommendations` skill — the recommendations file is produced by `/rubric-status`. The output conforms; the skill name diverges from the pattern. This is acceptable at v0.1 but should be noted for future skill naming conventions.
+
+---
+
+### Maven (`/maven-recommendations`)
+
+**Status: Conformant with extensions.**
+
+Maven uses heading-block format for 🔴 / 🟡 and a table for 🟢. All five canonical fields are present:
+- ID: `MR<N>` — conformant.
+- Severity: `🔴 High / 🟡 Medium / 🟢 Low` explicit in section headers — conformant.
+- Location: "Closes gap in:" field cites source files and sections — conformant.
+- What's wrong: "Why now:" field — conformant.
+- What to do: "Move:" field — conformant.
+- Evidence: "Evidence:" field — present and required for 🔴 items.
+
+**No gaps against canonical shape.**
+
+---
+
+### Forge (`/forge-recommendations`)
+
+**Status: Diverges — see [four-lane-reconciliation.md](../observations/four-lane-reconciliation.md).**
+
+Registered prefix: `FR`. Divergences to resolve: missing "What's working", "Manual checks required", "Out of scope" sections (D2); tier vocabulary uses Now/Next/Watch instead of 🔴/🟡/🟢 (D3); `block-ship` annotation not yet normalised to `gate-ship` (D7); evidence trace absent (D4).
+
+---
+
+### Helm (`/helm-recommendations`)
+
+**Status: Diverges — see [four-lane-reconciliation.md](../observations/four-lane-reconciliation.md).**
+
+Registered prefix: `HR`. Same divergences as Forge (D2, D3, D4, D7).
+
+---
+
+### Verify (`/verify-recommendations`)
+
+**Status: Diverges — see [four-lane-reconciliation.md](../observations/four-lane-reconciliation.md).**
+
+Registered prefix: `VR`. Same divergences as Forge (D2, D3, D4, D7). Verify is also a ship-gate lane — `gate-ship: true` applies to release-blocking findings.
+
+---
+
+### Guard (`/guard-recommendations`)
+
+**Status: Diverges — see [four-lane-reconciliation.md](../observations/four-lane-reconciliation.md).**
+
+Registered prefix: `GR`. Same divergences as Forge (D2, D3, D4, D7). Guard is also a ship-gate lane — `gate-ship: true` applies to Critical findings. Guard adds an `accepted-risk` triage state not yet in the base schema; this is a Guard-specific extension.
+
+---
+
+### Charter, Anchor, Ledger, Roster, Pitch
+
+**Status: Scaffold only — recommendations skills not yet written.**
+
+Registered prefixes: `CR` (Charter), `AR` (Anchor), `LR` (Ledger), `RO` (Roster), `PR` (Pitch). Conformance assessment pending skill development.
+
+---
+
+### Summary table
+
+| Pack | ID | Severity | Location | What's wrong | What to do | Evidence trace | Status |
+|---|---|---|---|---|---|---|---|
+| Compass | Conformant | Conformant | Conformant (lens-level) | Conformant | Conformant | Required | **Conformant** |
+| Layers+ | Conformant | Conformant | Partial (layer name only) | **Absent** | Conformant | Not present | **Diverges — missing Finding column** |
+| Ally | Conformant | Conformant | Conformant | Indirect (via finding ID) | Conformant | Not present | **Minor gap — Finding not inline** |
+| Rubric | Conformant | Conformant | Conformant | Conformant | Conformant | Present | **Conformant** |
+| Maven | Conformant | Conformant | Conformant | Conformant | Conformant | Required | **Conformant** |
+| Forge | Pending | Pending | Pending | Pending | Pending | Absent | **Diverges — see reconciliation doc** |
+| Helm | Pending | Pending | Pending | Pending | Pending | Absent | **Diverges — see reconciliation doc** |
+| Verify | Pending | Pending | Pending | Pending | Pending | Absent | **Diverges — see reconciliation doc** |
+| Guard | Pending | Pending | Pending | Pending | Pending | Absent | **Diverges — see reconciliation doc** |
+| Charter / Anchor / Ledger / Roster / Pitch | — | — | — | — | — | — | **Scaffold only** |
+
+---
+
+## 9. Schema changelog
+
+| Version | Date | Change |
+|---|---|---|
+| v0.1 | 2026-05-22 | Initial publication — making the implicit schema explicit. No changes to pack skill specs in this version; conformance gaps noted above are addressed as follow-on work. |
+| v0.2 | 2026-05-24 | Register prefixes for 9 new lanes (FR/HR/VR/GR/CR/AR/LR/RO/PR). Add `gate-ship` field to canonical finding shape §4. Add §1 file paths and §8 conformance entries for all new lanes. Reconciliation divergences (D1–D7) documented in four-lane-reconciliation.md; skill-level fixes tracked separately. |
+| v0.3 | 2026-05-24 | Register `FL` prefix for Felt (UX research lane). |
+
+---
+
+_Maintained in `pilot` repo · `docs/shared/recommendations-schema.md`_
+_Next review: when any pack skill spec is updated to change its finding table shape, or when a new pack is added._

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@keighleykodric/weeve",
+  "version": "0.1.0",
+  "description": "Cross-functional alignment system — install and manage Weeve lanes",
+  "bin": {
+    "weeve": "./bin/weeve.js"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/keighleykodric/weeve.git"
+  },
+  "keywords": ["weeve", "alignment", "cross-functional", "claude-code", "skills"]
+}