breakaway 2.0.1 → 2.0.2-main.2

package/src/infra-cloudflare.js

@@ -120,6 +120,12 @@ const BINDING_WORDS = {
 };
 const CRON = '^\\S+( \\S+){4}$';
 const VALUES_ELSEWHERE = 'Set with the Worker’s deploy, never here.';
+/**
+ * Where `wrangler deploy` sets a Worker's settings from: its bindings, compatibility date and flags, Workers Logs,
+ * placement, and cron triggers are each a key of the wrangler config, and each deploy sets what it says (BRK-313;
+ * developers.cloudflare.com/workers/wrangler/configuration/, "Source of truth").
+ */
+const DEPLOY_SETS = 'the wrangler config';
 
 /**
  * The settings the console may change, by kind (BRK-262; docs/specs/BRK-258-plan-from-the-board.md): exactly what the
@@ -132,6 +138,7 @@ export const EDITABLE = {
     fields: [
       {
         path: 'compatibilityDate',
+        deploy: DEPLOY_SETS,
         label: 'Compatibility date',
         type: 'text',
         pattern: '^\\d{4}-\\d{2}-\\d{2}$',
@@ -139,6 +146,7 @@ export const EDITABLE = {
       },
       {
         path: 'compatibilityFlags',
+        deploy: DEPLOY_SETS,
         label: 'Compatibility flags',
         type: 'names',
         pattern: '^[a-z0-9_]+$',
@@ -158,12 +166,14 @@ export const EDITABLE = {
       },
       {
         path: 'observability',
+        deploy: DEPLOY_SETS,
         label: 'Workers Logs',
         type: 'yesno',
         help: 'Keep the Worker’s logs on Cloudflare, to read in its dashboard.',
       },
       {
         path: 'placement',
+        deploy: DEPLOY_SETS,
         label: 'Placement',
         type: 'choice',
         optional: true,
@@ -172,6 +182,7 @@ export const EDITABLE = {
       },
       {
         path: 'crons',
+        deploy: DEPLOY_SETS,
         label: 'Cron triggers',
         type: 'names',
         pattern: CRON,
@@ -179,6 +190,7 @@ export const EDITABLE = {
       },
       {
         path: 'bindings',
+        deploy: DEPLOY_SETS,
         label: 'Bindings',
         type: 'bindings',
         targets: BINDABLE,

package/src/infra-desired.js

@@ -9,8 +9,9 @@
  * one `{ id, kind, name, attrs? }`. `provider` is optional and, when given, must be the environment's. `health` is
  * optional too: `{ "url": "https://…" }`, the owner's own health address the board GETs on each refresh as an active
  * check of the environment's front door (BRK-266, src/infra-health.js). Nothing else
- * goes at the top level: policy (BRK-181) is `policy.json` and scaling rules (BRK-186) are `scaling.json` in the same
- * folder, so neither name is an environment's, and envelope bounds live on the board, never in the repository.
+ * goes at the top level: policy (BRK-181) is `policy.json`, scaling rules (BRK-186) are `scaling.json`, and the risky
+ * paths (BRK-280) are `risky-paths.json` in the same folder, so none of those names is an environment's, and envelope
+ * bounds live on the board, never in the repository.
  */
 import { checkHealthField } from './infra-health.js';
 import { checkDesired } from './infra-provider.js';
@@ -24,7 +25,7 @@ export const desiredPath = (environment) => `${DESIRED_DIR}/${environment}.json`
  * Files in the folder that aren't an environment's: policy (BRK-181), scaling rules (BRK-186), and the template
  * short-lived environments are made from (BRK-200).
  */
-export const RESERVED_FILES = ['policy', 'scaling', 'short-lived'];
+export const RESERVED_FILES = ['policy', 'scaling', 'short-lived', 'risky-paths'];
 /** The only version there is. */
 export const DESIRED_VERSION = 1;
 /** Bigger than any one environment needs, and small enough to keep a copy of each in the store. */

