@keighleykodric/weeve 0.1.0 → 0.1.2

package/spec/weeve-yaml.md

@@ -0,0 +1,274 @@
+# weeve.yaml — project config reference
+
+`weeve.yaml` is the project-level config file for a weeve setup. It lives at the root of any repo that participates in a weeve workflow. Skills read it on startup to resolve `$DOCS_ROOT` and understand which lanes are active.
+
+---
+
+## Minimal config
+
+```yaml
+schema_version: "0.4"
+
+project:
+  name: My Project
+  tag: MYP
+```
+
+`project.tag` is the 3-letter (or short) identifier used to locate your docs folder. Skills resolve two root paths per project:
+
+| Variable | Default path | Purpose |
+|---|---|---|
+| `$LOOM_ROOT` | `<vault_path>/Projects/<tag>/loom` | **Input zone** — human-written notes, research, and orienting context. Skills read from here. |
+| `$DOCS_ROOT` | `<vault_path>/Projects/<tag>/weeve` | **Output zone** — structured analysis written by skills (signals, reports, priorities). Skills write here. |
+
+An `archive/` folder at `<vault_path>/Projects/<tag>/archive/` holds historical snapshots. It is not referenced by `$LOOM_ROOT` or `$DOCS_ROOT` — recap and archival skills write there directly.
+
+**Rule of thumb:** if a skill writes it, it lives in `$DOCS_ROOT`. If you wrote it (notes, research, briefs), it lives in `$LOOM_ROOT`. Skills read from `$LOOM_ROOT` via `source_dirs`; they write to `$DOCS_ROOT`.
+
+**Shared files in `$DOCS_ROOT/shared/`** (skill-generated and maintained):
+- `weeve-guardrails.md` — hard limits captured during intro
+- `weeve-decisions.md` — locked decisions log
+- `weeve-project.md` — project brief scaffolded by intro skills
+- `weeve-business.md` — strategic context
+- `weeve-users.md` — audience definition
+- `lane-conventions.md` — severity → ship-gate mapping
+- `signals-digest.md` — top signals per lane (written by `/pilot-check`)
+
+---
+
+## Full config reference
+
+```yaml
+# weeve.yaml
+schema_version: "0.4"
+
+project:
+  name: Acme Platform          # Human-readable project name
+  tag: ACP                     # Short ID — matches your vault's Projects/<tag>/ folder
+  docs_root: ./weeve           # Optional: explicit path to lane outputs folder ($DOCS_ROOT).
+                               # When set, skills write here directly (no vault needed).
+                               # Default: inferred as <vault_path>/Projects/<tag>/weeve
+  loom_root: ./loom            # Optional: explicit path to the input zone ($LOOM_ROOT).
+                               # Default: inferred as <vault_path>/Projects/<tag>/loom
+  depends_on:                  # Optional: other weeve projects this project reads context from.
+    - tag: API                 # Required: the other project's tag
+      name: Core API           # Optional: human label
+      relationship: api-contract # Optional: nature of the dependency
+
+roads:
+  - name: startup              # Road name (used in pilot-priorities)
+    path: roads/startup        # Path to road definition file (relative to repo root)
+
+lanes:
+  compass:
+    tag: ORG                   # Optional: use a different tag for cross-project lanes.
+                               # Useful when Compass covers the whole org, not just this repo.
+    source_dirs:               # Optional: loom subdirs this lane scans. Paths relative
+      - strategy/              # to $LOOM_ROOT. Defaults vary by lane (see table below).
+      - business/              # Override here if your project uses a different structure.
+                               # Omit to use lane defaults.
+```
+
+Lane `source_dirs` defaults (used when not specified in `weeve.yaml`). All paths are relative to `$LOOM_ROOT`:
+
+| Lane | Default source dirs |
+|---|---|
+| compass | `strategy/`, `business/` |
+| felt | `research/` |
+| ally | `design/` |
+| layers-plus | `design/` |
+| rubric | `design/`, `marketing/` |
+| maven | `marketing/` |
+| pitch | `sales/` |
+| forge | `engineering/` |
+| helm | `engineering/` |
+| verify | `engineering/` |
+| guard | `engineering/`, `business/` |
+
+All lanes also read `$LOOM_ROOT/shared/` regardless of `source_dirs` — place any cross-lane notes or raw context you want every skill to see here. Skill-managed shared files (`weeve-guardrails.md`, `weeve-decisions.md`, etc.) live in `$DOCS_ROOT/shared/`.
+```
+
+---
+
+## Multi-repo setup
+
+Weeve works across multiple repos. Each participating repo has its own `weeve.yaml` with the **same `project.tag`**. All repos write into the same `$DOCS_ROOT`, so Pilot sees a unified picture across the codebase.
+
+```
+my-workspace/
+  acme-web/
+    weeve.yaml         # project.tag: ACP
+  acme-api/
+    weeve.yaml         # project.tag: ACP  ← same tag
+  acme-mobile/
+    weeve.yaml         # project.tag: ACP  ← same tag
+```
+
+Skills are run from whichever repo is relevant. They all resolve to the same `$DOCS_ROOT` and write their outputs there. Lane outputs accumulate — you'll see findings from the web, API, and mobile codebases in the same signals files.
+
+**Optional: document which repos participate**
+
+```yaml
+project:
+  name: Acme Platform
+  tag: ACP
+  repos:
+    - name: web
+      path: ../acme-web
+    - name: api
+      path: ../acme-api
+    - name: mobile
+      path: ../acme-mobile
+```
+
+This is informational — weeve doesn't use `repos` to drive resolution, but it documents the full surface area for future tooling (e.g., `weeve status` across repos).
+
+---
+
+## Project relationships (`depends_on`)
+
+Projects don't exist in isolation. A frontend depends on an API. A platform team's decisions affect every product team. `depends_on` makes those relationships explicit — without requiring a hierarchy.
+
+```yaml
+project:
+  name: Frontend
+  tag: FE
+  depends_on:
+    - tag: API
+      name: Core API             # Optional: human-readable label
+      relationship: api-contract # Optional: describes the nature of the dependency
+    - tag: PLATFORM
+      name: Platform Team
+      relationship: infra
+```
+
+**What this does:**
+
+- Documents that this project reads context from, and is affected by, other weeve projects
+- Gives lanes access to dependent projects' `$DOCS_ROOT/shared/` as secondary context
+- Lets Pilot surface cross-project signals — a ship-blocked finding in API that affects Frontend's release
+
+**What this doesn't do:**
+
+- Impose a hierarchy — any project can depend on any other, in any direction
+- Require a shared parent — "org" or "fleet" is just what emerges from the full graph, not something weeve models
+- Give dependent projects write access — dependencies are read-only context
+
+**Accessing dependent project docs:**
+
+Skills resolve dependent project docs the same way they resolve their own `$DOCS_ROOT`:
+
+| Dependent project config | Resolves to |
+|---|---|
+| Has `docs_root` | That path directly |
+| Has `tag` only | `<vault_path>/Projects/<tag>/weeve` |
+
+Skills read `shared/` from each dependency as background context. Lane outputs are never written to a dependency's `$DOCS_ROOT`.
+
+**Example: cross-project Pilot**
+
+When Pilot runs on the Frontend project, it can read:
+- `$DOCS_ROOT/*/signals.md` — own project lane signals
+- `<API_DOCS_ROOT>/guard/signals.md` — API's security findings (relevant if FE calls API endpoints)
+- `<PLATFORM_DOCS_ROOT>/helm/signals.md` — Platform's deployment signals (relevant if FE uses platform infra)
+
+This surfaces blockers that live in a different repo but affect this project's ship readiness.
+
+**Shared docs between projects:**
+
+Use `$DOCS_ROOT/shared/weeve-sources.md` to reference external docs (Confluence, Notion). Use `depends_on` for other weeve projects. They're complementary:
+
+```
+shared/
+  weeve-project.md    ← what this project is
+  weeve-decisions.md  ← this project's decisions
+  weeve-guardrails.md ← this project's hard limits
+  weeve-sources.md    ← links to external org-level docs (Notion, Confluence, etc.)
+```
+
+The org-level layer doesn't need to live in weeve. `weeve-sources.md` is a pointer, not a copy.
+
+**How Pilot uses `depends_on`:**
+
+When Pilot runs, it reads signals from two sources:
+
+1. **Own project** — all lane signals files under `$DOCS_ROOT`
+2. **Dependent projects** — signals files from each `depends_on` project's `$DOCS_ROOT`
+
+Pilot's output is a single ranked backlog. Findings from dependent projects that affect this project's ship readiness appear as cross-project items — attributed to their source, ranked alongside own-project findings. A `gate_ship: true` finding in a dependency surfaces as a blocker on this project's release even if this project's own lanes are clean.
+
+Each project's findings remain scoped to their own codebase. Running the same lane in two projects isn't a conflict — it's two views of the same dependency relationship, both visible to Pilot when needed.
+
+---
+
+## $DOCS_ROOT resolution order
+
+Every intro skill resolves both `$DOCS_ROOT` and `$LOOM_ROOT` in this order:
+
+**`$DOCS_ROOT` (output zone):**
+1. **`weeve.yaml` present with `project.docs_root`** — use that path directly. No vault needed. Good for teams that don't use Claudette.
+2. **`weeve.yaml` present with `project.tag`** — resolve as `<vault_path>/Projects/<tag>/weeve`.
+3. **No `weeve.yaml`** — fall back to Claudette config: match cwd basename to `config.projects[].repo`, derive tag and path from there.
+
+**`$LOOM_ROOT` (input zone):**
+1. **`weeve.yaml` present with `project.loom_root`** — use that path directly.
+2. **`weeve.yaml` present with `project.tag`** — resolve as `<vault_path>/Projects/<tag>/loom`.
+3. **No `weeve.yaml`** — derive from Claudette config using the same tag as `$DOCS_ROOT`.
+
+If neither resolves, the intro skill asks for paths before proceeding.
+
+---
+
+## Without Claudette
+
+If you're using weeve without Claudette (e.g., on a team), set `docs_root` explicitly:
+
+```yaml
+project:
+  name: Acme Platform
+  tag: ACP
+  docs_root: ./weeve         # relative to repo root, or absolute — skill outputs go here
+  loom_root: ./loom          # raw input zone — notes, research, briefs skills read from here
+```
+
+Skills will write to `docs_root` and read raw input from `loom_root`. You can put these folders anywhere — inside the repo, in a shared drive, or in a separate docs repo.
+
+---
+
+## Claudette integration contract
+
+Weeve and Claudette are independent tools. Using both is optional — neither requires the other. If you use both, the coupling is minimal and one-directional:
+
+| Direction | What | Why |
+|---|---|---|
+| weeve → Claudette | Reads `vault_path` from `~/.config/claudette/bootstrap.yaml` | To resolve `$DOCS_ROOT` when `docs_root` is not set in `weeve.yaml` |
+| Claudette → weeve | Nothing | Claudette doesn't read weeve outputs — Pilot does |
+
+**No conflicts by design:**
+
+- Weeve writes lane outputs to `$DOCS_ROOT/<lane>/
+` (e.g. `Projects/ACP/weeve/compass/`)
+- Claudette writes context files to `<vault_path>/Projects/<tag>/` (e.g. `Projects/ACP/_context-week.md`)
+- These are different folders under the same project root — no overlap, no overwriting
+
+**Removing Claudette:** if you stop using Claudette, set `docs_root` in `weeve.yaml` and nothing changes. Weeve stops looking at `~/.config/claudette/` entirely.
+
+**Adding Claudette later:** add `vault_path` to `~/.config/claudette/bootstrap.yaml` with a project entry matching your `project.tag`. Remove `docs_root` from `weeve.yaml` if you want outputs in the vault. Or keep `docs_root` — both approaches work.
+
+**The one field weeve reads from Claudette:**
+
+```
+~/.config/claudette/bootstrap.yaml → vault_path
+```
+
+That's it. Weeve reads no other Claudette config. Claudette reads no weeve config.
+
+---
+
+## Generated by `weeve init`
+
+`weeve init [preset]` creates `weeve.yaml` in the current directory. It prompts for project name and tag if not provided, then writes a config with the correct preset lanes listed in comments.
+
+---
+
+_Maintained in [`weeve`](https://github.com/keighleykodric/weeve) · `spec/weeve-yaml.md`_

package/.github/SECURITY.md

@@ -1,22 +0,0 @@
-# Security Policy
-
-## Reporting a Vulnerability
-
-If you discover a security vulnerability in any Weave framework repo, please report it responsibly by opening an issue on the [pilot repo](https://github.com/kjk/pilot/issues) with the label `security`.
-
-Do **not** open a public issue on the affected repo if the vulnerability could be exploited before a fix is available. In that case, email the maintainer or use a private GitHub issue on pilot.
-
-## Scope
-
-A security issue includes:
-
-- Credential or secret exposure in generated output
-- Path traversal or file-system access beyond intended scope
-- Prompt injection that bypasses guardrails
-- Unintended data leakage between commands or sessions
-
-General bugs, feature requests, and performance issues are **not** security issues.
-
-## Response
-
-Best effort. Reports will be acknowledged within **7 days**. Fixes are prioritized by severity.

package/GOVERNANCE.md

@@ -1,173 +0,0 @@
-# Governance — ownership and permissions
-
-Addresses how ownership and permissions work in Weeve across multiple people and teams — the gap between one person running all lanes solo and an org with specialists writing to specialist outputs.
-
-This is a known adoption gate. Solvable, mostly with infrastructure orgs already use, but it needs to be explicit before Weeve lands in any multi-team environment.
-
-## The problem
-
-Weeve is markdown-in-git. In a multi-person org, anyone with repo write access can edit anything. Without explicit ownership boundaries:
-
-- Non-specialists write to specialist outputs (marketer edits `compass-recommendations`, designer edits `maven-recommendations`)
-- Authority is ambiguous — consumers don't know if upstream is the right voice
-- Quality erodes as the wrong people make decisions
-- Trust in the contract files breaks down
-
-This is the natural failure mode of any document collaboration system at scale. Weeve needs a governance overlay that makes ownership visible and enforceable.
-
-## The architectural insight
-
-Weeve already has the right ownership structure built in:
-
-- Each pack has a domain (compass = strategy, maven = marketing, etc.)
-- Each contract file has a clear consumer (Pilot reads recommendations)
-- Each output has a logical author (the department that owns the pack)
-
-What's missing is the *governance overlay* that exposes this structure and enforces it. The good news: 80% of the solution is infrastructure orgs already use. Nothing new needs to be invented.
-
-## Editor, storage, reader — three separable layers
-
-A common adoption concern: *"won't non-technical departments resist GitHub?"* Weeve's answer is that **edit, store, and read are three separable layers**, and a department only has to engage with whichever it wants:
-
-| Layer | Who | Tool |
-|---|---|---|
-| **Editor** | The specialist team | Their preferred tool — GitHub, Obsidian, Notion (with markdown export), VS Code, Cursor |
-| **Storage** | The org (versioned, audited) | Git, Dropbox, Drive, Box, or self-hosted |
-| **Reader / consumer** | Everyone | Dashboard, AI agent, Slack notification, exported PDF, the markdown file itself |
-
-A marketer never has to touch GitHub directly. They consume Maven's outputs via the dashboard, get notifications via Slack, ask the AI agent for the latest positioning, and edit (if they edit at all) in a tool they already know. GitHub is plumbing.
-
-For non-technical orgs entirely, the storage layer can be something other than git. Downstream tools read from wherever; Weeve doesn't care.
-
-## Layer 1 — Git-native ownership (OSS, works today)
-
-GitHub CODEOWNERS solves the core write-permission problem. One file at the repo root:
-
-```
-docs/compass/      @leadership-team
-docs/maven/        @marketing-team
-docs/rubric/       @design-system-team
-docs/ally/         @accessibility-team
-docs/layers-plus/  @product-team
-docs/pilot/        @leadership-team
-```
-
-Combined with branch protection rules requiring owner approval, this is a hard gate. PRs touching those paths auto-request review from the right team and cannot merge without it.
-
-Adoption is the only friction. Most orgs using GitHub already use CODEOWNERS for code; using it for the docs folders is the same pattern applied one level over. Weeve should ship a template CODEOWNERS file and make adoption obvious during install.
-
-## Layer 2 — Pack-declared ownership (small addition)
-
-Each pack declares its owner, consumers, and contract in a small `pack.yaml`:
-
-```yaml
-pack: compass
-owner: leadership
-consumers: [product, engineering, marketing]
-contract: compass-recommendations.md
-```
-
-This becomes:
-
-- A scaffolding template — installing Compass for an org auto-generates the right CODEOWNERS entry, picking up the org's team names from a one-time setup
-- A documentation artifact — anyone reading the pack repo can see who owns what
-- Input to downstream tooling — populates role-based views and routing without extra configuration
-
-Small addition; large payoff in adoption clarity.
-
-## Read vs write
-
-Weeve gates *writes*, not reads. Cross-functional alignment depends on cross-pack readability:
-
-- Marketing reads `compass-position` to understand the strategic frame
-- Leadership reads `ally-recommendations` to understand accessibility commitments
-- Engineering reads `maven-recommendations` to understand the launch shape
-
-Everyone can read everything. Only the *authors* are gated.
-
-## Roles and ownership
-
-Each domain pack has an obvious owner (the department whose work it captures). Pilot doesn't — it's the meta-pack. "Owning Pilot" splits into three roles, which collapse to one or two people at startup scale but need to be named so they can separate cleanly as the org grows:
-
-| Role | Owns | Small startup | Medium startup |
-|---|---|---|---|
-| **Pilot operator** | Runs `/pilot-roadmap` and `/pilot-ship`. Routine work. | Eng lead, platform person, or founder | Platform team |
-| **Pilot owner** | The roadmap *output* and the prioritization that produces it. Cross-functional priorities. | Founder / CEO | Leadership team |
-| **Alignment platform owner** | Weeve config — which packs are installed, scoring weights, CODEOWNERS template, integrations. | Weeve champion | Platform / ops |
-
-At small scale (5–50 people), one person is typically all three. That's fine. Naming the roles now lets them split cleanly later without re-architecting.
-
-The departmental pack owners map straightforwardly:
-
-| Pack | Default owner |
-|---|---|
-| Compass | Leadership / founder |
-| Layers+ | Product / design |
-| Ally | Accessibility lead (or whoever owns a11y) |
-| Rubric | Design system / DesignOps |
-| Maven | Marketing |
-| _(Personal capture tool)_ | Personal — usually not shared |
-| Pilot | Leadership (output) + platform (config) |
-
-## Adoption shape — the `.alignment/` repo layout
-
-Concrete shape for an org adopting Weeve:
-
-```
-alignment/                   (the org's adoption repo, e.g. github.com/your-org/alignment)
-├── .alignment/              <- meta-config; owned by platform
-│   ├── config.yaml          <- installed packs, scoring weights, integrations
-│   ├── CODEOWNERS           <- write permissions per folder
-│   └── pack-overrides/      <- org-specific tweaks (rare)
-├── docs/
-│   ├── compass/             <- @leadership-team
-│   ├── layers-plus/         <- @product-team
-│   ├── ally/                <- @accessibility-team
-│   ├── rubric/              <- @design-system-team
-│   ├── maven/               <- @marketing-team
-│   └── pilot/               <- mixed ownership (see below)
-└── README.md
-```
-
-`.alignment/` is the meta-config layer. The platform person owns it; leadership owns the Pilot output (the roadmap); each department owns their pack's folder. CODEOWNERS enforces all of it.
-
-**Splitting `docs/pilot/` ownership:**
-
-The *roadmap content* is leadership's call (these are company priorities). The *operational config* is platform's call (scoring weights, drift thresholds, pack weighting). CODEOWNERS handles this file-by-file:
-
-```
-docs/pilot/pilot-roadmap.md       @leadership-team
-docs/pilot/pilot-config.yaml      @platform-team
-```
-
-That split mirrors the role split above.
-
-## Config control — who owns what across the system
-
-For an adopting org, configuration spans several layers. Each has a clear owner:
-
-| Config layer | What it controls | Owner |
-|---|---|---|
-| `.alignment/CODEOWNERS` | Write permissions per folder | Platform |
-| `.alignment/config.yaml` | Installed packs, scoring weights, integrations | Platform |
-| `pack.yaml` (per pack) | Pack-declared ownership and consumers | Platform (informed by departments) |
-| Pack version pinning | Which version of each pack is installed | Platform (via git, like any dependency) |
-| Integration credentials | OAuth tokens, webhook URLs | Platform; secured per org policy |
-| Pack content (per `docs/<pack>/`) | The actual recommendations and audit files | Department owner per pack |
-
-The config is owned by whoever owns the repo — typically the same person who already maintains the company's GitHub org or `.github/` folder. This isn't a new role to invent; it's a small addition to an existing responsibility.
-
-## Compliance posture
-
-For teams that care about compliance (SOC2, ISO27001, GDPR/CCPA), Weeve is structurally well-positioned:
-
-- **Audit trail.** Git history is already an immutable, signed, attributed change log — built in, not a paid feature.
-- **Access control.** CODEOWNERS + branch protection + GitHub teams = real RBAC, audited by an established external service.
-- **Data residency.** Customer's repo = customer's infrastructure = whatever residency they've already configured for source code. No new residency story to defend.
-- **Encryption.** GitHub's repo-at-rest encryption applies; transit is HTTPS. Same for any git-based backend.
-- **Backup.** Git is inherently distributed; backup is built in via every clone.
-- **Vendor risk.** BYO-everything means data stays in the adopter's infrastructure. No new vendor to evaluate for data handling.
-
-Adopters who need compliance stories (SOC2, vendor risk questionnaires) get one for free from the git-native architecture.
-
-