prismatica 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prismatica authors
+
+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,403 @@
+# ◇ Prismatica
+
+**A safety layer for software that AI agents write for you.**
+
+The agent builds. Prismatica inspects. Nothing ships until the intent, the
+proof, and the owner agree.
+
+## The problem it solves
+
+AI agents write code fast — and confidently tell you it works. Sometimes it
+does. Prismatica exists for the times it doesn't: it never asks the agent, it
+never reads the chat, and it never calls an AI itself. It trusts exactly two
+things: **what Git says changed**, and **what your tests prove**.
+
+Every fact it knows is a plain Markdown or JSON file inside your repo, under
+`.prismatica/`. You can read every record yourself. Delete the tool and the
+records still make sense. No hidden database, no lock-in.
+
+## How it works, in one paragraph
+
+You **frame** a change: one sentence, the files it may touch, and the checks
+that prove it — that's a _contract_, tied to a GitHub issue. The agent builds
+in its own _lane_ (an isolated working copy) with a guard that blocks it from
+straying outside the contract. **Checks** run your own tools — typecheck,
+lint, tests, build, browser journeys, secret scan — plus Prismatica's own: did
+the diff stay in scope, does every acceptance check trace to a passing test?
+A **fresh session** — a new one that did not build the diff, and the same
+provider is fine — **reviews** the exact diff, and the review is **sealed**
+to that diff's fingerprint with an explicit verdict — change one line
+afterwards and the seal breaks. Above `light` tier, a `request_changes` verdict
+blocks the merge outright rather than merely being noted. The reviewer ends on `SAFE TO
+SEAL` or `DO NOT SEAL`; you record which, because nothing reads that session's
+output. Risky changes need your
+**signed decision** (a real cryptographic signature).
+Then the **gate** re-checks everything on the pull request and blocks the
+merge until it all holds — including that the tier you declared actually
+covers what the changed files touch. `prismatica merge` is the exact-SHA,
+owner-guarded step that follows: it re-verifies the PR and its gate result
+for this precise head before merging (never a silent squash or rebase), and
+`prismatica close` removes the lane only once GitHub confirms that exact
+head merged. After merge, close, deploy, and one live smoke check, the
+change gets its **passport**: what shipped, its proof, and a tested way back.
+`ship --verify` proves that passport against the ONE commit that merged — its
+exact head, the exact diff your review or check covered, and the gate's own
+recorded result on it — never against whatever main happens to be today, which
+is a moving target that made every merged change unverifiable the moment
+anything else shipped.
+
+Not every change should finish. `prismatica abandon <id> --reason "..."` closes
+the pull request, closes the issue, commits the contract, plan and brief to the
+change's own branch, and removes the lane. Nothing is deleted: the local
+branch is retained and any existing remote branch is untouched, and it prints
+the command that brings the lane back.
+
+`prismatica merge` is exact-head and owner-guarded — but it can only guard the
+route it runs on. Unless GitHub's own branch protection requires the
+`prismatica-gate` check, merging in the GitHub browser UI or pushing straight
+to main still bypasses it. `prismatica doctor` tells you which of those you
+actually have, and never overstates it: when GitHub cannot answer — no `gh`,
+signed out, an outage, or a plan that does not offer required status checks at
+all — it reports "unknown" or "unavailable", never "unprotected", and leaves
+those rows out of the adoption score instead of counting them against you.
+
+## Quick start
+
+Install the `prismatica` command from npm, naming the exact version:
+
+```bash
+npm install -g prismatica@0.2.0          # or: npx --yes prismatica@0.2.0 doctor
+```
+
+Always name the version. Bare `prismatica` resolves to whatever the registry
+serves that minute, and the gate is the one choke point — which reader runs it
+should be a decision you make in a reviewable diff, never one a registry makes
+for you between two pushes. Upgrading is the same command with a different
+number; nothing goes looking for a "latest" on your behalf.
+
+> `npm install && npm run build && npm link` is **not** how you adopt an app.
+> That is the self-host exception, for working on Prismatica's own source
+> checkout — see [Working on Prismatica itself](#working-on-prismatica-itself).
+
+Adopt an app:
+
+```bash
+cd ~/your-app                    # any git repo, new or existing
+prismatica init
+```
+
+`init` is safe to re-run and never overwrites your records. It detects the
+tooling you already have, enables only checks that can actually run, and prints
+what's **Enforced**, **Checked**, or **Missing** — with the exact fix for every
+gap. Old code is never judged; Prismatica governs changes from now on.
+
+The gate workflow it writes pins one exact published version and needs no
+Prismatica dependency in your app:
+
+```yaml
+- name: prismatica gate
+  run: npx --yes prismatica@0.2.0 gate
+```
+
+The `npm ci` step above it installs **your** checks — your typechecker, linter,
+test runner, build — and is skipped when the repository has no npm lock file at
+its root, so a Python or Go repo adopts exactly as cleanly as a Node one.
+
+**Adopted before 0.2.0?** Your workflow says `npx prismatica gate` with no
+version, so CI runs whatever the registry resolves that minute. `prismatica
+doctor` reports it under **Runtime**, beside the version you are running
+locally, so skew is visible rather than silent. The repair is one line in
+`.github/workflows/prismatica-gate.yml` — change `run: npx prismatica gate` to
+`run: npx --yes prismatica@0.2.0 gate`. `init` will never do it for you: it
+preserves an existing workflow byte-for-byte by design, which is precisely why
+the pin is yours to move deliberately.
+
+Compatibility runs one way. A newer Prismatica reads every record an older
+released one wrote — new persisted fields are optional, and a frozen pre-0.2
+fixture of every record kind proves it on every test run. The reverse is not
+promised, so move an app's CI pin **before**, or in the same change as, the
+first time a newer Prismatica writes a record there.
+
+Then start a change the short way — which begins in your coding agent, not in
+your terminal:
+
+1. Open the agent you are already using and activate **Prismatica Start**.
+2. Describe what you need, and settle the plan with it in conversation.
+3. It reads the repository, writes the plan, and hands you one command:
+
+```bash
+prismatica start --import ~/plan.json
+```
+
+4. You run that in your own terminal and confirm.
+
+You never type your description into a command. You and the agent agree the
+wording between you, and the plan carries it back — along with who will build
+it — so the contract, the issue and the reviewer all quote one agreed sentence
+instead of a one-liner retyped twice.
+
+Under the hood the skill runs `prismatica context start` for itself: a
+read-only snapshot of the repo written as **one** json file to a private
+temporary directory — outside your repository, and at no path a caller can
+choose — containing that snapshot, plain instructions, and the exact schema the
+answer must match. You do not normally run it, though you can (see `prismatica
+context --help`), which is how an agent with no Prismatica plugin still works.
+**Prismatica does not run the agent.** There is
+no `--agent` flag, no adapter to keep working and no fallback path, because
+there is no transport to fail: any agent that can read a file and write JSON
+can answer.
+
+The import revalidates the plan strictly against a **fresh** reading of your
+repo — nothing the document says is taken as fact about your code — shows you
+your own request first, then the whole plan **and the exact GitHub issue it
+will file**, and asks once, defaulting to No. Nothing at all is created until
+you say yes: no issue, no branch, no lane, no record. There is no `--yes`.
+After that it creates the issue, frames the lane, writes your approved intent
+and Delta (or Planned Flow) into it, and generates the builder brief.
+
+If something fails after the lane exists, `--resume <id>` finishes it. It is
+the same path, not a shortcut: the same fresh reading, the same full preview
+and the same default-No question. Only then does it verify each record already
+in that live lane against the plan and write what is missing — never
+overwriting one that differs.
+
+`--model` and `--effort` still exist on `open` and `review`, which do start a
+real session. Before either changes the lane, Prismatica asks the installed
+provider to print its own usage and requires that usage to **name the value you
+chose**; a value it lists nowhere is refused rather than passed through on
+trust. Prismatica hard-codes no model names and never calls a model to check
+one, so in practice `--effort` on Claude Code is the selection it can confirm —
+run a specific model in the session you start yourself.
+
+Prismatica never calls an LLM API, holds no API key, and reads no transcript.
+
+Then learn the loop from the built-in guide — it's the same content as
+[docs/USER_GUIDE.md](docs/USER_GUIDE.md):
+
+The guide is organised around what you are trying to do, not around command
+names:
+
+```bash
+prismatica guide                     # start here — scenarios, then reference
+prismatica guide startbug            # something is broken; you don't know where
+prismatica guide understandapp       # understand an app you already have
+prismatica guide changeflow          # change what an existing Flow does
+prismatica guide newflow             # define and approve a new Planned Flow
+prismatica guide starttechnical      # a refactor, with no product Flow invented
+prismatica guide rediscover          # the app changed; bring the map up to date
+prismatica guide approvebatch        # review and approve a batch safely
+prismatica guide handoff             # how Prismatica hands work to your agent
+prismatica guide roles               # Planner vs Builder vs Fresh Reviewer
+prismatica guide manualframe         # frame by hand, every flag spelled out
+prismatica guide proof               # inspect the proof, and the code behind it
+prismatica guide mergepath           # the owner-guarded merge path
+prismatica guide verifyclose         # verify the live deploy, then close
+prismatica guide terms               # every bit of jargon in one sentence each
+```
+
+## The commands
+
+| Command           | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init`            | Adopt a repo: records skeleton, gate workflow, capability table                                                                                                                                                                                                                                                                                                                                                                                                |
+| `next`            | The one command when you don't know what to run — reads the record, prints exactly one next step                                                                                                                                                                                                                                                                                                                                                               |
+| `start`           | **The usual way in.** Import the plan your agent wrote (it runs `context start` for itself); see your request, the whole plan and the exact issue text in full; confirm once; then issue + lane + intent + brief. Takes no positional request and no `--builder` — both are in the plan. `--resume <id>` finishes a run that failed after framing, through the same preview and confirmation                                                                   |
+| `frame`           | Start a change by hand: contract + issue link + isolated lane + scope guard                                                                                                                                                                                                                                                                                                                                                                                    |
+| `pack` / `open`   | Build the agent's scoped brief; hand a known agent one short pointer at it in the lane, or `--copy` the whole brief                                                                                                                                                                                                                                                                                                                                            |
+| `amend`           | Change scope mid-flight, with an audited reason — never re-baselines                                                                                                                                                                                                                                                                                                                                                                                           |
+| `check`           | Run all proof checks — the same engine the gate runs; refuses while proof inputs are uncommitted, and records the commit it proved                                                                                                                                                                                                                                                                                                                             |
+| `ready`           | Append or inspect strict Get Change Ready run bookkeeping in `.prismatica/ready.jsonl`. `ready record --import` starts no agent and decides no verdict; `ready status` reconstructs the durable owner card without changing the lane. `ready record --import … --new-run` is the owner's alone: it opens a second bounded run, with fresh attempt budgets, after the current one has stopped. Ready events are not Check or gate evidence                                                                                                                                                                                    |
+| `review` / `seal` | Fresh-eyes review, cryptographically bound to the exact diff, with a verdict the gate enforces; `review --agent claude\|codex` checks the selected provider's own usage in a disposable process before drafting, then starts a read-only reviewer session. After a committed `request_changes`, lifecycle-only review/ledger/Check-evidence output cannot unlock a new brief; substantive code or proposal rework can. `--reconsider` is the owner's TTY-only exception |
+| `accept`          | The owner's Ed25519-signed decision (required for heavy changes)                                                                                                                                                                                                                                                                                                                                                                                               |
+| `ship`            | Pre-flight the gate, push the exact lane HEAD, open/reuse the PR; later `--verify` writes the passport                                                                                                                                                                                                                                                                                                                                                         |
+| `gate`            | The CI choke point — non-zero exit blocks the merge; makes zero writes, pass or fail                                                                                                                                                                                                                                                                                                                                                                           |
+| `merge`           | Exact-SHA, owner-guarded merge — requires a passing gate for this exact head; `--merge` only                                                                                                                                                                                                                                                                                                                                                                   |
+| `close`           | Remove a merged lane only at its exact head, preserving uncommitted and unproven-disposable ignored local data; always prints the main fast-forward                                                                                                                                                                                                                                                                                                            |
+| `abandon`         | Stop a change for good: close its PR and issue, archive its records on its own retained branch, remove the lane. Deletes no branch; prints how to restore it                                                                                                                                                                                                                                                                                                   |
+| `doctor`          | Repo health, an honest gate-assurance level, an adoption score over what could be measured, and the highest-value next fix                                                                                                                                                                                                                                                                                                                                     |
+| `stats`           | Median rework loops, cost per accepted change, escaped bugs                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `view`            | The local board: Needs You · Work · Apps · Releases · Understand                                                                                                                                                                                                                                                                                                                                                                                               |
+| `context`         | Machine-facing read-only context for the Start and Understand skills, which normally run it themselves. Writes nothing to your repo; available by hand for an agent with no plugin                                                                                                                                                                                                                                                                             |
+| `discover`        | Import an agent's Flow/Rule proposals for the whole app, onto main; first mapping and reconciliation are one command                                                                                                                                                                                                                                                                                                                                           |
+| `propose`         | Import the same document into the change lane you are building in, so the proposal rides that change's pull request                                                                                                                                                                                                                                                                                                                                            |
+| `flow` / `rules`  | List, show, approve, dismiss, or verify Flows and app rules; `approve --all` reviews a whole batch with one confirmation                                                                                                                                                                                                                                                                                                                                       |
+| `flow report`     | Your honest per-Flow account of what a change touched. `--auto` fills in what the diff proves and prints the exact command for every Flow only you can answer                                                                                                                                                                                                                                                                                                  |
+| `delta`           | Say what should change about a Flow, in your own words; `frame --from-delta` turns it into a change                                                                                                                                                                                                                                                                                                                                                            |
+| `forget`          | Remove a repo from the board (records untouched)                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `guide`           | The manual, built in                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+
+### Understand — Flows, Rules, and Deltas
+
+Alongside change governance, Prismatica maintains a comprehension layer: a
+**Flow** is one complete route through your app (goal, steps, ending, rules),
+kept as a hash-guarded record under `.prismatica/flows/`.
+Ask your agent for **Prismatica Understand** and it drafts them from the real
+code — reading the repository through `prismatica context discover`, which it
+runs for itself — then hands you `prismatica discover --import` to materialise
+the answer; you review and approve in the terminal or in
+the board's **Understand** view. Agents propose changes to a Flow's truth
+_and_ its mechanics (which files it lives in) — never edit the canonical
+record directly — and the owner approves. A **Delta** (`prismatica delta new`)
+is the fast on-ramp for saying "this should work differently" without writing
+a contract by hand; `frame --from-delta` turns an approved one into an
+ordinary governed change.
+
+Reading a Flow is meant to take seconds. `prismatica flow list` gives you every
+flow in reading order with a short title and a one-sentence outcome, and stays
+quiet unless something needs you — a stale step, an unverified flow, a pending
+update, an open change that touches it. `prismatica flow show <id>` tells the
+story: where it starts and ends, what happens in order, and how solid the
+evidence is. Every rule and guardrail is shown as its complete text, wrapped,
+with no flag needed — a rule cut to a short label ("In governed mode…") is true
+and useless. Everything genuinely heavier is one flag away and composes freely:
+`--details` (the assumptions each step relies on), `--proof` (how each step was
+verified), `--code` (files, routes, tests), `--json` (the same view, stable, for
+scripts). `prismatica rules list` does the same for app-wide guardrails, where
+`--details` adds which flows cite each one. A Flow may optionally carry a short
+title and a journey for display only — it sits outside the truth block, so it is not part
+of the fingerprint and nothing is ever backfilled or re-signed for you. This
+layer works the same with or without the merge gate (`init
+--map-only` for comprehension alone, no governance).
+
+## The board
+
+`prismatica view` starts a local page (your machine only) across every adopted
+repo. **Needs You** lists everything waiting on your decision, each in one
+plain sentence — approving writes a signed record into the repo, and the gate
+reads the record, never the board. **Work** shows every in-flight change in
+its lifecycle column; cards move only when records change. **Apps** shows per
+repo health and red flags. **Releases** keeps three states apart rather than
+blurring them: a verified release (a passport exists), one merged and awaiting
+live verification (no passport yet, still eligible for `ship --verify`), and a
+legacy one created before this repo started tracking release proof at all —
+never queued, and never called shipped or verified. Below them are the plans
+you approved — an Intent lists the outcomes it set out to achieve, and says a
+change shipped only when a passport for it exists.
+
+The board follows your system light/dark theme, with a manual toggle
+(Auto · Light · Dark) and an optional 10-second auto-refresh. Each **Needs You**
+card offers **Approve and sign** or **Request changes** (both write a signed
+decision); each **Apps** row has a **Remove** button that forgets the repo's
+board pointer without touching the repo or its records. To empty the board from
+the terminal instead: `prismatica forget --all`.
+
+## For Claude Code users
+
+This repo is also a **plugin marketplace**. Install the plugin once and it works
+in every app you build:
+
+```bash
+claude plugin marketplace add /path/to/prismatica-cli
+claude plugin install prismatica@prismatica
+```
+
+It adds two skills — scoped Contract Work and the Get Change Ready controller —
+plus
+`/prismatica:start`, `/prismatica:understand`, `/prismatica:ready`,
+`/prismatica:status` and `/prismatica:review` commands. These are the six
+capabilities: Start, Understand, Contract Work, Get Change Ready, Status and
+Review. For "what now", run `prismatica next` directly.
+See [claude-plugin/README.md](claude-plugin/README.md).
+
+**Get Change Ready** is the one that saves the most typing. Once a change has a
+contract and a lane, it drives the whole loop for you: build, `check` (at most
+three attempts), then — above `light` tier — a genuinely fresh read-only review
+(at most three). It opens one durable run boundary in the append-only
+`.prismatica/ready.jsonl`, then records only that run's Check and review
+attempts, exact Check evidence and checked commit, resolved provider/model/effort
+plan, verbatim findings, stop state and next owner action. `prismatica ready
+status` reconstructs the same owner card after the original controller has
+gone. Checks before the boundary remain pre-run history and consume none of the
+new budget; restarting reuses the run and cannot reset either limit.
+
+When a run stops — `check_budget_exhausted`, `review_budget_exhausted`,
+`blocked` or `awaiting_owner` — deciding to try again is yours:
+`prismatica ready record <id> --import <start.json> --new-run` appends a second
+boundary bound to today's HEAD, with a new run id and its own three Check and
+three review attempts. It is refused while the run is still running, refused
+when no run exists, and refused for an agent, so a controller can never grant
+itself a fourth attempt. Every earlier run and event is kept exactly as
+recorded; `ready status` reconstructs the latest run and lists the earlier ones
+as history. A new run is also the one place a rejected provider, model or
+effort selection can be corrected — within a run the plan is fixed.
+
+Every attempt is a new, non-resumed session given only the contract, pack, Git
+state and relevant failure or findings. You choose the provider, model and
+effort for the builder and reviewer independently, or use the recorded builder,
+the same provider for a fresh reviewer and provider defaults. When you explicitly
+select a model or effort, before `open` or `review` writes the lane Prismatica
+runs that provider once in an empty OS temporary directory to print its own
+usage, and requires that usage to document the flags your selection needs and
+name the value you chose among the accepted values it enumerates.
+Provider defaults run no probe. No prompt is ever sent, no model is ever called
+and no model catalogue is kept — so a provider that will not run, that has no
+such flag, or that does not name that value, stops the command before the real
+lane mutation. In practice, model names are refused for both providers and
+Codex effort is refused; Claude Code effort is the one explicit selection the
+probe can confirm. Your sign-in remains the provider's answer at launch. It
+stops at your decisions —
+`SAFE TO SEAL`, any scope change, an
+ambiguous verdict, any provider failure — and it may run exactly one owner-only
+command: `seal --request-changes`. The mirror of that exception is
+`ready record --new-run`: ordinary run bookkeeping is the controller's, and the
+one form that grants fresh attempt budgets is refused for an agent by the same
+guard. It never advances a change; Get Change Ready
+stops before review at `light`, and above `light` the rejection blocks the gate
+and `accept` while `next` returns it to a builder. Approving seals, `accept`,
+`ship`, `merge` and the rest stay yours.
+
+After a rejection, the controller first imports the verdict and findings from a
+strict JSON file, then records the blocking seal, inspects dirty paths, stages
+only the expected review, ledger, evidence and forward-stage contract outputs,
+and commits them with an ordinary subject. Findings never enter argv, shell
+interpolation, a heredoc or a commit message. Ready events live in their own
+append-only file, `.prismatica/ready.jsonl`, so `.prismatica/ledger.jsonl` holds
+Check and gate rows and nothing else — a reader that has never heard of Get
+Change Ready still parses every line of it. Ready events remain bookkeeping:
+Check, gate, stats and passports ignore them. The scope backstop, Check, gate,
+patch-id seal and your signature remain the assurance path.
+
+**None of these six is Claude-only in substance.** They are disciplines — read
+the contract, stay in scope, prove it, review it fresh, stop at the owner — and
+the CLI they drive is the same for every agent. This directory is a Claude Code
+_package_ of them because that is the plugin system Prismatica currently
+packages for. Claude and Codex use the known `open <agent>` and `review --agent`
+launch paths; another agent uses `open --copy` and `review --copy --reviewer`
+rather than receiving guessed safety flags. Every path is judged by exactly the
+same gate. Prismatica has no favourite agent and no command that asks which one
+you used.
+
+## Principles (in priority order)
+
+1. The agent proposes; deterministic code decides. Never the reverse.
+2. Trust Git and test results, never the agent's chat. No LLM API calls, ever.
+3. One choke point: nothing merges without passing the gate.
+4. Write the durable record only after a step succeeds.
+5. Archive over delete: rollback is a new record, never an erased one.
+6. Default to "not ready": gates fail closed.
+7. All records are plain Markdown/JSON in the repo. No hidden database. No lock-in.
+
+## Working on Prismatica itself
+
+```bash
+npm run verify     # typecheck + lint + tests + build — all must pass
+npm run dev -- …   # run the CLI from source
+```
+
+To put a source checkout on your PATH instead of the published package:
+
+```bash
+npm install && npm run build     # build the CLI
+npm link                         # put `prismatica` on your PATH
+```
+
+That is the **self-host exception** and it applies to this repository only.
+Adopted apps install `prismatica@<version>` from the registry and their CI
+fetches one exact published version; `npm link`, `npm run build` and
+`node dist/cli.js` are never part of an ordinary application's workflow. After
+editing Prismatica's own source, re-run `npm run build` — `prismatica doctor`
+names which checkout holds the build that is actually running.
+
+See [CLAUDE.md](CLAUDE.md) for working rules, [DECISIONS.md](DECISIONS.md) for
+why things are the way they are, and [docs/CHECKPOINT.md](docs/CHECKPOINT.md)
+for the build state.