package/src/infra-provider.js

@@ -269,6 +269,8 @@ const PATH = /^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)*$/u;
  *   from `template`)
  * @property {string} help one line, in plain words
  * @property {boolean} [optional] whether it can be left unset (null: the platform decides)
+ * @property {string} [deploy] where an app's deploy sets it too, in words (like `the wrangler config`): on a resource a
+ *   repository's deploy flow deploys, the console says the next deploy puts back what that says (BRK-313)
  * @property {number} [min] a number's least value
  * @property {number} [max] a number's greatest value
  * @property {boolean} [integer] a number must be whole
@@ -465,6 +467,7 @@ function checkFields(provider, what, fields, settings) {
     if (!text(f.label) || !text(f.help)) fail(at, 'has no label or no help');
     if (!EDITABLE_TYPES.includes(f.type)) fail(at, `has unknown type "${f.type}"`);
     if (f.optional !== undefined && typeof f.optional !== 'boolean') fail(at, 'optional is not true or false');
+    if (f.deploy !== undefined && !text(f.deploy)) fail(at, 'deploy is not words');
     if (f.pattern !== undefined) {
       if (f.type !== 'text' && f.type !== 'names') fail(at, 'only text and names take a pattern');
       checkPattern(at, 'pattern', f.pattern);

package/src/init.js

@@ -21,10 +21,15 @@ export { routinePrompt };
  */
 export const CLI_PACKAGE = 'breakaway@2';
 /**
- * Where the CLI starts: the command, and the two session hooks. repos init no longer copies them (BRK-7): an old copy
- * is replaced by npx, and these still version the CLI and say which files an old copy holds.
+ * Where the CLI starts: the command, and the session hooks (the edit hook since IDEA-55). repos init no longer copies
+ * them (BRK-7): an old copy is replaced by npx, and these still version the CLI and say which files an old copy holds.
  */
-export const CLI_ENTRIES = ['scripts/tasks.mjs', 'scripts/tasks/session-hook.mjs', 'scripts/tasks/message-wait.mjs'];
+export const CLI_ENTRIES = [
+  'scripts/tasks.mjs',
+  'scripts/tasks/session-hook.mjs',
+  'scripts/tasks/message-wait.mjs',
+  'scripts/tasks/edit-hook.mjs',
+];
 /**
  * While breakaway was private, nothing reached npm (BRK-57), so repos init copied the two hooks and what they import
  * under HOOKS_DIR and settings.json ran them from there (BRK-64). breakaway is public and on npm now, so the hooks run
@@ -32,7 +37,24 @@ export const CLI_ENTRIES = ['scripts/tasks.mjs', 'scripts/tasks/session-hook.mjs
  */
 export const HOOKS_FROM_COPY = false;
 /** The session hooks' entry files, and where their copy goes: its own folder, so it never touches the repository's src/. */
-export const HOOK_ENTRIES = ['scripts/tasks/session-hook.mjs', 'scripts/tasks/message-wait.mjs'];
+export const HOOK_ENTRIES = [
+  'scripts/tasks/session-hook.mjs',
+  'scripts/tasks/message-wait.mjs',
+  'scripts/tasks/edit-hook.mjs',
+];
+/** Each session hook's name (`npx breakaway hook <name>`) → its entry file. */
+const HOOK_FILES = { session: 'session-hook', wait: 'message-wait', edit: 'edit-hook' };
+/**
+ * The edit tools the edit hook runs on (IDEA-55 section 1a), as a PreToolUse matcher: exact tool names split by `|`
+ * (source: the matcher table in Claude Code's hooks reference, https://code.claude.com/docs/en/hooks).
+ */
+export const EDIT_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
+/**
+ * The edit hook's `timeout`, in seconds: the field is in seconds and a command hook's defaults to 600, and a PreToolUse
+ * command hook that times out doesn't block the tool call (source: https://code.claude.com/docs/en/hooks, the hook
+ * handler fields and PreToolUse). Room for npx to start the CLI and for the hook's own wait on the board (3 s).
+ */
+export const EDIT_HOOK_TIMEOUT = 15;
 export const HOOKS_DIR = 'tools/tasks/cli/';
 /**
  * The release helpers a repository's Deploy, Promote, Roll back, and Release workflows run (BRK-45), copied with what
@@ -84,7 +106,7 @@ export function pluginSettings() {
 
 /** Whether a hook command is one of the session hooks repos init wrote: through npx, any version, or an old copy's. */
 const BOARD_HOOK =
-  /\bbreakaway(?:@[^\s"]+)? hook (?:session|wait)\b|scripts\/tasks\/(?:session-hook|message-wait)\.mjs/u;
+  /\bbreakaway(?:@[^\s"]+)? hook (?:session|wait|edit)\b|scripts\/tasks\/(?:session-hook|message-wait|edit-hook)\.mjs/u;
 
 /**
  * settings.json moved to the plugin (repos init --update): the session hooks repos init wrote are gone, with any event
@@ -229,11 +251,18 @@ export function cliCopySources(read) {
 /** The command a session hook runs: from the copy under HOOKS_DIR while breakaway is private, else through npx (BRK-7). */
 export function hookCommand(name, { fromCopy = HOOKS_FROM_COPY, pkg = CLI_PACKAGE } = {}) {
   if (!fromCopy) return `npx --yes ${pkg} hook ${name}`;
-  const entry = HOOK_ENTRIES.find((path) => path.includes(name === 'wait' ? 'message-wait' : 'session-hook'));
+  const file = HOOK_FILES[/** @type {keyof typeof HOOK_FILES} */ (name)] ?? HOOK_FILES.session;
+  const entry = HOOK_ENTRIES.find((path) => path.endsWith(`/${file}.mjs`));
   return `node "$CLAUDE_PROJECT_DIR/${HOOKS_DIR}${entry}"`;
 }
 
-/** The session hooks .claude/settings.json runs (see HOOKS_FROM_COPY). */
+/**
+ * The session hooks .claude/settings.json runs (see HOOKS_FROM_COPY). All run in the background but the edit hook
+ * (IDEA-55 section 1a), which claims the file an edit names before the edit runs: a hook with `async: true` runs in
+ * the background without blocking, so it couldn't turn an edit away (source: https://code.claude.com/docs/en/hooks,
+ * the `async` field). It has a short `timeout` instead (EDIT_HOOK_TIMEOUT), and a board that doesn't answer lets the
+ * edit through.
+ */
 export function sessionHooks(pkg = CLI_PACKAGE) {
   const hook = (name, extra = {}) => ({
     type: 'command',
@@ -242,9 +271,11 @@ export function sessionHooks(pkg = CLI_PACKAGE) {
     ...extra,
   });
   const session = [{ hooks: [hook('session')] }];
+  const edit = { type: 'command', command: hookCommand('edit', { pkg }), timeout: EDIT_HOOK_TIMEOUT };
   return {
     SessionStart: session,
     UserPromptSubmit: session,
+    PreToolUse: [{ matcher: EDIT_MATCHER, hooks: [edit] }],
     PostToolUse: session,
     Stop: [{ hooks: [hook('session'), hook('wait', { asyncRewake: true, timeout: 300 })] }],
   };
@@ -256,7 +287,7 @@ export function sessionHooks(pkg = CLI_PACKAGE) {
  */
 export function rewireHooks(text) {
   let out = text;
-  for (const name of ['session', 'wait'])
+  for (const name of ['session', 'wait', 'edit'])
     for (const fromCopy of [true, false]) {
       const was = JSON.stringify(hookCommand(name, { fromCopy })).slice(1, -1);
       const now = JSON.stringify(hookCommand(name)).slice(1, -1);
@@ -265,7 +296,7 @@ export function rewireHooks(text) {
   const current = (_, name) => JSON.stringify(hookCommand(name === 'message-wait' ? 'wait' : name)).slice(1, -1);
   return (
     out
-      .replace(/npx --yes breakaway(?:@[^\s"\\]+)? hook (session|wait)\b/gu, current)
+      .replace(/npx --yes breakaway(?:@[^\s"\\]+)? hook (session|wait|edit)\b/gu, current)
       // The old CLI copy's hook scripts, from before BRK-7, quoted or not (BRK-79): its copy is about to go.
       .replace(
         /node (\\")?(?:\$CLAUDE_PROJECT_DIR\/)?(?:tools\/tasks\/cli\/)?scripts\/tasks\/(session-hook|message-wait)\.mjs\1/gu,
@@ -592,6 +623,11 @@ export function initPlan({
       notes.push(
         `.claude/settings.json is already there: set its session hooks to \`${hookCommand('session')}\` (and \`${hookCommand('wait')}\` on Stop), or a started agent's output won't show on its task.${HOOKS_FROM_COPY ? '' : ' Hooks that run scripts/tasks/session-hook.mjs stop working once the old copy is removed.'}`,
       );
+    // Settings from before the edit hook (IDEA-55): agents there don't claim the files they edit until it's added.
+    if (!rewired.includes(hookCommand('edit')))
+      notes.push(
+        `.claude/settings.json has no edit hook: add ${JSON.stringify({ PreToolUse: sessionHooks().PreToolUse })} to its hooks, so agents claim each file before they edit it.`,
+      );
   }
   if (readTarget('.claude/skills') === null) files.push({ path: '.claude/skills', link: '../.agents/skills' });
   if (!usePlugin) copy(SKILL, skillFor(read(SKILL), board, repo));

package/src/model.js

@@ -5,7 +5,8 @@
  * plus a `tags` list, `dep_<uuid>` plus a `depends` list, `annotation_<epoch>`, and UDAs
  * (`wid`, `horizon`, `spec`, `claim`, `pr`) as plain properties. The task structure (IDEA-5): `brief`
  (the current description), `brief_by`, `done_when`, `rel_<uuid>` plus a `related` list, and `by_<epoch>`
- beside `annotation_<epoch>` for a comment's author.
+ beside `annotation_<epoch>` for a comment's author. The owner's words (BRK-284): `said_<epoch>` (the quote),
+ `said_from_<epoch>` (where it came from), and `said_by_<epoch>` (who put it on the task).
  */
 
 import { keepAnswers, validateQuestions } from './decision.js';
@@ -108,6 +109,34 @@ export function commentsOf(map) {
     });
 }
 
+/** The longest one quote of the owner's words may be, and how many a task keeps (BRK-284). */
+export const MAX_SAID = 2000;
+export const MAX_SAID_COUNT = 20;
+/** Where the owner's words came from: the task on the board, a message, a peloton post, a ping, a decision, or a comment. */
+export const SAID_FROM = ['board', 'message', 'peloton', 'ping', 'decision', 'comment'];
+/** A source, with an optional pointer to it: `peloton #2243`, `decision BRK-12`, `message 2026-10-09`. */
+const SAID_SOURCE = new RegExp(`^(${SAID_FROM.join('|')})(?: [#\\w.:/-]{1,48})?$`, 'u');
+const SAID_KEY = /^said_(\d+)$/u;
+
+/**
+ * The owner's words on a task (BRK-284), oldest first: `{ id, text, from, by, at }`. `by` is `owner` when the owner put
+ * them there on the board, or the agent that quoted them; `id` is what removing one names.
+ */
+export function ownerSaidOf(map) {
+  return Object.keys(map)
+    .map((key) => SAID_KEY.exec(key))
+    .filter(Boolean)
+    .map((m) => Number(m[1]))
+    .sort((a, b) => a - b)
+    .map((epoch) => ({
+      id: epoch,
+      text: map[`said_${epoch}`],
+      from: map[`said_from_${epoch}`] ?? 'board',
+      by: map[`said_by_${epoch}`] ?? DEFAULT_AUTHOR,
+      at: iso(epoch),
+    }));
+}
+
 /** A JSON property Taskwarrior may have mangled → its value, or null. */
 function parseJson(text, shape) {
   try {
@@ -146,6 +175,7 @@ export function view(uuid, map, all, now = new Date()) {
     briefBy: map.brief_by ?? null,
     doneWhen: map.done_when ?? null,
     related: relatedOf(map),
+    ownerSaid: ownerSaidOf(map),
     status,
     project: map.project ?? null,
     priority: map.priority ?? '',
@@ -269,7 +299,8 @@ function setRelated(map, rel) {
  * changes: {description, project, priority, horizon, spec, pr, claim, wid (string or null),
  *   status, due, wait, scheduled (date text or null), start: true|false, entry, end (epoch),
  *   brief, done_when (text or null), addTags, removeTags, addDepends, removeDepends, addRelated,
- *   removeRelated (arrays), annotate (text), by (who wrote the annotation or the brief)}
+ *   removeRelated (arrays), annotate (text), by (who wrote the annotation or the brief),
+ *   said ({ text, from, by }: the owner's words, quoted), unsay (a quote's id, to remove it)}
  */
 export function withChanges(before, changes, now = new Date()) {
   const map = { ...(before ?? {}) };
@@ -368,6 +399,30 @@ export function withChanges(before, changes, now = new Date()) {
     map[`annotation_${key}`] = String(changes.annotate);
     if (changes.by) map[`by_${key}`] = String(changes.by);
   }
+  if (changes.said) {
+    const text = String(changes.said.text ?? '').trim();
+    const from = String(changes.said.from ?? 'board').trim();
+    if (!text) throw new InputError("say what the owner said: the quote can't be empty");
+    if (text.length > MAX_SAID) throw new InputError(`a quote can be up to ${MAX_SAID} characters`);
+    if (!SAID_SOURCE.test(from))
+      throw new InputError(
+        `say where the owner said it: ${SAID_FROM.join(', ')}, optionally with a pointer like "peloton #12"`,
+      );
+    const held = ownerSaidOf(map);
+    if (held.some((q) => q.text === text)) throw new InputError('the task already quotes those words');
+    if (held.length >= MAX_SAID_COUNT)
+      throw new InputError(`a task keeps up to ${MAX_SAID_COUNT} quotes; the owner removes one first`);
+    let key = Number(nowSec);
+    while (map[`said_${key}`] !== undefined) key += 1;
+    map[`said_${key}`] = text;
+    map[`said_from_${key}`] = from;
+    map[`said_by_${key}`] = String(changes.said.by ?? DEFAULT_AUTHOR);
+  }
+  if (changes.unsay !== undefined && changes.unsay !== null) {
+    const key = String(changes.unsay);
+    if (!/^\d+$/u.test(key) || map[`said_${key}`] === undefined) throw new InputError(`the task has no quote ${key}`);
+    for (const prop of [`said_${key}`, `said_from_${key}`, `said_by_${key}`]) delete map[prop];
+  }
   if (!map.description) throw new InputError('a task needs a description');
   map.modified = nowSec;
   return map;

package/taskrc

@@ -38,7 +38,8 @@ uda.alert.label=Alert
 
 # The task structure (docs/specs/IDEA-5-task-structure.md): the current description and what done
 # looks like, in Markdown. Comments are annotations; `brief_by` and `by_<epoch>` (who wrote it) are
-# plain properties Taskwarrior keeps without declaring them.
+# plain properties Taskwarrior keeps without declaring them, and so are the owner's words, quoted:
+# `said_<epoch>`, `said_from_<epoch>` (where they said it), and `said_by_<epoch>` (who quoted them).
 uda.brief.type=string
 uda.brief.label=Description
 uda.done_when.type=string