@nanocollective/roster 0.1.0-alpha.5 → 0.1.0-alpha.7

package/templates/ops/compose.mjs

@@ -186,6 +186,12 @@ function parseScalar(raw, line) {
 
 const MAX_INCLUDE_DEPTH = 8;
 
+/* A partial's output is scanned again by the template that included it, so a value containing
+   `{{` would be rendered as though somebody had written it into a prompt: a PR title saying
+   `{{nope}}` failed the run, and one saying `{{> some/file}}` read that file in. Values are
+   fenced off with a character no template can contain, and let back out once, at the end. */
+const FENCE = "\u0000";
+
 export function render(template, ctx, readPartial, depth = 0) {
   if (depth > MAX_INCLUDE_DEPTH) throw new Error("include depth exceeded; a partial probably includes itself");
 
@@ -220,10 +226,10 @@ export function render(template, ctx, readPartial, depth = 0) {
       }
       throw new Error(`unknown or empty placeholder: {{${path}}}`);
     }
-    return String(v);
+    return String(v).replace(/\{\{/g, FENCE);
   });
 
-  return out;
+  return depth === 0 ? out.replaceAll(FENCE, "{{") : out;
 }
 
 function lookup(ctx, path) {
@@ -282,7 +288,7 @@ function defaultMarker(name) {
 // Composition
 // ---------------------------------------------------------------------------
 
-export function compose({ opsDir, brainsDir, staff, kind }) {
+export function compose({ opsDir, brainsDir, staff, kind, runDir }) {
   const org = parseYaml(readFileSync(join(opsDir, "org.yaml"), "utf8"), "org.yaml");
 
   const entry = (org.staff ?? []).find((s) => s.handle === staff);
@@ -317,6 +323,12 @@ export function compose({ opsDir, brainsDir, staff, kind }) {
   // sends it to a 404 before it has read anything. So the absence is a value of its own.
   if (Object.keys(event).length) event = { ...event, no_comment: !event.comment_id };
 
+  // What people have open on the product repos, gathered by inflight.mjs just before this runs.
+  // Read as a value and never rendered as a template: it is PR titles, which are a person's
+  // words, and a `{{` in one must not be able to break composition.
+  const inflightFile = join(runDir ?? join(brainsDir, ".roster-run"), "inflight.md");
+  const inflight = existsSync(inflightFile) ? readFileSync(inflightFile, "utf8").trim() : "";
+
   const humans = readHumans(org);
   const ctx = {
     org,
@@ -344,6 +356,7 @@ export function compose({ opsDir, brainsDir, staff, kind }) {
     // without the one the prose already names. Empty when there is only one, which is what
     // makes `{{#if humans_extra}}` the right way to mention the others at all.
     human_list: humanSentence(humans),
+    inflight,
     humans_extra: humanSentence(humans.slice(1)),
   };
 

package/templates/ops/inflight.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// Finds the pull requests people have open on a staff member's product repos, before the prompt
+// is composed, so the agent knows what a human is in the middle of changing.
+//
+// Written because nothing told them. While a person had a long branch open rewriting a product's
+// copy, the staff opened five pull requests and nine issues chasing that same copy, and four of
+// those pull requests were overtaken by the branch. Each one was reasonable on its own; none of
+// them could see the branch.
+//
+// Vendored alongside compose.mjs for the same reason: it runs on the runner, and must not depend
+// on npm. It asks GitHub through `gh`, which every runner has, and it never fails a run: with no
+// answer the prompt simply has no section about it.
+//
+// Usage:  node roster-ops/inflight.mjs --staff cto --ops roster-ops --brains . --out .roster-run/inflight.md
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseYaml } from "./compose.mjs";
+
+/** Enough to see an overlap without reading a 37,000-line branch into the prompt. */
+const MAX_PRS = 10;
+const MAX_FILES = 20;
+const MAX_DIRS = 6;
+
+/**
+ * A person, rather than one of this org's Apps or anybody else's automation.
+ *
+ * `gh` marks an App author as a bot and names it `app/<slug>`; a bot's own login ends `[bot]`.
+ * A machine user is none of those, which is why the org's own bot logins are passed in too.
+ */
+export function isHuman(author, bots = []) {
+  if (!author) return false;
+  const login = String(author.login ?? "");
+  if (!login || author.is_bot) return false;
+  if (login.startsWith("app/") || /\[bot\]$/i.test(login)) return false;
+  const bare = (s) => String(s).toLowerCase().replace(/\[bot\]$/, "").replace(/^app\//, "");
+  return !bots.some((b) => bare(b) === bare(login));
+}
+
+/** The repos a staff member works in: their own `works_in`, or else every product repo. */
+export function productRepos(org, manifest) {
+  const own = (manifest?.works_in ?? []).map((w) => String(w?.repo ?? "")).filter(Boolean);
+  if (own.length) return own;
+  return (org.repos ?? []).filter((r) => r.role === "product").map((r) => `${org.org}/${r.name}`);
+}
+
+/** The top directories a change touches, so a wide one reads as "the copy" rather than a list. */
+function directories(paths) {
+  const counts = new Map();
+  for (const p of paths) {
+    const parts = p.split("/");
+    const dir = parts.length === 1 ? "(root)" : parts.slice(0, Math.min(2, parts.length - 1)).join("/") + "/";
+    counts.set(dir, (counts.get(dir) ?? 0) + 1);
+  }
+  return [...counts].sort((a, b) => b[1] - a[1]).slice(0, MAX_DIRS);
+}
+
+function days(iso, now) {
+  const d = Math.floor((now - new Date(iso).getTime()) / 86400_000);
+  return d <= 0 ? "today" : d === 1 ? "1 day" : `${d} days`;
+}
+
+/**
+ * The markdown the prompt carries, or "" for nothing in flight.
+ *
+ * Titles are a person's words and go in as data: compose.mjs substitutes this file as a value,
+ * never renders it as a template, so a `{{` in a title cannot break a run.
+ */
+export function describe(found, now = Date.now()) {
+  const lines = [];
+  for (const { repo, prs } of found) {
+    for (const pr of prs.slice(0, MAX_PRS)) {
+      const paths = (pr.files ?? []).map((f) => f.path).filter(Boolean);
+      const total = Math.max(pr.changedFiles ?? 0, paths.length);
+      const title = String(pr.title ?? "").replace(/\s+/g, " ").trim();
+      lines.push(
+        `- **${repo}#${pr.number}** "${title}" by @${pr.author.login}, open ${days(pr.createdAt, now)}` +
+          `, branch \`${pr.headRefName}\`${pr.isDraft ? ", draft" : ""}, ${total} file${total === 1 ? "" : "s"}`,
+      );
+      if (!paths.length) continue;
+      if (total > MAX_FILES) {
+        lines.push(`  - mostly under ${directories(paths).map(([d, n]) => `\`${d}\` (${n})`).join(", ")}`);
+      }
+      const shown = paths.slice(0, MAX_FILES).map((p) => `\`${p}\``).join(", ");
+      const more = total - Math.min(paths.length, MAX_FILES);
+      lines.push(`  - ${shown}${more > 0 ? `, and ${more} more` : ""}`);
+    }
+    if (prs.length > MAX_PRS) lines.push(`- and ${prs.length - MAX_PRS} more open on ${repo}`);
+  }
+  return lines.length ? lines.join("\n") + "\n" : "";
+}
+
+/** Everything open by a person, per repo. `gh` is passed in so a test never needs the network. */
+export function gather({ org, manifest, gh }) {
+  const bots = [manifest?.bot, manifest?.public_bot].filter(Boolean);
+  const out = [];
+  for (const repo of productRepos(org, manifest)) {
+    let raw;
+    try {
+      raw = gh([
+        "pr",
+        "list",
+        "--repo",
+        repo,
+        "--state",
+        "open",
+        "--limit",
+        "50",
+        "--json",
+        "number,title,author,createdAt,headRefName,isDraft,changedFiles,files",
+      ]);
+    } catch (err) {
+      // One unreadable repo is not a reason to say nothing about the others.
+      console.error(`::warning::inflight: ${repo}: ${String(err.message).split("\n")[0]}`);
+      continue;
+    }
+    const prs = JSON.parse(raw || "[]")
+      .filter((pr) => isHuman(pr.author, bots))
+      // Oldest first: the long-lived branch is the one most likely to be overtaking everybody.
+      .sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+    if (prs.length) out.push({ repo, prs });
+  }
+  return out;
+}
+
+function main(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 2) args[argv[i].replace(/^--/, "")] = argv[i + 1];
+  if (!args.staff) throw new Error("--staff is required");
+  const opsDir = resolve(args.ops ?? ".");
+  const org = parseYaml(readFileSync(join(opsDir, "org.yaml"), "utf8"), "org.yaml");
+  const entry = (org.staff ?? []).find((s) => s.handle === args.staff);
+  if (!entry) throw new Error(`org.yaml has no staff member "${args.staff}"`);
+  const manifestPath = join(resolve(args.brains ?? ".."), entry.dir ?? entry.handle, "staff.yaml");
+  const manifest = existsSync(manifestPath)
+    ? parseYaml(readFileSync(manifestPath, "utf8"), "staff.yaml")
+    : {};
+
+  const gh = (a) => execFileSync("gh", a, { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 });
+  const text = describe(gather({ org, manifest, gh }));
+  const out = resolve(args.out ?? ".roster-run/inflight.md");
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, text);
+  process.stdout.write(text || "no human pull requests open on the product repos\n");
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+  try {
+    main(process.argv.slice(2));
+  } catch (err) {
+    // Never the reason a run fails. Without it the prompt has no section, which is how every
+    // run went before this existed.
+    console.error(`::warning::inflight: ${err.message}`);
+  }
+}

package/templates/ops/org/operating.md

@@ -15,13 +15,33 @@ question instead of doing work has wasted its slot.
 - **Never end a run blocked.** If everything on the list is genuinely blocked, do the most useful
   unblocked thing you can find and say so in the report.
 
+## Choosing work
+
+- **Serve the priorities.** Work that serves none of the ranked priorities in `org/priorities.md`
+  waits, unless something is broken. Say which priority a PR serves.
+- **Product before process.** Guards, checks, claim-policing and measuring your own output earn a
+  run when they protect something that has shipped. Most runs should move the product forward; if
+  your last few went on meta-work, this one does not.
+
+## Keeping your tracker clean
+
+{{human.name}} should never have to ask whether an issue can be closed.
+
+- **Close your own issues** when the work is done or superseded, with one line naming what closed
+  it: the PR, the commit, or the issue that replaced it. Do not leave one open "in case".
+- **Sweep them on every daily run.** Read every open issue you opened; close what is finished or
+  stale, and fold duplicates into one.
+- **Ideas live in your brain, not on the tracker.** Park a speculative idea as one line in
+  `strategy/ideas.md`. Open an `IDEA:` issue only when it needs a ruling, and never more than one
+  at a time.
+
 ## What you may not do
 
 - **You cannot ship to the outside world.** Anything public goes through {{human.name}}. The gate is
   mechanical rather than a promise: protected branches mean you open a PR and their merge is the
   approval. **Do not look for a way around it.** Being unable to ship unreviewed is what earns the
   autonomy.
-- **Never close a `decision` issue.** Those are {{human.name}}'s rulings to close.
+- **Never close a `decision` issue**, even in a sweep. Those are {{human.name}}'s rulings to close.
 - **Never `git add -A` in another staff member's repo, or in a repo where a human may have work in
   flight.** Stage explicit paths. Doing otherwise has swept someone else's uncommitted work into an
   unrelated commit.

package/templates/ops/org/voice.md

@@ -12,6 +12,15 @@ bodies, run reports, briefs to other staff, and how you talk to them in a sessio
 - **An issue title is the ask, not the topic.**
 - **Say the default** on anything needing a ruling: what you do if they say nothing.
 
+**Length ceilings.** Lead with the outcome or the ask, then stop at:
+
+- **A comment or reply: 100 words.** Most need three lines.
+- **An issue or PR body: 200 words.**
+- **The pinned status issue: 300 words**, readable on one phone screen.
+
+Past the ceiling, the detail goes in a file in your brain and the comment links to it in one
+line. A status {{human.name}} has to rewrite before they can use it has cost more than it saved.
+
 **Cut on sight:**
 
 - Context they already have. They founded this; it does not need explaining to them.

package/templates/ops/prompts/_inflight.md

@@ -0,0 +1,14 @@
+{{#if inflight}}
+## Human work in flight
+
+People have these pull requests open on the product repos, and each one is theirs. A long-lived
+branch is usually rewriting what you would otherwise be about to change.
+
+- **Do not open competing work on files they touch**: no pull request, and no issue asking for a
+  change there. It gets overtaken when their branch lands, and it costs them a review first.
+- **If you have something to say about that work, say it on their pull request**, briefly, and
+  leave the decision to them.
+- If today's task sits on those files, say so in your report and take the next thing.
+
+{{inflight}}
+{{/if}}

package/templates/ops/prompts/_paths.md

@@ -5,7 +5,8 @@ repos sit side by side inside it:
 
 - `{{staff.dir}}/` - your brain. **Start by reading it.**
 - `{{ops.dir}}/` - the org's shared brain: `org/operating.md`, `org/voice.md`, `org/guardrails.md`,
-  `org/business.md`. **Read-only to you.** Propose a change as a PR; do not edit it in place.
+  `org/business.md`, `org/priorities.md`. **Read-only to you.** Propose a change as a PR; do not
+  edit it in place.
 {{#if peers}}
 {{peer_list}}
 {{/if}}

package/templates/ops/prompts/daily.md

@@ -33,11 +33,15 @@ your brain. Reconstitute yourself, do a day's work, hand off.
    **Do not read `log/decisions.md` at boot**; it is the audit trail, for when you need to know why
    something was decided.
 
+{{> prompts/_inflight.md}}
+{{>? org/priorities.md}}
+
 ## Then work. Autonomously.
 
-Take the top item off #{{staff.status_issue}}'s ordered list, unless something above changed the
-priority, in which case say so in your report and do the more urgent thing. **Then actually do it.**
-You are not writing a plan for {{human.name}} to approve.
+Take the top item off #{{staff.status_issue}}'s ordered list that serves the org's priorities
+(`org/priorities.md`, where there is one), unless something above changed the priority, in which
+case say so in your report and do the more urgent thing. **Then actually do it.** You are not
+writing a plan for {{human.name}} to approve.
 
 {{> org/operating.md}}
 
@@ -48,15 +52,16 @@ You are not writing a plan for {{human.name}} to approve.
 {{#if staff.product}}
 1. **Open the PR** on `{{staff.product.repo}}` if you produced anything there, from a branch:
    `GH_TOKEN=${{staff.public_token_env}} gh pr create --repo {{staff.product.repo}} ...`
-   **Body: what it does, what the gate covered, what it did not cover. Nothing else** - no design
-   essay, no narration of how you built it. It is reviewed on a phone and the diff is right there.
+   **Body: which priority it serves, what it does, what the gate covered, what it did not cover.
+   Nothing else** - no design essay, no narration of how you built it. It is reviewed on a phone
+   and the diff is right there.
 {{/if}}
 2. **Rewrite pinned issue #{{staff.status_issue}} "Where we are"**: the situation in a line, what
    this run did, what the next run picks up in priority order. **It is a handover for the next run,
    not a diary.** Rewrite it, do not append, and cut anything the next run can find for itself.
 3. **Reconcile the tracker.** Open issues for anything new needing {{human.name}}, labelled by owner
-   plus kind, assigned to `{{human.github}}`. Close what genuinely completed, citing evidence.
-   **Never close a `decision` issue.** **Comments and replies get the same concision as everything
+   plus kind, assigned to `{{human.github}}`. Sweep every open issue you opened: close what is done
+   or superseded, citing what closed it. **Comments and replies get the same concision as everything
    else:** what changed and what it means for them. A comment that only says an issue is still open
    is not worth the notification.
 4. **Update `{{staff.dir}}/memory/` only if a fact or watch-out changed.** A new fact is **one line**
@@ -64,6 +69,10 @@ You are not writing a plan for {{human.name}} to approve.
    with "updated:". If it needs an argument, that goes in `memory/notes/<slug>.md` and the line stays
    one line. **Delete any line that no longer changes a decision** and say so in the decision log.
    If the run was purely work, touch nothing.
+   **Then check the budget:** `wc -c {{staff.dir}}/memory/INDEX.md {{staff.dir}}/log/decisions.md`.
+   Over 24KB either, or any fact over 400 characters (unless a `memory:` block in `staff.yaml` or
+   `org.yaml` sets other limits), and pruning is this run's job: delete, shorten, move arguments
+   to notes, and roll older decisions into `log/decisions/<YYYY-MM>.md`.
 5. **Log real decisions** in `{{staff.dir}}/log/decisions.md`, dated, newest at top, with the why.
 {{#if peers}}
 6. **Write to the other staff** if anything shipped, changed or broke that touches their patch.

package/templates/ops/prompts/mention.md

@@ -35,6 +35,8 @@ An issue opened this way often carries a pull request somewhere else, and says w
 
 `gh issue view --comments` is broken; use `gh api` as above.
 
+{{> prompts/_inflight.md}}
+
 ## Do the work
 
 - **Read `{{staff.dir}}/CHARTER.md` and `{{staff.dir}}/memory/INDEX.md` before acting.** They are

package/templates/ops/run-record.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// Writes down what one run was and what it cost, after the agent has finished or failed.
+//
+// Vendored alongside compose.mjs for the same reason: it runs on the runner, and must not depend
+// on npm or on an org the tenant does not control.
+//
+// The record is small and deliberately incomplete. Staff, kind, outcome and duration are always
+// known. Turns, cost and tokens are known only when the agent says so: claude-code-action writes
+// an execution file, the `claude` CLI writes JSON when asked, and anything else may say nothing.
+// An unknown is null, never a guess, because a total built from guesses is worse than none.
+//
+// Usage:  node roster-ops/run-record.mjs --out .roster-run/run.json
+//         (everything else arrives in the environment; see session.yaml)
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The agent's own account of the run, from whatever it wrote.
+ *
+ * Three shapes turn up: an array of messages whose last `result` is the summary (the Action's
+ * execution file), a single result object (`claude -p --output-format json`), and one message
+ * per line (`stream-json`). All three end in the same object, so find that.
+ */
+export function readResult(text) {
+  if (!text || !text.trim()) return null;
+  let items;
+  try {
+    const parsed = JSON.parse(text);
+    items = Array.isArray(parsed) ? parsed : [parsed];
+  } catch {
+    items = [];
+    for (const line of text.split("\n")) {
+      try {
+        items.push(JSON.parse(line));
+      } catch {
+        // A line of log output between the JSON is not ours to fail on.
+      }
+    }
+  }
+  const results = items.filter(
+    (m) => m && typeof m === "object" && (m.type === "result" || "total_cost_usd" in m),
+  );
+  const last = results[results.length - 1];
+  if (!last) return null;
+
+  const n = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+  const u = last.usage ?? {};
+  const tokens = {
+    input: n(u.input_tokens),
+    output: n(u.output_tokens),
+    cache_read: n(u.cache_read_input_tokens),
+    cache_write: n(u.cache_creation_input_tokens),
+  };
+  return {
+    turns: n(last.num_turns),
+    cost_usd: n(last.total_cost_usd ?? last.cost_usd),
+    tokens: Object.values(tokens).some((v) => v !== null) ? tokens : null,
+  };
+}
+
+/**
+ * What happened, in one word.
+ *
+ * The agent step's own outcome when it ran. When it never ran, the job's status says whether
+ * that was a cancel (a timeout is one) or a failure somewhere in the setup before it.
+ */
+export function outcomeOf(agentOutcome, jobStatus) {
+  if (["success", "failure", "cancelled"].includes(agentOutcome)) return agentOutcome;
+  if (jobStatus === "cancelled") return "cancelled";
+  return "setup-failure";
+}
+
+export function buildRecord(env, resultText, now = Date.now()) {
+  const started = Number(env.ROSTER_STARTED) || null;
+  const result = readResult(resultText);
+  return {
+    v: 1,
+    staff: env.STAFF ?? "",
+    kind: env.KIND ?? "",
+    outcome: outcomeOf(env.AGENT_OUTCOME, env.JOB_STATUS),
+    started: started ? new Date(started * 1000).toISOString() : null,
+    duration_s: started ? Math.max(0, Math.round(now / 1000 - started)) : null,
+    agent: env.AGENT_ID || null,
+    model: env.MODEL || null,
+    turns: result?.turns ?? null,
+    cost_usd: result?.cost_usd ?? null,
+    tokens: result?.tokens ?? null,
+    run_id: env.GITHUB_RUN_ID ?? null,
+    run_url:
+      env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY && env.GITHUB_RUN_ID
+        ? `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}`
+        : null,
+  };
+}
+
+/** The same record as the job summary shows it: one table, unknowns as a dash. */
+export function summary(record) {
+  const dash = (v) => (v === null || v === undefined ? "—" : String(v));
+  const mins = record.duration_s === null ? null : `${Math.round(record.duration_s / 60)}m`;
+  const cost = record.cost_usd === null ? null : `$${record.cost_usd.toFixed(2)}`;
+  const t = record.tokens;
+  const tokens = t
+    ? [
+        t.input !== null ? `${t.input} in` : "",
+        t.output !== null ? `${t.output} out` : "",
+        t.cache_read !== null ? `${t.cache_read} cached` : "",
+      ]
+        .filter(Boolean)
+        .join(", ")
+    : null;
+  return [
+    `### ${record.staff} · ${record.kind} · ${record.outcome}`,
+    "",
+    "| duration | turns | cost | tokens | agent |",
+    "|---|---|---|---|---|",
+    `| ${dash(mins)} | ${dash(record.turns)} | ${dash(cost)} | ${dash(tokens)} | ${dash(record.agent)} |`,
+    "",
+  ].join("\n");
+}
+
+function main(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 2) args[argv[i].replace(/^--/, "")] = argv[i + 1];
+  const out = resolve(args.out ?? ".roster-run/run.json");
+  const file = process.env.RESULT_FILE;
+  const text = file && existsSync(file) ? readFileSync(file, "utf8") : "";
+  const record = buildRecord(process.env, text);
+
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, JSON.stringify(record, null, 2) + "\n");
+  if (process.env.GITHUB_STEP_SUMMARY) appendFileSync(process.env.GITHUB_STEP_SUMMARY, summary(record));
+  process.stdout.write(JSON.stringify(record) + "\n");
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+  try {
+    main(process.argv.slice(2));
+  } catch (err) {
+    console.error(`run-record: ${err.message}`);
+    process.exit(1);
+  }
+}