prismatica 0.2.0

package/dist/planning/materialise.js

@@ -0,0 +1,210 @@
+/**
+ * Turning one imported proposals document into Flow/Rule proposal records.
+ *
+ * Shared by `discover --import` (destination: main) and `propose --import`
+ * (destination: the active change lane). Two properties earn this its own
+ * module:
+ *
+ *  1. **`home` is a parameter, never inferred.** The one thing that must not be
+ *     guessed here is WHERE the records land. A materialiser that resolved its
+ *     own destination would put the map of the app on a change branch, or a
+ *     change's own proposals on main, depending on which directory the command
+ *     happened to be run from.
+ *  2. **Plan, then write.** `planProposals` decides the whole batch — path
+ *     safety, what exists, what conflicts — and returns either problems or a
+ *     complete plan. `applyPlan` only writes. Nothing is written while anything
+ *     is still undecided, so a batch with one bad touchpoint leaves the repo
+ *     exactly as it was rather than half-applied.
+ *
+ * A partial write can still happen: the filesystem can fail on item three of
+ * five, and no amount of pre-checking prevents that. What makes the retry safe
+ * is that RE-RUNNING the same import is a no-op over what already landed —
+ * an existing proposal that is semantically identical to the one we would write
+ * is reported as already present and left untouched, keeping its original
+ * timestamp. An existing proposal that DIFFERS is a conflict and fails the
+ * whole batch closed: it is either a review the owner has in progress or a
+ * different answer being imported over this one, and overwriting either
+ * silently is the one outcome nobody could recover from.
+ *
+ * That is deliberately not a transaction framework. It is the same idempotence
+ * every other record write in Prismatica has — write in place, compare before
+ * replacing — applied to a batch.
+ */
+import { renderFlowProposalBody, renderRuleProposalBody } from '../atlas/render.js';
+import { flowExists, flowProposalExists, readFlowProposal, readRuleProposal, ruleProposalExists, writeFlowProposal, writeRuleProposal, } from '../atlas/store.js';
+import { FlowProposalSchema, RuleProposalSchema } from '../records/types.js';
+import { stableStringify } from '../records/store.js';
+import { validateRelativeGlob } from './validate.js';
+/**
+ * Two records are "the same" when everything the owner would read is the same.
+ * The listed keys are blanked before comparing — they are deterministic stamps
+ * a second run cannot reproduce (`createdAt`, or a Delta's id, which embeds the
+ * instant it was made), and re-stamping one would be the only difference a byte
+ * comparison could see.
+ *
+ * The JSON round-trip is load-bearing, not tidiness. One side of this
+ * comparison is a record built in memory and the other has been through YAML
+ * and back, and an OPTIONAL field the answer omitted (`presentation`) is the
+ * difference between a key present with the value `undefined` and no key at
+ * all. `stableStringify` reports those as different, so without this every
+ * retry saw a conflict and refused to finish work it had started itself.
+ *
+ * Exported because `start --resume` asks the identical question about the
+ * Intent it is about to write. One implementation of "is this the same
+ * record", not two that drift.
+ */
+export function sameRecordIgnoring(existing, incoming, ignoredKeys) {
+    const blanks = Object.fromEntries(ignoredKeys.map((key) => [key, '']));
+    const strip = (record) => stableStringify(JSON.parse(JSON.stringify({ ...record, ...blanks })));
+    return strip(existing) === strip(incoming);
+}
+function sameProposal(existing, incoming) {
+    return sameRecordIgnoring(existing, incoming, ['createdAt']);
+}
+/**
+ * Two entries in ONE envelope claiming the same id are invalid, and are caught
+ * before any of the batch is written.
+ *
+ * Every record here is written to a path derived from its id, so a duplicate is
+ * two entries with one destination: `applyPlan` would write the first and then
+ * silently overwrite it with the second, and the owner would review a proposal
+ * whose other half never existed. Which one "won" would depend on array order,
+ * which is not a decision anyone made.
+ *
+ * Scoped PER KIND, because flows and rules live in different directories and
+ * therefore have separate namespaces: a Flow `x` and a Rule `x` do not collide.
+ */
+function duplicateIdProblems(entries, field) {
+    const seen = new Map();
+    const problems = [];
+    for (const [index, entry] of entries.entries()) {
+        const first = seen.get(entry.id);
+        if (first === undefined) {
+            seen.set(entry.id, index);
+            continue;
+        }
+        problems.push({
+            field: `${field}.${index}.id`,
+            detail: `"${entry.id}" is already proposed by ${field}.${first} in this same answer — one id, one record: decide which of the two you mean and return only that`,
+        });
+    }
+    return problems;
+}
+export function planProposals(input) {
+    const { home, canonicalRoot, answer, now } = input;
+    const problems = [
+        ...duplicateIdProblems(answer.flows, 'flows'),
+        ...duplicateIdProblems(answer.rules, 'rules'),
+    ];
+    const items = [];
+    const createdAt = now.toISOString();
+    for (const [index, flow] of answer.flows.entries()) {
+        for (const [touchpointIndex, touchpoint] of flow.mechanics.touchpoints.entries()) {
+            const problem = validateRelativeGlob(touchpoint);
+            if (problem) {
+                problems.push({
+                    field: `flows.${index}.mechanics.touchpoints.${touchpointIndex}`,
+                    detail: `"${touchpoint}" ${problem}`,
+                });
+            }
+        }
+        // A recognised id is an UPDATE whatever the agent labelled it: the
+        // filesystem decides, not the label, so a mislabelled answer can never
+        // create a duplicate Flow or clobber one under the wrong proposal type.
+        const action = flowExists(canonicalRoot, flow.id) ? 'update' : 'new';
+        const record = FlowProposalSchema.parse({
+            id: flow.id,
+            proposalType: action === 'update' ? 'update' : 'draft',
+            reason: flow.reason,
+            proposedBy: input.proposedBy,
+            createdAt,
+            status: flow.status,
+            presentation: flow.presentation,
+            truth: flow.truth,
+            mechanics: flow.mechanics,
+        });
+        let alreadyPresent = false;
+        if (flowProposalExists(home, flow.id)) {
+            const existing = readProposalOrNull(() => readFlowProposal(home, flow.id).data);
+            if (existing && sameProposal(existing, record)) {
+                alreadyPresent = true;
+            }
+            else {
+                problems.push({
+                    field: `flows.${index}.id`,
+                    detail: `a different proposal for "${flow.id}" is already awaiting review — review or dismiss it before importing this one (prismatica flow show ${flow.id})`,
+                });
+            }
+        }
+        items.push({ id: flow.id, kind: 'flow', action, record, alreadyPresent });
+    }
+    for (const [index, rule] of answer.rules.entries()) {
+        const action = input.knownRuleIds.includes(rule.id) ? 'update' : 'new';
+        const record = RuleProposalSchema.parse({
+            id: rule.id,
+            proposalType: action === 'update' ? 'update' : 'draft',
+            reason: rule.reason,
+            proposedBy: input.proposedBy,
+            createdAt,
+            text: rule.text,
+        });
+        let alreadyPresent = false;
+        if (ruleProposalExists(home, rule.id)) {
+            const existing = readProposalOrNull(() => readRuleProposal(home, rule.id).data);
+            if (existing && sameProposal(existing, record)) {
+                alreadyPresent = true;
+            }
+            else {
+                problems.push({
+                    field: `rules.${index}.id`,
+                    detail: `a different proposal for "${rule.id}" is already awaiting review — review or dismiss it before importing this one (prismatica rules list)`,
+                });
+            }
+        }
+        items.push({ id: rule.id, kind: 'rule', action, record, alreadyPresent });
+    }
+    if (problems.length > 0) {
+        return { ok: false, problems };
+    }
+    // Absence is reported, never acted on: a Flow the agent could not find stays
+    // exactly as it is. Filtered to ids that really are canonical here, so a
+    // typo cannot make the owner hunt for a Flow that never existed.
+    const notFound = answer.notFound.filter((entry) => flowExists(canonicalRoot, entry.id));
+    return { ok: true, plan: { items, notFound } };
+}
+/**
+ * An unreadable proposal is NOT treated as "no proposal". Returning null routes
+ * it to the conflict branch above, which refuses — a file we cannot parse is
+ * the one case where overwriting could destroy something nobody can see.
+ */
+function readProposalOrNull(read) {
+    try {
+        return read();
+    }
+    catch {
+        return null;
+    }
+}
+/** Writes only. Every decision was made by `planProposals`. */
+export function applyPlan(home, plan) {
+    const written = [];
+    const alreadyPresent = [];
+    for (const item of plan.items) {
+        const summary = { id: item.id, kind: item.kind, action: item.action };
+        if (item.alreadyPresent) {
+            alreadyPresent.push(summary);
+            continue;
+        }
+        if (item.kind === 'flow') {
+            const record = item.record;
+            writeFlowProposal(home, record, renderFlowProposalBody(record));
+        }
+        else {
+            const record = item.record;
+            writeRuleProposal(home, record, renderRuleProposalBody(record));
+        }
+        written.push(summary);
+    }
+    return { written, alreadyPresent, notFound: plan.notFound };
+}
+//# sourceMappingURL=materialise.js.map

