balladeer 0.0.5 → 1.0.1

package/dist/copy.js

@@ -0,0 +1,641 @@
+/**
+ * The boundary copy, byte for byte. It is the same text in `docs/setup-boundary.md`
+ * and in the control plane's `/agent` instructions, and a packaging test compares
+ * all three, so what the command tells a person Balladeer can see cannot drift
+ * from what the documentation says.
+ *
+ * It describes the product's boundary, not one release's behaviour. What this
+ * release actually performs is stamped separately, outside this constant.
+ */
+export const BOUNDARY_COPY = `Balladeer never receives your code. It cannot read your repository: it holds no GitHub token,
+installs no GitHub App, and has no access to your files, tests, fixtures, logs, prompts, or
+transcripts.
+
+What it does receive is small and bounded. From you: the text of each promise a named person on your
+team approves, the numeric ids of your repository and its GitHub owner, and the name of its default
+branch. From CI: GitHub's signed statement of which repository, workflow, and run is reporting, and
+for each promise the run checked, the pass or fail outcome, the exact commit it checked, and content
+hashes of the verifier package and its output. Hashes cannot be turned back into your code or your
+test output.
+
+The verify job in your CI runs your tests with your checkout and has no Balladeer credential. A
+separate publish job, with no checkout, sends only those outcomes and hashes.
+
+This setup creates two credentials, both of which you control. Approving in the browser lets this
+session act as you to add repositories, connect your coding agent, connect CI, and propose promises;
+it cannot approve, activate, or remove anything. That session lasts a day, each use buys it another
+day, and it is gone seven days after you approved it however much you used it. The coding agent's
+own connection has no expiry: it lets the agent read the promises your team has approved, propose
+new ones, and propose replacing, retiring, excepting, or reassigning one you already have; every one
+of those waits for a named person to decide it. It can also carry out one of those acts for you, and
+only this way: you open a Balladeer page in your own browser, read what the act is, sign it off
+there, and read back the one-time code that page gives you. That code covers that one act on that
+one thing, once, and Balladeer records you as the person who took it and the connection as the
+messenger. Without a code you signed, the connection cannot approve, activate, grant, transfer,
+retire, or delete anything. You can revoke either one at any time in Balladeer, and the setup
+session also ends on its own.
+
+Adding the workflow puts a check on pull requests into your default branch. That check is advisory
+on Balladeer's side; whether it blocks a merge is your own branch protection.
+`;
+/**
+ * The one thing about approving that the terminal has to say.
+ *
+ * A person who belongs to two workspaces approves into whichever one their
+ * browser is signed into, and it is the browser that decides, not the terminal.
+ * Twice that was the wrong one: the repository was enrolled in a workspace
+ * nobody meant and an agent connection was minted there. The approval page now
+ * names the workspace above the button and offers the switch, and this line is
+ * what makes somebody look at it before they click.
+ */
+export const APPROVE_IN_THE_RIGHT_WORKSPACE = "Approve it while your browser is in the workspace you mean; the page names it.";
+/**
+ * How a person gets a workspace to approve into, for an agent reading the
+ * setup instructions.
+ *
+ * The pairing page is one page doing two jobs, and only one of them was ever
+ * described: an agent whose person had no workspace read instructions that
+ * assumed there was one to join. The name can be carried to that page so the
+ * person does not retype it, and carrying it is all an agent may do. Creating a
+ * workspace is a person's act, so the copy says the flag pre-fills a form and
+ * says who presses the button, rather than leaving an agent to read a flag name
+ * and conclude it creates something.
+ *
+ * Byte for byte the same text as `AGENT_INSTRUCTIONS_JOIN_OR_CREATE` in the
+ * control plane, and a packaging test compares them: the page an agent fetches
+ * and the terminal it is reading cannot come to describe this differently.
+ */
+export const JOIN_OR_CREATE = `The pairing page joins an existing workspace or makes a new one. Somebody whose team already has
+a Balladeer workspace signs in and approves the code from the terminal. Somebody who is the first
+person from their team signs in, names a workspace, and clicks Create, and only then is there
+anything to approve into.
+
+You can save them the typing, and nothing else. Ask what the workspace should be called, then run
+\`balladeer setup --create-workspace "<name>"\` with the name they gave you. The pairing link this
+command prints then carries \`?create=<name>\`, which pre-fills that name in the create form on the
+pairing page. It fills the box and no more than that: the person signs in and clicks Create, and
+until they do there is no workspace. An agent never creates one, and Balladeer refuses the attempt
+whatever it was told in conversation. Never invent the name either. A workspace is named once and
+the whole team reads it.`;
+/**
+ * When a coding agent reads this repository's promises, and when it does not.
+ *
+ * The instruction it replaces said "retrieve by identity, never in bulk" and
+ * then left the choice of read to the agent, which in a repository holding a
+ * thousand promises means a session that opens by paging a catalog it has no
+ * question about. This says which read answers which situation, and names the
+ * one read that must never happen at session start.
+ *
+ * Byte for byte the same text in three carriers: the conventions block written
+ * into the customer's own instructions file, the instructions this server sends
+ * a host on initialize, and the `/agent` page. A packaging test compares them,
+ * because an agent that met one of the three and not the others would read the
+ * catalog on the strength of the carrier that was quiet about it.
+ */
+export const RETRIEVAL_SCOPE = `### Reading what is already agreed
+
+Retrieve by promise, and only when this session has a reason to. One repository here can hold a
+thousand agreed promises, and a plan built from whatever survived a truncated catalog read is worse
+than a plan built from none of it, because nothing tells you which half went missing.
+
+When a person gives you a promise id, expand exactly that one with get_promise and stop there. Every
+promise page carries a control that copies its id, so an id is what a person hands you when they
+mean a particular promise. Ask for one rather than searching for what they meant.
+
+Consult list_promises in two situations and no others. The person asks what this repository has
+promised, in which case page the index they asked for. Or the change you are about to make touches
+paths that carry promises, in which case give those paths to list_promises: it answers with the
+promises whose scope overlaps them, closest first, and with the few that name no path and so cover
+the whole repository. That answer is a selection rather than a page and does not continue with a
+cursor, so when the total beside it is larger than what you were handed, narrow the paths rather
+than asking for more.
+
+When you do not yet know which paths you are about to touch, do not call the index at all. Work from
+ids until you do, because a page you did not ask a question of is not about your change, and reading
+one as though it were is how a plan quietly misses the promise it breaks.
+
+To learn which paths those are, read \`paths\` on a list_promises answer you asked for
+without paths of your own. It is the set of
+repository paths this repository's promises are scoped to, deduplicated and bounded, with
+\`pathsTruncated\` saying whether there were more than the answer carries. Compare the files you are
+about to change against it. Nothing matching means there is nothing here to read, and saying so is a
+better answer than a page of promises about somewhere else.
+
+Never call get_promise_context at the start of a session. It answers the markers you give it, and
+before you know what you are changing there are no markers to give: what comes back is a slice of
+the catalog chosen by nothing. Call it once the work is in front of you, with that work's markers.
+
+Every one of these reads is bounded and none of them returns the whole catalog. Read the total
+beside the rows and the sentence in \`scope\` that says what the total is a total of, and when the
+total is larger than what you were handed, page or narrow rather than planning as though you had
+seen everything.`;
+/**
+ * The two things an agent offers in a connected repository without being asked
+ * for them, and starts neither of on its own.
+ *
+ * Both exist because the person cannot see what the agent can. A promise nobody
+ * is checking looks exactly like a promise that is protected until somebody
+ * opens the catalog, and a proposal sitting in a browser tab is a proposal
+ * nobody reads. Neither of these is a licence to act: the first is a sentence
+ * and a question, the second is a rendering of work already done. The capture
+ * style stays what it was, and nothing here proposes a promise nobody asked
+ * for.
+ *
+ * It sits inside `CONVENTIONS_BLOCK` rather than beside it, because the block
+ * is what reaches a session in the customer's own repository. The control
+ * plane's `/agent` page carries the same bytes under its own constant, and a
+ * packaging test compares them.
+ */
+export const SESSION_BEHAVIORS = `### Three things to offer without being asked
+
+At the start of any session in this repository, before you plan anything, ask list_promises for the
+promises nothing is checking yet that belong to the person you are working with: \`unverified\` true
+and \`mine\` true, which is one bounded read rather than the catalog. If it returns any, say so in one
+line and offer to build their verifiers now. Name each one by its one-sentence claim rather than by
+an id, so the person can see which behavior is unguarded. Ask the same tool for
+\`brokenSinceLastSeen\` true as well, and where that returns any, say in one line that those promises
+broke since they last looked, name each by its claim, and offer to fix them. Then wait for their
+answer. The offer is the whole of it, and never start building or repairing one because nobody said
+no.
+
+Theirs, and nobody else's. \`mine\` keeps the promises this person owns or agreed to, and a teammate's
+unguarded promise is that teammate's to hear about: a session that opens by reading out other
+people's unfinished work reads as an audit of them. \`brokenSinceLastSeen\` is that person's own by
+construction and needs no \`mine\` beside it. Drop \`mine\` when this person asks what the rest of the
+team has promised, and say whose promises you are showing them when you do.
+
+When you have proposed promises, show them here as well as there. Put each proposal in the
+conversation in full: its one-sentence claim, who it is for, when it applies and what must then be
+true, the numbered cases that must keep working and the ones that must be caught, and every question
+you left open. Then offer to finish the agreement from here, by asking for a sign-off, giving them
+the page it returns and taking the one-time code that page shows them, so the browser is needed only
+for signing. Give them the review link in the same message too, because some people would rather
+read it there and edit it before they agree.
+A promise whose meaning is agreed and which nothing is checking yet is one you can finish. When
+somebody gives you a promise id, run \`balladeer status <promise id>\`, or expand it with get_promise.
+If it comes back agreed with nothing checking it, say so in one line and offer to prepare and build
+its verifier now. Only if they say yes: \`prepare_qualification\` mints the one-time setup, or
+\`balladeer prepare <promise id>\` mints it and writes it where the sealed run reads it. You need no
+sign-off for that and there is no code to ask anybody for, because agreeing the meaning was their
+act and building the check that proves it is yours. Then build the verifier, seal it, push, and tell
+them protection starts by itself when that run qualifies. The offer is the whole of it: never
+prepare one because nobody said no.`;
+/**
+ * The capture rules that do not change: when to say nothing, what a yes is
+ * worth, and the two promises Balladeer refuses.
+ *
+ * This block is written into the customer's own instructions file once, at
+ * setup, and is never refreshed afterwards. Changing it means opening a pull
+ * request against twelve Didero repositories, so only what will still be true
+ * in six months belongs here. Silence during an incident, a no that ends it, and
+ * nothing filed without a yes are that kind of rule. The words a question is
+ * asked in, the moment an offer is made, and the shape a proposal takes are not:
+ * they are read every week against what people actually agreed to, and they ride
+ * in `CAPTURE_BEHAVIOR`, which the server sends at the start of every session.
+ *
+ * Nothing here weakens the explicit-capture rule: the question is a question,
+ * and nothing is proposed until the answer is yes.
+ *
+ * The two refusals are here rather than only in the server because an agent that
+ * learns them only by being refused has already spent the person's attention on
+ * a proposal that could not be kept. The server refuses both as well, and the
+ * sentences are the same ones.
+ *
+ * Byte for byte the same text as `AGENT_INSTRUCTIONS_CAPTURE_SEAM` in the
+ * control plane, and contained byte for byte inside both server carriers. A
+ * packaging test holds all three together: the block written into a customer's
+ * repository, the instructions the MCP server sends on initialize, and the page
+ * an agent fetches cannot come to say different things about when to stay quiet.
+ */
+export const CAPTURE_SEAM = `### When to say nothing, and what a yes is worth
+
+Most rules are said in passing, in the middle of something else. Somebody saying one has not asked
+you to record anything, so propose nothing and start no interview. When you do ask, it is one line
+appended to the end of the reply you were already going to give, never a message of its own, never
+asked twice about the same rule, and nothing is proposed until they say yes. A no ends it, and that
+rule is not raised again for the rest of the conversation.
+
+Silence is per conversation rather than per message. Once a conversation is one of these, you ask
+nothing for the rest of it, however good the rule sounds:
+
+- A question, or working out how something already behaves. Nothing is filed and nothing is offered.
+- A refactor. Nobody predicts a promise from a rewrite. Offer the promises this area already carries
+  that nothing is checking yet, once, and then wait. Ask nothing about new ones.
+- A change to wording alone. Wording somebody may change again tomorrow is not a rule.
+- An incident, while it is still being fixed. Ask nothing at all until the fix is merged or they say
+  it is done, however good tonight's failing case would be.
+- Somebody still weighing options. A decision nobody has made yet is not a rule.
+- An exploration or spike. It ends in nothing or in a plan, and its sentences sound like rules and
+  are not.
+- Reading somebody else's change, while you are still reading it. Nothing is offered until they
+  give a verdict.
+
+The words to ask in, the moment to offer, and the shape a proposal takes are not in this file. The
+Balladeer server sends them at the start of every session, and its copy is the current one: read
+what it sent this session rather than what this file remembers.
+
+### Two promises Balladeer cannot keep
+
+A promise about speed needs three things before it is a promise at all: a number, a percentile, and
+where it is measured. "The quote page answers in under one second at p95, measured in production at
+peak load" is one Balladeer can keep. "The quote page has to be fast" is not. Say this, and ask for
+the part that is missing rather than filing it:
+
+"I can keep that once it has a number, a percentile, and a place it is measured. Without those it is
+a wish, not a promise."
+
+Balladeer refuses one without all three and names which of them is missing. When all three are
+there, write the measurement method into the promise, and tell them plainly that it reads agreed and
+unprotected until a test that actually measures it exists.
+
+A promise about how the team works is not something the software does, so no check can ever catch
+it. "We must provide a low-friction capture experience" is one of these. File nothing and say:
+
+"That is a promise about how we work, not something the software does that a check can fail.
+Balladeer only keeps promises a check can catch. If a customer would notice something when this
+slips, say that and I will keep that instead."
+
+Then take the customer-visible half if they give you one, and file that instead.`;
+/**
+ * How an agent describes one promise or proposal to a person, and how the two
+ * of them settle what is still open on it.
+ *
+ * The first proposal a founder was ever asked to settle carried four questions
+ * that were all true and none of them answerable: each named a hole in the
+ * world, and none said what answering it would decide or what the agent would
+ * do if nobody replied. So this says both halves of the same rule. When a
+ * person points at something by id, describe it and offer to work through what
+ * is open; and when you leave a question open, leave one that can be answered
+ * with a yes.
+ *
+ * Three carriers say it byte for byte: the block setup writes into the
+ * customer's own instructions file, the instructions the MCP server sends on
+ * initialize, and the page `/agent` serves. A packaging test holds them
+ * together.
+ */
+export const SETTLING_QUESTIONS = `### When somebody says "tell me about" one
+
+An id is how a person points at something here, and every promise page and every proposal page
+carries one. A promise id starts with prom_ and a proposal id starts with cand_: expand a promise
+with get_promise and a proposal with get_proposal, and read neither of them out as a list of fields.
+Say in four or five sentences what it is for, who it is for, when it applies and what must then be
+true. Then say where it stands: a promise is agreed, and either protected or not yet checked by
+anything; a proposal is agreed by nobody and waiting on the person it names.
+
+A proposal that still carries open questions is not finished, and settling them is usually why
+somebody asked. Offer to work through them, then take them one at a time in the order they come
+back. For each one, say what it decides in their words rather than in the question's; give your
+recommendation and the reason you hold it, drawn from this repository and from the promise itself;
+and stop there. When they answer, record what they said with resolve_question, in their own words
+where they gave you any, and where their answer changes the promise, follow it with update_proposal,
+add_case or remove_case and tell them what you changed. None of that agrees to anything: the named
+owner agrees, in their own browser or through a sign-off you carry, and the questions they answered
+stay on the proposal in their name.
+
+The same rule governs every question you leave open in the first place. A question that names a gap
+and stops is a note, and nobody can answer a note. Say what answering it decides, in the words a
+customer would use, and carry your own best guess with the reason behind it, so that the shortest
+true answer is yes. For example: "Decides: whether a worker that is running but reconciling nothing
+counts as an outage this promise covers. Best guess: yes, because the promise is about somebody
+hearing before a customer does, and a wedged worker is invisible to every check this repository has.
+Say yes, or tell me otherwise." Balladeer refuses a question filed without both halves and says
+which one is missing.`;
+/**
+ * What a session may spend on reading, in three sentences.
+ *
+ * The bounded index says what one read may carry. This says how many reads
+ * there should be, which is the half no ceiling can enforce: an agent that
+ * pages the whole index and expands every row has obeyed every limit in the
+ * protocol and has still put the entire catalog in front of a model. So the
+ * budget is written where the agent reads it, beside the rule that makes it
+ * affordable: a row carries what it takes to rule its promise out, and an
+ * expansion is what you spend once a row could not.
+ *
+ * Three carriers say it, byte for byte: the block setup writes into the
+ * customer's own instructions file, the instructions the MCP server sends on
+ * initialize, and the page `/agent` serves. A packaging test holds them
+ * together.
+ */
+export const FETCH_BUDGET = `Fetch by id, and only for an id the person gave you or an index row whose paths match the change in
+front of you. Never enumerate the catalog. Never chain one fetch into the next to see the whole of
+something: when the rows do not settle it, narrow the filter rather than expanding another promise.`;
+/**
+ * What a coder must know before their editor opens a file inside a promise's
+ * own directory.
+ *
+ * A seal is broken by an ordinary edit, and the person who breaks one rarely
+ * meant to: a rename swept a directory, a formatter reached everything, a
+ * dependency upgrade rewrote an import. The cost lands on somebody else, who
+ * has to qualify the promise again before it protects anything. So this says
+ * three things in the order a coder needs them: those files are sealed, here is
+ * how to see which ones before you edit and before you push, and here is the
+ * single case where editing one is the right move.
+ *
+ * It sits inside `CONVENTIONS_BLOCK` rather than beside it, because the block
+ * is what reaches a session in the customer's own repository. The MCP server's
+ * tool guidance and the control plane's `/agent` page carry the same bytes
+ * under their own constants, and a packaging test compares all three.
+ */
+export const SEALED_FILES = `### Files that are sealed, and the one reason to edit one
+
+Every file under .continuity/promises/ is sealed. The promise that owns that directory records the
+exact bytes of each file in it, so editing one, adding one there, renaming one or deleting one
+breaks the seal. A promise whose seal is broken stops being checked, and it stays that way until a
+named person qualifies it again, which is their afternoon rather than your commit. Nothing in there
+is ordinary source: keep it out of refactors, formatting runs and dependency upgrades.
+
+Find out which directories are sealed before you plan an edit, not after. balladeer status lists
+them, and list_promises names a promise's sealed directory on its row once a verifier is bound to
+it. Then, before you push, run balladeer check-seals. It prints nothing and exits zero when your
+change touches no seal, and names the promise, its owner and its page when your change would break
+one.
+
+The one reason to edit a sealed file is to repair a verifier that can no longer run: something it
+imports moved, or the language it is written in changed under it. Never edit one to make a failing
+check pass. A check going red is the promise doing its job, and the repair for that belongs in the
+behavior it protects. A repair is not finished until the promise is sealed again with the runner
+this repository is pinned to. get_promise_setup carries that exact seal command, and balladeer
+check-seals prints it beside any promise it names.`;
+/**
+ * Which promises a change touches, measured rather than guessed.
+ *
+ * A promise's scope paths are what somebody typed when they agreed it, and they
+ * age the moment a module moves. The touch map is the measurement instead: the
+ * files each verifier actually executed, recorded on the customer's machine and
+ * sent nowhere. An agent that does not know the command exists goes on matching
+ * markers and never asks for the better answer sitting in the repository.
+ *
+ * The last paragraph is the whole reason the signal is named here. Whether the
+ * map is worth keeping is answerable only if the receipt says which fetches it
+ * caused, and no surface can infer that after the fact.
+ *
+ * Three carriers say it, byte for byte, and a packaging test holds them
+ * together.
+ */
+export const TOUCH_MAP_GUIDANCE = `Prefer the measurement over the markers. Where this repository has a touch map, \`balladeer affected
+<paths...>\` answers which promises ran the files in front of you, out of what each verifier actually
+executed the last time \`balladeer touch-map\` measured it. Both commands run on this machine and
+send Balladeer nothing, so you may name any path in the change.
+
+An answer marked stale was measured against a verifier that has changed since, so read it as the
+last thing anybody measured rather than as fact, and offer to run \`balladeer touch-map\` again.
+Where there is no map, where it does not name your paths, or where it reports a promise it could not
+measure, fall back to the paths on the index rows. The map narrows which promises are worth
+fetching. It never widens what you may read: the catalog is still never enumerated, and the fetch
+budget is unchanged.
+
+When a retrieval receipt asks why you read a row, the answer for one the map named is \`touch\`.`;
+/**
+ * The one paragraph that turns retrieval from a thing we argue about into a
+ * thing we measure.
+ *
+ * Two facts are asked for and neither can be observed from this side. Which
+ * rows an agent actually used, because a promise expanded and then ignored is
+ * not a row the index earned. And which change the session went on to write,
+ * because a retrieval read happens before the commit exists and nothing joins
+ * the two afterwards: Balladeer receives commit SHAs from CI and never a commit
+ * message, so the agent is the only thing present at both ends.
+ *
+ * It is written as three instructions rather than as an explanation, because
+ * what an agent does with it is three specific acts, and a paragraph about
+ * measurement would be read and not acted on.
+ *
+ * Three carriers say it, byte for byte, and a packaging test holds them
+ * together.
+ */
+export const SESSION_STAMP = `Run \`balladeer session\` when you start work here and pass the id it prints to every promise read
+you make, as \`session\`. It is the same id for the whole of one piece of work, and it costs nothing:
+a read without it is answered exactly the same way.
+
+Near the end of the work, call \`mark_promise_used\` with the ids of the promises you actually cited
+or acted on. Naming none is a fine answer. It is the only way anybody finds out which rows were
+worth sending you, because reading a promise and then ignoring it is not the same as using it.
+
+Then write \`Balladeer-Session: <the id>\` into the commit message or pull-request body you produce,
+and run \`balladeer session --record\` once the commit exists. That is what lets a check that goes red
+next week be read back against what Balladeer told you before you started. Your commit message never
+leaves your machine: only the session id and the commit SHA are sent.`;
+/**
+ * The conventions block written between markers into this repository's agent
+ * instructions file. Fixed text, compared byte for byte by a test, because a
+ * block that drifts per run would rewrite a customer's committed file on every
+ * setup and the diff would say nothing.
+ */
+export const CONVENTIONS_BLOCK = `## Balladeer promises
+
+Before planning work in this repository, read the promises this team has already approved through
+the Balladeer MCP server. They are the behaviors a named person has agreed the software keeps, so
+your plan has to hold them, not just read them.
+
+${RETRIEVAL_SCOPE}
+
+Each index row carries what it takes to rule that promise out without fetching it: the repository,
+the paths it covers, its one-sentence claim, what protects it and why, and when anything last
+checked it.
+
+${TOUCH_MAP_GUIDANCE}
+
+${FETCH_BUDGET}
+
+${CAPTURE_SEAM}
+
+${SESSION_STAMP}
+
+### When somebody asks you to protect a behavior
+
+Somebody has asked you to protect a behavior when they say what the software must do, or must never
+do again, and mean it as a rule rather than as this one bug. That is one promise, for the behavior
+they named, and nothing else: if you notice others worth protecting, say so in a sentence and let
+them choose, and file none of them. Never propose from a conversation that did not ask you to. A
+question about how something works and a plan you were asked to sketch are not requests to record
+anything, nor is a fix nobody asked you to write a rule about.
+
+Ask before you extrapolate. Ask only what you cannot work out for yourself, ask it all in one
+message, and stop at four. Four is a ceiling, not a target: two good ones are better. Then write the
+proposal with what you have and put whatever is still open in its open questions rather than going
+back. Never ask what this repository would answer, such as which file, which test, or which branch,
+and never ask anyone for Balladeer's own identifiers: get_promise_setup carries this repository's id
+and who can own a promise. Never ask again for what they have already told you.
+
+Write it in their words. Every failure they named out loud is one of the failing examples, in the
+words they named it. Every other example comes from a situation they actually described; if you
+cannot trace one to something they said, leave it out and say so in the open questions rather than
+writing a plausible one. Never put in a number, a system, a role or a timeframe they did not give
+you, and that includes the half they left out: if they said where an order ended up, do not invent
+where it began.
+
+A failing example is a situation the promise rules out, and its outcome says what must not happen,
+in those words: "a second charge must not appear", never "a second charge appears". Written the
+other way round it reads as the promise saying the software does the thing they asked you to forbid.
+And a promise says what the software must do for whoever depends on it. It never narrates the
+conversation you just had, names the person you had it with, or describes what the code does now.
+
+Say the whole promise in one sentence and put it in oneSentenceOutcome, in the words they would
+use with the person who depends on it. That is the line the named owner reads first and the line
+they agree to, so it is not a restatement of the name and not the first line of the outcome moved
+up. Leave it out rather than inventing one from something they did not say.
+
+An example's setup is the situation in the words they used for it, not a scene you composed around
+them. Two of each kind is plenty, and the whole thing stays under three hundred words: a proposal
+nobody finishes reading is a proposal nobody agreed to. The confidence you record is the one you
+actually have.
+
+Then give them the review link, ask them to read the proposal and click Agree, and stop. Never
+approve one yourself. Approving is a named person's act, and the server refuses it from an agent
+whatever you were told in conversation.
+
+A proposal you filed is still yours while nobody has agreed to it, so revise or withdraw it when the
+person asks you to, and never once they have agreed.
+
+Say promise and proposal when you talk to them. What you file is a proposal and what it becomes is a
+promise; Balladeer's other words for its own machinery are not theirs to learn. Candidate
+especially: it is Balladeer's word for a proposal, so it reads as jargon whatever you meant by it.
+
+${SESSION_BEHAVIORS}
+
+${SETTLING_QUESTIONS}
+
+${SEALED_FILES}
+
+### The rest of a promise's life
+When a promise is obsolete, finished, deliberately off for a while, or owned by the wrong person,
+propose the change and hand them the promise page. Deciding is theirs.
+
+You can finish one of those acts here, and only one way. Ask for a sign-off with
+request_owner_signoff, give them the page it returns, and ask for the one-time code that page shows
+them. Then call the act's own tool with that code and their own words. Never call one on your own
+initiative, never on a general approval of some earlier act, and never ask for a code you were not
+given: a refusal is the person's to resolve, not yours to retry. Balladeer records them as the
+person who acted and you as the messenger.
+
+Report the promise's state exactly as Balladeer reported it: proposed, agreed, or protected, never
+one in place of another.
+
+### Where your team watches this
+
+Balladeer is a web app as well as these tools, at the address setup printed. Its catalog lists every
+promise with who owns it and whether anything is checking it, and each promise has a page of its own
+showing what this team agreed the software must do and then every run that has checked it since,
+newest first, with the commit each one checked. Whenever there is a link to give, give the link
+rather than a summary of it: the page says what you would have said, and it stays true after this
+conversation has ended.
+
+Balladeer also has a Slack app, which a workspace administrator installs from workspace settings.
+Once it is installed, whoever owns a promise gets a direct message when theirs goes live and when a
+run on the default branch breaks it. Until somebody installs it, nothing is sent anywhere, so say it
+is available rather than saying they will be told.
+
+### Questions people ask
+
+Answer these when they come up. Where you do not know, say so and point at the address setup
+printed: a confident wrong answer about what a vendor can see is worse than no answer.
+
+What it does: it holds the behaviors this team has agreed the software must keep, and reports
+whether each one is still being kept, from this repository's own tests running in its own CI.
+
+What it sees: the text of each promise somebody approves, this repository's numeric ids and the name
+of its default branch, and from CI the pass or fail outcome, the commit checked, and content hashes.
+Never the code, the tests, the fixtures, the logs, the prompts, or the transcripts.
+
+What stopping costs: nothing that matters to their tests. The verifier package, its fixtures and the
+workflow file are theirs, in their repository, running in their CI, and disconnecting changes none
+of them. An administrator can download everything Balladeer holds at any time from workspace
+settings, and disconnecting hands them that same download in the response that ends access.
+
+Who can approve one: the named person who owns it, in their own browser. Not an administrator on
+their behalf, and never you.
+
+Whether it blocks a merge: no. The check is advisory on Balladeer's side, and their own branch
+protection is what decides whether a failing check stops anything.
+
+Who can invite people and change setup: a workspace administrator. A contributor can read the
+workspace and propose promises, and a viewer can read it. If somebody asks you to add a teammate,
+invite_teammate returns the page an administrator sends the invitation from, with the address filled
+in for them to read. The tool sends nothing itself: an administrator presses Send.`;
+/**
+ * How an agent turns a repository that has just been connected into a catalog a
+ * person can read. Setup's last step prints it, and the control plane's `/agent`
+ * page serves it byte for byte, so the instruction a connected agent reads on
+ * the page cannot drift from the one the command prints in the terminal.
+ *
+ * The runnable invocation is deliberately not in here. Only the server knows
+ * whether the package is published, and a playbook carrying a literal command
+ * would either name a registry version npm does not have or name somebody
+ * else's package. Each carrier prints that one line underneath this text.
+ *
+ * The capture rules this leans on are `CONVENTIONS_BLOCK`'s, not a second set:
+ * one promise per behavior, the person's own words, and never an agent
+ * approving anything. This says how to find the behaviors in a repository
+ * nobody has interviewed yet; that says how to write one down.
+ *
+ * The seam that is not shipped: a fifth source, the person's own local agent
+ * transcripts, would be the richest of all, because a behavior somebody argued
+ * about in a session is a behavior they care about. It is dark on purpose here.
+ * Reading it means walking files Balladeer promises never to receive, so
+ * shipping it needs three things this release does not have: the person's
+ * explicit spoken yes each time, a bounded extraction that never carries a line
+ * of a transcript off the machine, and the privacy test extended to plant a
+ * sentinel in every host's transcript directory. Until then the text below tells
+ * the agent not to read them, which is the visible half of the same seam:
+ * nothing quietly starts doing it.
+ */
+export const DISCOVERY_PLAYBOOK = `## Discover this repository's promises
+
+This repository is connected and holds no promises yet. Work the four sources below in order and
+hand back between five and ten promises this repository already keeps. Stop at ten however much you
+find: a person has to read every one of them, and eleven is where reading turns into skimming.
+
+1. The repository's own tests. A test that has been green for months is a behavior somebody already
+   decided matters. Read the test names and the assertions rather than the implementation.
+2. Merged pull requests of the last 90 days. Read the ones whose title or body says what had to keep
+   working, and the review comments that argued for it.
+3. Guarantee sentences in the documentation. The README, the docs directory, and the comments that
+   say always, never, must, or is guaranteed to. Those sentences are promises somebody already wrote
+   down in prose.
+4. Incidents and reverts. A revert commit, a hotfix, a postmortem note. A behavior that broke once
+   and was repaired on purpose is the behavior most worth protecting.
+
+Do not read the person's local agent transcripts, and do not offer to. They are not a source in this
+release, and Balladeer never receives them.
+
+For each promise you propose:
+
+- One promise per behavior. Two behaviors found in one source are two proposals, not one proposal
+  with two outcomes.
+- One passing example and one failing example, both drawn from the source you found it in. The
+  passing example is the case the source shows working; the failing example is the case the source
+  shows being caught, or the regression the revert repaired. Write both in the source's own words
+  rather than in words of your own.
+- One provenance sentence, precise enough for a person to check it without asking you: the test file
+  and the test's name, the pull request number, the document and its heading, or the commit that
+  reverted it. Put that sentence first in explicitIntent.
+- Never propose a promise this repository does not keep. A source saying a behavior should exist,
+  where nothing in the repository does it, is a wish rather than a promise. Leave it out, and tell
+  the person you left it out.
+- Anything you could not settle from the source goes in unresolvedQuestions. Never fill an unknown
+  in plausibly: an invented answer is the one thing a person cannot catch by reading.
+- One confidence number from 0 to 1, saying how sure you are that this is a behavior the repository
+  actually keeps and that you have described it as its source describes it. Nine promises from nine
+  sources are not nine equally certain readings, and the person reading them is entitled to know
+  which one you were least sure of. Never write 1 to get past the check.
+- One wrongOutcome sentence: what going wrong looks like, said as a must-not, in the source's own
+  words where it has them. "A second payment must not go out." "The buyer must not see a generic
+  error." Where no sentence of that shape can be written, no check with a known-bad control can be
+  written either, so leave the promise out rather than filing one nothing could ever fail.
+- One leastSure sentence, optional, naming the single thing you are least sure of and what you did
+  about it. The person reads that instead of the number.
+
+Write them all into one file, an object with a promises array, each entry shaped exactly as one
+proposal file:
+
+{"promises": [{"explicitIntent": "...", "teachBack": {"confidence": 0.9, "wrongOutcome": "...", "meaning": {"title": "..."}}}]}
+
+An entry carries explicitIntent and teachBack, and inside teachBack only meaning, confidence,
+wrongOutcome, leastSure, unresolvedQuestions, and proposedOwnerId. Anything else is refused on this
+machine before the file leaves it, and one bad entry means not one of them is sent.
+
+Every promise in the file is proposed as owned by whoever ran setup, and waits for that person. The
+command prints one link that opens all of them at once. Give the person that link and ask them to
+read each promise and click Agree. Nothing you can run agrees to one.
+
+File the whole catalog in one go with the discover subcommand, naming that file:`;