@rafinery/cli 0.2.2 → 0.4.0

package/blueprint/.rafa/capabilities/plan.md

@@ -1,38 +0,0 @@
-# plan — brain-grounded ADR decomposition  (DRAFT · capability #3)
-
-> Status: **draft / spec.** The first *consumer* of the stores — where the brain starts to pay
-> off. Depends on: brain (#1), ledger (#2). Built after the stores are proven in real use.
-
-Turn an intent into an approval-gated **ADR plan**, *grounded* in the brain (don't re-derive)
-and *aware* of the ledger (fold improvement into the work). Invoke via `/plan <intent>`.
-
-## Why plan fits the mission (the integration)
-
-plan is the first place knowledge + improvement meet real work, all keyed on **domain**:
-
-- **RECALL** — load the brain slice for the domains the intent touches: conventions,
-  contracts, flows, and **non-exemplars** (don't copy the grandfathered demo — the audit's
-  exact lesson). The plan starts from known ground, not a cold read. *This is the 100×.*
-- **BLAST RADIUS** — name the domains/nodes the change touches (from the brain's map), so risk
-  is known up front and `build` can recall/nudge per task.
-- **NUDGE** — query the improve ledger for open improvements in that blast radius; surface the
-  **top-leverage** ones as optional *"while-you're-here"* tasks (leverage-ranked, dismissible).
-- **LEVERAGE (orchestrate, don't bury)** — match the intent against available capabilities
-  (committed skills/agents/MCP **+** the dev's personal ones, discovered live) and recommend the
-  best-fit to the host: *"there's a `tdd-workflow` skill for this — use it."* Never plan to
-  hand-roll what a capability already does; flag config that would help. Recommend; the host
-  orchestrates (a hook can't auto-invoke).
-
-## Procedure (draft)
-1. **Recall** the brain slice for the intent's domains (notes + contracts + non-exemplars).
-2. **Decompose** ADR: decision + rationale + alternatives + tradeoffs + risk surface + non-goals.
-3. **Tasks** — each bound to domains/nodes (so `build` can recall + nudge per task) with a done-check.
-4. **Ledger nudge** — surface open improvements in the blast radius as optional, leverage-ranked tasks.
-4b. **Leverage-match** — recommend the existing skills/tools/MCP that fit the tasks; flag tooling-fit
-    improvements. Don't plan to reinvent a present capability.
-5. **Approval gate** (ExitPlanMode). Materialize `.rafa/plans/<id>.md` + `active.md → {plan, task:1}`.
-
-## Deferred / open
-- Capture-back of plan-time decisions → brain (prism-validated) — needs the capture engine (hooks).
-- Pivot detection (conversation-as-steering; mark superseded, the path is data).
-- Plan lifecycle + tiering (cap, archive→remote, restore) — designed in `.arohi/architecture.md`.

package/blueprint/.rafa/contract.md

@@ -1,303 +0,0 @@
-# rafa brain contract — v1
-
-The strict protocol every brain file obeys, and the `manifest.json` the platform
-ingests. This is the **single source of truth** shared by the writers (atlas, bloom,
-prism) and the reader (the platform ingest). If a file violates this, the compile
-step **fails loudly** and the authoring agent must correct it — the platform never
-guesses, never assumes a value.
-
-Pipeline:
-
-```
-agents write .md (frontmatter per this contract)
-  → rafa compile   (deterministic: parse frontmatter, VALIDATE, fail loudly)
-       ├ FAIL → structured error (file · field · rule) → author agent fixes → retry
-       └ PASS → emit manifest.json
-  → git push → webhook → INGEST = JSON.parse(manifest) + shape-check → Convex
-  → query APIs (per repo+branch) → platform renders
-```
-
-Two enforcement points: **compile-time** (structure — this contract) and **prism**
-(semantics — truth of the content). Structure is validated *before* semantics.
-
----
-
-## File-type registry — every `.rafa` file has a declared class
-
-No consumer ever guesses. **Every** file type is classified here; a `structured` type has
-a schema (parse it), a `verbatim` type is prose (display it, never parse for data), a
-`generated` type is machine-written by a named tool. If a file matching a `structured` path
-doesn't validate, compile fails.
-
-| Type | Path glob | Class | Schema | Author |
-|---|---|---|---|---|
-| rule | `brain/rules/*.md` | **structured** | §2 | atlas |
-| playbook | `brain/playbooks/*.md` | **structured** | §2 | atlas |
-| health | `brain/checklist.md` | **structured** | §4 | prism |
-| coverage | `brain/coverage.md` | **structured** | §6 | atlas |
-| improvement | `improve/improvements/*.md` | **structured** | §3 | bloom |
-| ledger | `improve/ledger.md` | **structured** | §5 | bloom |
-| plan | `plans/**/*.md` | **structured** | §7 *(wired: Slice 4)* | plan/build |
-| log | `brain/log.md` | **verbatim** | — (prose trail) | conductor |
-| citation-check | `**/citation-check.md` | **generated** | — (by `verify-citations`) | tool |
-| active pointer | `active.md` | **generated** | — (`# <plan-id>` or "No active plan") | conductor |
-| blueprint | `capabilities/*`, `bin/*`, `contract.md` | **verbatim** | — (shipped SOPs/tools) | rafa |
-
-`structured` types are compiled into `manifest.json` (§1) — that JSON is the ONLY thing the
-platform ingests. `verbatim`/`generated` files are shown as-is in the file browser (fetched
-lazily), never parsed. A file under a `structured` path that isn't in this table → compile
-error (no rogue unschema'd data files).
-
----
-
-## 0. Global rules
-
-- **Frontmatter is the only machine-read surface.** The markdown **body is prose**
-  and is NEVER parsed for data. Every value the platform shows comes from frontmatter
-  (via the compiled manifest), or from the body rendered *verbatim* (never scraped).
-- **`schemaVersion` is required** on every file and in the manifest. Unknown version
-  → ingest reports an error, does not guess.
-- **`id` is required and stable.** It MUST equal the filename stem (`foo.md` → `foo`).
-  Renames are safe because rows are keyed by `id`, not path.
-- **Required fields are required.** Missing/empty required field = compile failure.
-  The validator **never fills a default for a required field** — that would be
-  assuming. Optional fields have documented defaults.
-- **Enums are closed.** A value outside the enum = compile failure (not coerced).
-
-### Frontmatter grammar (strict subset — the only shapes allowed)
-
-Frontmatter is a leading `---` … `---` block. Within it, only these forms are legal;
-anything else is a compile error:
-
-```yaml
-key: scalar                       # string | number | true | false
-key: "quoted string"              # quotes stripped
-key: [a, b, c]                    # flow list of scalars
-key: { a: x, b: y }               # flow map of scalars
-key:                              # block list …
-  - item
-  - item
-```
-
-No nested block maps, no multiline scalars, no anchors. Deterministic to parse.
-
-### cites DSL
-
-Each cite is one string: `` `<path>:<line> :: <token>` ``
-
-- split on the **first** ` :: ` → (`left`, `token`)
-- in `left`, split on the **last** `:` → (`path`, `line`)
-- `line` is digits (`"42"`) or a range (`"14-18"`)
-
-Compile parses each into `{ file, line, token }`. A cite that doesn't match → error.
-
----
-
-## 1. manifest.json — the ingestion contract
-
-Machine-generated by `rafa compile`, committed to the brain repo, read by ingest as
-JSON. This is the exact shape the platform binds to.
-
-```jsonc
-{
-  "schemaVersion": 1,
-  "generatedAt": "2026-07-03T10:00:00Z",   // ISO-8601, stamped by compile
-  "repo": "owner/repo",                     // CODE repo full_name (identity)
-  "branch": "main",                         // code branch this brain reflects
-  "codeSha": "abc123…",                     // code commit the brain was built for
-
-  "health": {                               // from brain/checklist.md — or null
-    "verdict": "PASS",                      // "PASS" | "ITERATE"
-    "score": 95,                            // 0–100
-    "gates": { "fidelity": "pass", "coverage": "pass" },
-    "counts": { "blockers": 0, "majors": 0, "minors": 2 }
-  },
-
-  "ledger": {                               // from improve/ledger.md — or null
-    "open": 7,
-    "debtScore": 13,
-    "byPriority": { "P0": 0, "P1": 1, "P2": 3, "P3": 3 }
-  },
-
-  "coverage": {                             // from brain/coverage.md — or null
-    "domains": [                            // one row per domain, its scan status
-      { "domain": "design-system", "status": "mapped" },
-      { "domain": "external-integrations", "status": "thin" }
-    ]
-  },
-
-  "notes": [
-    {
-      "id": "agent-name-contract",
-      "kind": "rule",                       // "rule" | "playbook" (from directory)
-      "type": "contract",                   // contract | convention | flow | how-to
-      "domain": "web-agent-bridge",
-      "title": "…",
-      "summary": "…",
-      "links": ["other-note-id"],           // [] if none
-      "failure": "silent",                  // "silent" | "loud" | omitted
-      "cites": [{ "file": "src/x.tsx", "line": "42", "token": "research_agent" }],
-      "path": "brain/rules/agent-name-contract.md"  // prose body (lazy fetch)
-    }
-  ],
-
-  "improvements": [
-    {
-      "id": "dead-model-options-google-crewai",
-      "priority": "P1",                     // P0 | P1 | P2 | P3
-      "lens": "product",                    // security|correctness|performance|architecture|product|ops
-      "status": "open",                     // open | backlog | fixed | wontfix
-      "title": "…",
-      "summary": "…",
-      "fix": "…",
-      "leverage": { "impact": "high", "effort": "low" },   // impact/effort ∈ low|medium|high
-      "blastRadius": ["web-agent-bridge"],  // [] if none
-      "cites": [{ "file": "…", "line": "25", "token": "…" }],
-      "path": "improve/improvements/dead-model-options-google-crewai.md"
-    }
-  ],
-
-  "plans": []                               // v1: may be empty; shape in §6
-}
-```
-
-Ingest is `JSON.parse` + a shape-check against this schema. Any mismatch (missing
-key, wrong enum, wrong type, unknown `schemaVersion`) → a **surfaced ingest error**
-on the platform, never a guessed value.
-
----
-
-## 2. Note files — `brain/rules/*.md`, `brain/playbooks/*.md`
-
-`kind` is derived from the directory (`rules/` → `rule`, `playbooks/` → `playbook`).
-
-```yaml
----
-schemaVersion: 1
-id: agent-name-contract          # required · == filename stem
-type: contract                   # required · contract | convention | flow | how-to
-domain: web-agent-bridge         # required · non-empty
-title: The agent name is a cross-process contract   # required
-summary: Only "research_agent" is fully wired end to end   # required
-links: [copilotkit-runtime-route-convention]   # optional · default []
-failure: silent                  # optional · silent | loud
-cites:                           # required · ≥ 1
-  - src/lib/model-selector-provider.tsx:42 :: research_agent
-  - agents/python/main.py:20 :: research_agent
----
-（prose body — rendered verbatim, never parsed）
-```
-
----
-
-## 3. Improvement files — `improve/improvements/*.md`
-
-```yaml
----
-schemaVersion: 1
-id: dead-model-options-google-crewai   # required · == filename stem
-priority: P1                     # required · P0 | P1 | P2 | P3
-lens: product                    # required · security|correctness|performance|architecture|product|ops
-status: open                     # required · open | backlog | fixed | wontfix
-title: Two of the four model options are dead and fail silently   # required
-summary: google_genai and crewai route to unwired agents   # required
-fix: Wire both agents in main.py, or remove them from the picker   # required
-leverage: { impact: high, effort: low }   # required · impact/effort ∈ low|medium|high
-blast_radius: [web-agent-bridge, external-integrations]   # optional · default []
-cites:                           # required · ≥ 1
-  - src/components/ModelSelector.tsx:25 :: google_genai
-found: 2026-07-02               # optional · ISO date
----
-（prose body）
-```
-
-Note: `title`, `summary`, `fix` are now **required frontmatter** — previously scraped
-from prose. That scraping is gone; these are authored values.
-
----
-
-## 4. Health file — `brain/checklist.md`
-
-```yaml
----
-schemaVersion: 1
-verdict: PASS                    # required · PASS | ITERATE
-score: 95                        # required · 0–100
-gates: { fidelity: pass, coverage: pass }   # required · each pass | fail
-counts: { blockers: 0, majors: 0, minors: 2 }   # required · non-negative ints
----
-（prism report body）
-```
-
----
-
-## 5. Ledger file — `improve/ledger.md`
-
-The debt figure is **authored in frontmatter** (bloom's number), not parsed from a
-table. `open`/`by_priority` are cross-checked against the improvement rows at ingest.
-Flat keys only — no nesting (compile maps `debt_score`→`debtScore`, `by_priority`→`byPriority`).
-
-```yaml
----
-schemaVersion: 1
-open: 7
-debt_score: 13
-by_priority: { P0: 0, P1: 1, P2: 3, P3: 3 }
----
-（human-readable trend/tables in the body）
-```
-
----
-
-## 6. Coverage file — `brain/coverage.md`
-
-The scan's breadth report. `domains` is a **flow map** of `domain: status`, one entry per
-domain found (compile emits it as `[{ domain, status }]` in the manifest). Status enum:
-`mapped | thin | stubbed | empty`. The body holds the human per-criterion PASS/FAIL narrative.
-
-```yaml
----
-schemaVersion: 1
-domains: { design-system: mapped, components: mapped, api: thin, external-integrations: empty }
----
-（per-criterion PASS/FAIL narrative in the body）
-```
-
----
-
-## 7. Plan files — `plans/**/*.md` (Slice 4)
-
-Each child owns exactly one file (so merges never conflict; parent progress is
-derived by counting).
-
-```yaml
----
-schemaVersion: 1
-id: c1-schema                    # required · == filename stem
-plan: multitenant                # required · the parent plan id
-parent: null                     # required · parent plan id, or null for the root
-kind: parent | child             # required
-title: …                         # required
-status: todo | in-progress | done | blocked   # required (child); parent may omit
-branch: feat/mt-c1               # optional · the branch this executes on
-baseSha: abc123                  # optional · commit it was cut from
----
-```
-
-Parent progress is `count(children where status == done) / count(children)` —
-derived, never stored.
-
----
-
-## 8. Versioning & the validate-and-correct loop
-
-- **`schemaVersion`** bumps when this contract changes incompatibly. Ingest refuses
-  an unknown version (surfaced error) rather than mis-reading it.
-- **Validate-and-correct:** `rafa compile` validates every file. On failure it emits
-  a structured error — `path · field · rule` — to the **authoring agent** (atlas for
-  notes, bloom for improvements/ledger, prism for checklist). The agent edits the
-  file and compile re-runs. Bounded retries; if it can't converge, a **hard failure**
-  blocks the push (better than a silently-wrong brain).
-- The validator **reports, never auto-fills** a required value.
-
-This contract is the thing to test against.