package/dist/planning/materialise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialise.js","sourceRoot":"","sources":["../../src/planning/materialise.ts"],"names":[],"mappings":"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"}

package/dist/planning/pack.js

@@ -0,0 +1,290 @@
+/**
+ * The provider-neutral instructions carried inside a context envelope.
+ *
+ * Plain deterministic text rendered from a snapshot, identical for every agent.
+ * There is no per-provider dialect here and no transport: Prismatica exports a
+ * document, an agent the OWNER is already talking to reads it, and the answer
+ * comes back through `--import`. That is the whole seam. Prismatica imports no
+ * LLM SDK, spawns no planner, holds no key and reads no transcript.
+ *
+ * The instructions never restate the answer's SHAPE — the envelope carries a
+ * JSON Schema derived from the importing zod schema itself, so a prose copy of
+ * the same field list could only ever go stale.
+ */
+import { FLOW_FIELD, FLOW_STEP_FIELD } from '../atlas/labels.js';
+import { DISCOVER_FORMAT, PROPOSE_FORMAT, START_FORMAT } from './schema.js';
+function bulletsOrNone(lines, none) {
+    return lines.length === 0 ? `_${none}_` : lines.map((line) => `- ${line}`).join('\n');
+}
+function snapshotSection(snapshot) {
+    const flows = bulletsOrNone(snapshot.flows.map((flow) => `**${flow.id}** — "${flow.title}" (${flow.status}) — ${flow.goal}\n  - truth hash: \`${flow.truthHash}\`\n  - lives in: ${flow.touchpoints.join(', ') || '(no touchpoints mapped)'}`), 'no Flows are recorded yet');
+    const rules = bulletsOrNone(snapshot.rules.map((rule) => `**${rule.id}** — ${rule.text}`), 'no app rules are recorded yet');
+    const pending = bulletsOrNone(snapshot.pending.map((item) => `${item.kind} **${item.id}** (${item.proposalType}) — ${item.reason}`), 'nothing is pending review');
+    const open = bulletsOrNone(snapshot.openChanges.map((change) => `**${change.id}** — ${change.title} (at stage ${change.stage})`), 'no changes are in flight');
+    const problems = snapshot.problems.length === 0
+        ? ''
+        : `\n### Records that could not be read\n\n${bulletsOrNone(snapshot.problems, '')}\n\nDo not assume anything about these — say so in your answer instead.\n`;
+    return `## The repository, exactly as it stands
+
+- **App:** ${snapshot.appName} (mode: ${snapshot.mode})
+- **Git HEAD:** \`${snapshot.head}\`${snapshot.branch ? ` on \`${snapshot.branch}\`` : ''}
+- **Snapshot id:** \`${snapshot.snapshotId}\`
+- **Proof available here:** ${snapshot.capabilities.join(', ') || 'none configured'}
+
+### Flows
+
+${flows}
+
+### App rules
+
+${rules}
+
+### Pending proposals (already awaiting the owner)
+
+${pending}
+
+### Changes already in flight
+
+${open}
+${problems}`;
+}
+/**
+ * The one thing every answer must do, said once: echo the binding it was given,
+ * so an answer about a tree that has since moved is a detectable fact rather
+ * than a hope. It is checked against a reading taken FRESH at import time, and
+ * a mismatch is a refusal rather than a merge.
+ */
+function bindingSection(echo) {
+    return `## Writing the answer
+
+Write ONE JSON document — no prose before or after it — matching \`answerSchema\`
+in the context file you were given. Save it to a file and tell the owner the
+exact path; the owner imports it themselves.
+
+${echo}
+
+Prismatica takes a fresh reading of the repository when the owner imports your
+answer, revalidates everything you returned against THAT reading, and shows the
+owner anything that moved in between. Nothing you return takes effect until
+they confirm it.`;
+}
+/**
+ * Planning instructions. They ask for exactly one document and forbid every
+ * kind of action — the agent is reading, not building, and the owner's import
+ * is the only thing that creates anything.
+ *
+ * They carry no request. `prismatica context start` takes no argument: the
+ * owner is already in a conversation with this agent, and that conversation is
+ * where the need is described and clarified. The wording they settle on is
+ * returned in the plan's `request` field, so exactly one agreed description of
+ * the change reaches the records, the issue and the reviewer.
+ */
+export function startInstructions(input) {
+    const { snapshot } = input;
+    return `# Planning context — ${snapshot.appName}
+
+The owner wants to change this app. Your job is to settle WHAT they want with
+them in this conversation, read this repository, and turn both into ONE
+structured proposal they can approve or reject. You are not building anything,
+and nothing you return takes effect until the owner imports it and confirms.
+
+${snapshotSection(snapshot)}
+
+## What to do
+
+1. **Settle the request with the owner, here, before you write anything.** Ask
+   about anything that genuinely changes the plan — behaviour, data, security,
+   destructive effects, compatibility — and ask it in this conversation, where
+   they can answer in their own words. Decide from the code everything the code
+   can decide. Then put the wording you both agreed in \`request\`: that exact
+   text is recorded, filed on the GitHub issue and read by the reviewer.
+   Prismatica will not ask any of it again at import time.
+2. **Agree who will build it, and put that in \`builder\`** (\`claude\`,
+   \`codex\`, or whatever the owner names). Do not assume it is you — planning
+   and building are different jobs, and a fresh session usually builds.
+3. Read the real code — routes, handlers, components, tests — before deciding
+   anything. Do not reason from the Flow text above alone; it describes intent,
+   the code is what actually happens.
+4. Decide which of three kinds this is, and be honest about it:
+   - \`existing-flow\` — it changes how a Flow listed above behaves. Name that
+     Flow's exact id and return a complete Delta.
+   - \`new-flow\` — it is a genuinely new user journey that no Flow above
+     covers. Return a complete Planned Flow with \`status: planned\`.
+   - \`technical\` — refactors, build, tooling, tests, dependencies. Return
+     neither a Delta nor a Planned Flow. **Do not invent a product Flow to make
+     technical work look like a feature.**
+5. Propose the narrowest scope that can actually do the job. Every glob must be
+   relative to the repository root. Absolute paths, \`..\`, and anything
+   matching a secret file will be rejected.
+6. Answer the risk questions honestly. Your answers can RAISE the risk tier;
+   they can never lower it. Deterministic path rules are applied on top and win.
+7. Give at least two acceptance checks. Each needs a real test file path
+   (\`src/thing.test.ts\`) or \`manual:OWNER\` — a description with no way to
+   prove it is not a check.
+8. List in \`docsDelta\` every documentation file this change must update. The
+   check engine requires each of them to have actually changed, so name the
+   ones that genuinely go stale — not every file in \`docs/\`.
+9. Label honestly: \`assumptions\` and \`possibleConflicts\` are your reading of
+   the situation. They are shown to the owner as **advisory**, and no
+   deterministic decision is made from them.
+
+${bindingSection([
+        `Set \`format\` to \`"${START_FORMAT}"\`.`,
+        '',
+        'Copy the whole `snapshot` object from the context file into your answer,',
+        'VERBATIM — every field, unedited. Prismatica recomputes its id from its own',
+        `contents (\`${snapshot.snapshotId}\`) and refuses an echo that was assembled by`,
+        'hand. It is used only to tell the owner what moved since you read the tree.',
+    ].join('\n'))}
+
+Do not write, edit, or delete any file except the answer. Do not create an
+issue, branch, or worktree. Do not run any command that changes state. Do not
+run \`prismatica start\` yourself — it is the owner's decision, and it refuses
+an agent anyway. Tell the owner to run it in their OWN terminal:
+
+    prismatica start --import <the file you saved>
+`;
+}
+// ── Flow/Rule proposals ──────────────────────────────────────────────────────
+const FLOW_PROPOSAL_TEMPLATE = `---
+id: <kebab-case-id, e.g. log-a-practice-session>
+proposalType: draft
+reason: "Discovered while reading the repo"
+proposedBy: agent
+createdAt: "<ISO timestamp, e.g. 2026-01-01T00:00:00.000Z>"
+status: works               # works | planned | idea | uncertain — be honest; see rules below
+truth:
+  goal: "<${FLOW_FIELD.goal.hint}>"
+  startsWhen: "<${FLOW_FIELD.startsWhen.hint}>"
+  needs: []                 # optional — ${FLOW_FIELD.needs.hint}
+  steps:
+    - actor: "<${FLOW_STEP_FIELD.actor.hint}>"
+      action: "<${FLOW_STEP_FIELD.action.hint}>"
+      shows: "<optional — ${FLOW_STEP_FIELD.shows.hint}>"
+      changes: "<optional — ${FLOW_STEP_FIELD.changes.hint}>"
+      assumes: []            # optional — ${FLOW_STEP_FIELD.assumes.hint}
+      evidence: { method: inferred, at: "<same ISO timestamp>" }
+    # one entry per step — add as many as the real flow needs
+  endsWith: "<${FLOW_FIELD.endsWith.hint}>"
+  variations: []             # optional — {name, differs, status?}
+  rules: []                  # optional — free text, or an existing rule id like "r-offline-first"
+  involves: []                # optional — who/what takes part
+mechanics:
+  touchpoints: ["<file globs this flow's code lives in>"]
+  routes: []
+  components: []
+  entities: []
+  tests: []                   # [{file, steps: [1,2]}] — only list tests you actually found and read
+---
+
+Notes for the owner (optional free text — not validated).
+`;
+const RULE_PROPOSAL_TEMPLATE = `---
+id: <kebab-case-id starting with "r-", e.g. r-offline-first>
+proposalType: draft
+reason: "Discovered while reading the repo"
+proposedBy: agent
+createdAt: "<ISO timestamp>"
+text: "<the rule, in one plain sentence>"
+---
+`;
+/**
+ * Flow/Rule proposal instructions — the first mapping of an app and every
+ * reconciliation afterwards, which are the same job at different starting
+ * points. The snapshot above already says which Flows exist, so one text covers
+ * both: with none listed it reads as "map this app", with some listed it reads
+ * as "reconcile what is here against the code".
+ */
+export function proposalsInstructions(input) {
+    const { snapshot } = input;
+    const firstRun = snapshot.flows.length === 0;
+    return `# Understanding context — ${snapshot.appName}
+
+Your job is to read this repository and describe what it actually does, as
+Flows and app Rules — Prismatica's map of the app. You are NOT building or
+changing anything; you are observing and reporting. Nothing you return takes
+effect until the owner reviews and approves it, one proposal at a time.
+
+## What a Flow is
+
+A Flow is one complete, real route through the app: where it starts, the steps
+someone takes, what the app shows and changes at each step, and where it ends.
+Not a feature list, not a code walkthrough — an outcome someone actually gets,
+start to finish.
+
+${snapshotSection(snapshot)}
+
+## What to do
+
+1. ${firstRun
+        ? 'This app has no Flows recorded yet. Draft 6–12 Flows covering its real, everyday use. Do not invent features that are not in the code.'
+        : 'Reconcile the Flows above against the code as it is **now**, and draft Flows for real behaviour none of them covers yet.'}
+2. Read the real code paths for each candidate Flow — routes, handlers,
+   components, tests — before writing anything about it.
+3. **Recognise, do not duplicate.** If what you find changes a Flow listed
+   above, return it with that Flow's **exact existing id** and
+   \`proposalType: "update"\`. Use \`"draft"\` only for behaviour no listed Flow
+   covers. A near-duplicate under a new id is the single most damaging thing
+   you can return here, because ids are how Deltas, reports and evidence stay
+   attached to a Flow across its whole life.
+4. Be honest about \`status\`. Mark \`works\` ONLY where you found working,
+   connected code for the whole path. If you are not sure it is wired up end to
+   end, mark \`uncertain\`. If it is referenced but clearly not built, mark
+   \`planned\` or \`idea\`. Never guess \`works\` to look thorough.
+5. Set every step's \`evidence.method\` to \`inferred\` — you read code, you did
+   not run it. Only a person running \`prismatica flow verify\` produces
+   \`manual\` evidence; only a passing mapped test produces \`test\` evidence.
+6. Propose candidate app rules too — short, cross-cutting requirements you
+   noticed ("offline-first", "never call a paid API").
+7. If a Flow above no longer seems to exist in the code, put it in
+   \`notFound\` with your reason. **Do not** return it as a draft, an empty
+   update, or a deletion. That list is advisory: it causes no write of any
+   kind. The code may simply have moved, and Prismatica never deletes truth
+   because an agent did not mention it.
+8. Leave anything already pending alone. Proposals awaiting the owner are
+   listed above; returning your own version of one would displace a review in
+   progress, and the import refuses rather than overwrite it.
+
+${bindingSection([
+        'Set `format` to the protocol for the command the owner will actually run:',
+        '',
+        `- \`"${DISCOVER_FORMAT}"\` — the map of the app. The owner runs`,
+        '  `prismatica discover --import <file>` and the proposals land on main.',
+        `- \`"${PROPOSE_FORMAT}"\` — a proposal you are making while a change is`,
+        '  being built. The owner runs `prismatica propose --import <file>` and the',
+        "  proposals land in that change's lane, riding its pull request.",
+        '',
+        'The two documents are otherwise identical. Ask the owner which they want if',
+        'it is not obvious; each command refuses the other one\'s format, so a',
+        'mis-paste is caught rather than written to the wrong branch.',
+        '',
+        `Set \`head\` to \`${snapshot.head}\` verbatim — it is the commit you read, and`,
+        'what a Flow describes is committed behaviour. Copy the whole `snapshot`',
+        'object across VERBATIM as well: its id is recomputed from its own contents,',
+        'and it is used only to tell the owner what moved since you read the tree.',
+    ].join('\n'))}
+
+Do not write to \`.prismatica/flows/\`, \`.prismatica/rules.md\`, or any
+canonical record yourself. Only the owner's approval creates those.
+
+## Writing proposal files directly instead
+
+The JSON answer above is the route the owner can prevalidate, retry safely and
+see previewed. If you would rather write proposal files straight into the repo,
+that still works and is still read by \`flow list\`, \`rules list\` and the
+board: one file per Flow at \`.prismatica/flows/proposals/<id>.md\` and one per
+Rule at \`.prismatica/rules/proposals/<id>.md\`, using these exact templates.
+Field names must match exactly.
+
+### \`.prismatica/flows/proposals/<id>.md\`
+
+\`\`\`
+${FLOW_PROPOSAL_TEMPLATE}\`\`\`
+
+### \`.prismatica/rules/proposals/<id>.md\`
+
+\`\`\`
+${RULE_PROPOSAL_TEMPLATE}\`\`\`
+`;
+}
+//# sourceMappingURL=pack.js.map

package/dist/planning/pack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack.js","sourceRoot":"","sources":["../../src/planning/pack.ts"],"names":[],"mappings":"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"}