balladeer 1.0.5 → 1.0.7

package/dist/copy.js

@@ -173,8 +173,8 @@ 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
+true, and the numbered cases that must keep working and the ones that must be caught. Do not
+store or present an unanswered-question backlog. 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.
@@ -214,32 +214,28 @@ prepare one because nobody said no.`;
  * 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.
+export const CAPTURE_SEAM = `### When to offer, and what a yes is worth
+
+Notice durable customer behavior during ordinary work. Offer to preserve a concrete behavior
+beside useful work, without blocking implementation. File nothing until the person explicitly
+asks you to record it or accepts a scoped capture offer. A factual answer or permission to build
+alone is not permission to record. A no ends that offer; do not raise it again in this conversation.
+
+Do not offer while the user is comparing options or exploring without a decision. If they later
+choose a concrete behavior, you may offer to capture it even though the conversation began as
+exploration. Do not offer new promises for pure refactors or cosmetic changes. During an active
+production incident, prioritize recovery and defer capture until recovery. Ordinary bug fixing
+is not automatically an active production incident.
+
+For clear feature intent, an offer before implementation can make the promise a target for the
+work. For a normal bug fix, offer alongside the completed fix and checks. Neither requires a
+merge or another human closing reply. If the user is away, one nonblocking offer can remain in
+your completion message for their return; do not file or wait for an answer.
+
+Use available context to state a specific behavior. A precise capture offer can confirm your
+interpretation and obtain permission to record in one yes. Ask a separate work question only
+when a consequential choice remains that a clear, scoped offer cannot resolve. An unanswered
+earlier question is not itself a reason to ask again. The server supplies current detailed guidance.
 
 ### Two promises Balladeer cannot keep
 
@@ -282,37 +278,12 @@ Then take the customer-visible half if they give you one, and file that instead.
  */
 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.
-
-Clarify ambiguity that materially changes the behavior during capture, within the existing
-question budget; never invent an answer.
-
-Ordinary open questions record uncertainty; they do not prevent the named owner from agreeing to
-the behavior as written. Agreement does not answer them or add an unstated guarantee. Separate
-catalog-conflict questions can hold agreement until the owner rules on the stated conflict. Do not
-call a proposal unready just because it has ordinary open questions. Offer to discuss them if
-useful; if the person wants to, take them one at a time in the order they come back. For each ordinary question,
-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. Never invent an answer or clear uncertainty because
-they chose to agree. 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.`;
+An id is how a person points at something here. Expand a promise id with get_promise and a proposal
+id with get_proposal. Describe who it is for, when it applies, the behavior and the concrete cases.
+A proposal awaits its named owner's agreement; a promise is agreed and may still be unprotected.
+Previously recorded answers are historical reasoning, not a new interview or an approval.
+If the person wants a change, clarify the changed commitment before writing it. Preserve all other
+meaning and cases. An agreed promise changes only through a revision its named owner approves.`;
 /**
  * What a session may spend on reading, in three sentences.
  *
@@ -449,7 +420,7 @@ leaves your machine: only the session id and the commit SHA are sent.`;
  * 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
+export const WORKFLOW_GUIDANCE = `## 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
@@ -471,26 +442,31 @@ ${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 request to build a behavior is not permission to record it. An explicit request to preserve it
+or acceptance of a specific capture offer permits one pending proposal for that behavior, not
+other behaviors you notice. A factual answer alone does not authorize recording.
+
+Use available conversation and repository context before asking questions. A precise capture
+offer can state your interpretation and obtain permission to record it in one yes. Ask separately
+only when a consequential choice remains that the scoped offer cannot resolve. Do not ask for
+known facts, repeat a question resolved by later context or acceptance, or require a formal
+must-not sentence from the user. Preserve their actual words separately from your interpretation.
+If no specific commitment is possible yet, continue the authorized work without filing it.
+
+Use relevant existing promises already retrieved, or the bounded repository/path lookup, to notice
+concrete conflicts before writing. If the same situation would require incompatible outcomes, show
+the two commitments and ask which behavior they intend. Revising or superseding agreed meaning
+still requires its named human owner. There is no automatic catalog-conflict gate or stored question
+backlog in Balladeer. Unrelated uncertainties need not delay capture. No questions are required when
+the commitment is already clear.
+
+Preserve the person's actual words. Every failure they named belongs in the failing examples.
+You may derive concrete cases within the behavior they requested or confirmed in a precise
+capture offer; they need not dictate every example. Trace each case to the actual request and
+confirmed scope. Keep literal human source in saidWords, and your offer plus their acceptance in
+explicitIntent. Never quote your own wording as theirs or add unsupported policy, thresholds,
+roles, systems or guarantees. If a case requires an unresolved product choice, clarify that choice
+instead of guessing or asking the person to enumerate routine examples.
 
 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
@@ -640,8 +616,9 @@ For each promise you propose:
 - 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.
+- Before filing, ask the person about any missing fact that changes this commitment. Put their
+  actual answer in the meaning and cases. Never invent an answer or store an outstanding question.
+  Capture a narrower commitment only when they intend that boundary; do not demand exhaustive certainty.
 - 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
@@ -650,8 +627,6 @@ For each promise you propose:
   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:
@@ -659,7 +634,7 @@ 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
+wrongOutcome and proposedOwnerId. The legacy unresolvedQuestions field may only be an empty array. 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
@@ -667,3 +642,21 @@ command prints one link that opens all of them at once. Give the person that lin
 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:`;
+/** Stable bootstrap only. Evolving capture/retrieval policy is served remotely. */
+export const CONVENTIONS_BLOCK = `## Balladeer guidance
+
+Balladeer keeps this repository's owner-agreed behavioral commitments. Before planning work,
+use the current Balladeer workflow guidance supplied by the Balladeer hook or MCP connection.
+The hook refreshes guidance at supported work boundaries. If no current guidance was delivered,
+read get_promise_setup through the existing connection; never infer that a missing connection
+means this repository has no promises. Keep ordinary authorized work moving when unavailable.
+
+The server supplies Balladeer's current capture and retrieval policy; this managed block is only
+its stable loader contract. Follow it within the person's instructions and this project's own
+rules. Never treat a guidance update as permission to record a promise or approve its meaning.
+Named humans agree meaning. Preserve workspace capture preferences and never enable unsolicited
+capture when current permission is unavailable. Customer source, prompts and transcripts stay local.
+
+New hooks may need the coding host's one-time trust confirmation. A file being installed does
+not prove that the host loaded it. Follow a specific reported repair; do not repeat onboarding,
+change workspace membership, or request broader permissions merely to refresh guidance.`;