@golden-frijoles/kit 0.0.0 → 0.2.0

package/dist/prose/weekly.task.md

@@ -0,0 +1,36 @@
+<!--
+  weekly.task.md — the per-surface task block for the WEEKLY recap.
+
+  Higher altitude than standup.task.md: themes, not events. Composed after cpo-persona.md and the
+  accumulated lessons, before the evidence pack.
+
+  Written by the Claude Routine in-context (README D1).
+
+  Everything above the first `---` is stripped before sending.
+-->
+
+---
+
+## Task: write the WEEKLY RECAP
+
+For someone who was not watching this week and wants the through-line, not the log.
+
+**Length: up to 160 words.** That is a budget, not a target — and it is emphatically **not**
+permission to enumerate. A list of merges is not a report.
+
+The question you are answering: **what is now possible that was not possible on Monday, and what is
+still owed?**
+
+- **Group by theme, never by commit or by repo.** Three changes that together made one flow work are
+  one theme and one sentence. Repos are an implementation detail the reader does not think in.
+- **Lead with shipped and closed work.** The evidence pack gives you epics whose status flipped this
+  week, with their retrospectives — that is the highest-altitude product input available, written in
+  product language by the people who did the work. Use it before you touch commit subjects.
+- **Name the decision that shaped the week**, if there was one. Something chosen over an obvious
+  alternative, something deliberately declined, something that turned out to be false and changed
+  the plan. A week usually has exactly one of these and it is usually the most valuable sentence in
+  the report.
+- **State what is still owed** — unverified work, gaps a person has to close by hand, anything
+  built but not yet live. The owed ledger is sacred here: a weekly that quietly omits a known gap is
+  the one unforgivable error in this house.
+- **A quiet week is a fact.** Report it in a sentence and stop.

package/dist/prose-draft.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+// prose-draft.mjs — delegate FILE-DERIVED internal prose to a cheaper, different-family model.
+//
+// The cross-agent rail (cross-review / cross-panel) proved the primitive: pipe context into a
+// foreign CLI, get one advisory pass back. This extends it from *reviewing code* to *drafting
+// prose* — but only for artifacts whose inputs are FILES (epic docs, sprint docs, git log), not
+// the builder's in-head context. That's the honest scope boundary: a PR body is cheapest written
+// by the agent that just built the PR; a retrospective/poster entry is a synthesis of docs that
+// are already on disk, which a cheap fast model drafts well and the coordinating agent edits.
+//
+// Modes (v1):
+//   node scripts/prose-draft.mjs --kind retro  --epic Roadmap/<area>/<epic-dir>
+//   node scripts/prose-draft.mjs --kind poster --epic Roadmap/<area>/<epic-dir>
+//   node scripts/prose-draft.mjs --kind sprint-wrap --sprint Roadmap/<area>/<epic>/sprint-N.md
+//
+// Output: the draft on stdout (synchronous flush — LEARNINGS pipe-truncation rule). The caller
+// reviews/edits/commits; this tool NEVER writes repo files itself (editorial control stays with
+// the coordinating agent — same "advisory only" stance as cross-review).
+//
+// Model: agy with a cheap-fast pair by default (prose doesn't need Pro-tier reasoning; the
+// coordinating agent is the editor). Override via PROSE_MODEL / PROSE_FALLBACK_MODEL.
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync, readdirSync, existsSync, writeSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { hasCmd, loadPromptBody, die, need } from './lib/cross-agent-cli.mjs';
+import { writeProse, buildWriterPrompt, loadLessons } from './lib/prose-writer.mjs';
+import { projectAsset, projectRoot } from './lib/project-root.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = projectRoot(); // D2
+
+// The model/router lives in scripts/lib/prose-writer.mjs now — deliberately NOT here.
+//
+// This file used to default to `gemini-3.5-flash-high`. That is the exact constant a consuming
+// project identified as having silently destroyed the register of every report it wrote: the accepted
+// drafts had come from GPT-OSS on the occasions Gemini's quota was exhausted, so the "fallback" was
+// actually the good writer. The rail now pins a single non-Gemini model and routes devin first. Do not
+// reintroduce a model constant here.
+
+export const KINDS = ['retro', 'poster', 'sprint-wrap'];
+
+// ── mode task blocks (pure) ─────────────────────────────────────────────────────────────────
+
+export function taskBlock(kind) {
+  switch (kind) {
+    case 'retro':
+      return `## Task: draft RETROSPECTIVE.md for the epic whose docs follow.
+Shape (exactly these sections): a one-line header with the epic name + close date placeholder
+(_Closed: YYYY-MM-DD_ — leave the placeholder if no date is in the sources); **## What shipped**
+(per sprint, outcome-first, with PR/commit refs from the sources); **## What worked**;
+**## What didn't / incidents** (plain, unsoftened); **## Gaps / follow-ups** (the owed ledger —
+every unverified item, pending migration, human smoke); **## Durable learnings** (only the
+*transferable* rules, each a bold one-liner + why + date/source, written so it can be pasted
+into Roadmap/LEARNINGS.md — dedupe-aware: if a learning sharpens an existing well-known rule,
+say "sharpens: <rule>"). Length budget: 60-90 lines.`;
+    case 'poster':
+      return `## Task: draft the product-poster entry for this epic (Roadmap/README.md house shape).
+One dated bold-led bullet: **YYYY-MM-DD — <Epic name> (<n> sprint(s); <risk>, <surface>).**
+followed by 3-8 sentences: the problem, what shipped (with PR refs), the load-bearing technical
+decision(s), what's owed. Then one table-row line for the area README:
+| [<slug>](<slug>/) | <one-line what> | ✅ **Shipped YYYY-MM-DD** (<refs + owed note>) |
+Length budget: 12 lines max.`;
+    case 'sprint-wrap':
+      return `## Task: draft the sprint-wrap terminal summary (SESSION-KICKOFFS §7 shape) for the
+sprint doc that follows. It is a THIN POINTER, never a re-summary: 4-8 lines — sprint name +
+status, the one-line outcome per story (ref'd), the owed list, and "next:" with the next sprint
+or close-out step. No headings, no code fences.`;
+    default:
+      return die(`unknown --kind "${kind}" (expected: ${KINDS.join(' | ')})`);
+  }
+}
+
+// ── source gathering (I/O, thin) ────────────────────────────────────────────────────────────
+
+function read(p) {
+  return readFileSync(p, 'utf8');
+}
+
+function gitLogFor(paths) {
+  // argv-array spawn, never a shell-built string — a path can't smuggle command substitution.
+  const r = spawnSync('git', ['log', '--oneline', '-20', '--', ...paths], {
+    cwd: REPO_ROOT,
+    encoding: 'utf8',
+  });
+  return r.status === 0 ? (r.stdout || '').trim() : '(git log unavailable)';
+}
+
+export function gatherEpicSources(epicDir, { readFile = read, listDir = readdirSync, log = gitLogFor } = {}) {
+  const files = listDir(epicDir)
+    .filter((f) => f.endsWith('.md'))
+    .sort();
+  if (!files.includes('README.md')) die(`${epicDir} has no README.md — is this an epic directory?`);
+  const parts = files.map((f) => `\n\n### FILE: ${f}\n\n${readFile(join(epicDir, f))}`);
+  return `## Source material — epic directory ${epicDir}${parts.join('')}\n\n### GIT LOG (epic paths)\n${log([epicDir])}`;
+}
+
+export function gatherSprintSources(
+  sprintPath,
+  { readFile = read, log = gitLogFor, exists = existsSync } = {}
+) {
+  const epicDir = dirname(sprintPath);
+  const readme = join(epicDir, 'README.md');
+  let out = `## Source material — sprint doc ${sprintPath}\n\n### FILE: ${sprintPath}\n\n${readFile(sprintPath)}`;
+  if (exists(readme)) out += `\n\n### FILE (context): ${readme}\n\n${readFile(readme)}`;
+  return `${out}\n\n### GIT LOG (epic paths)\n${log([epicDir])}`;
+}
+
+// ── prompt assembly (pure) ──────────────────────────────────────────────────────────────────
+
+// The house voice now comes from the SHARED persona + the internal-artifact task file, so a change to
+// the register reaches this surface and the two scheduled reports at once. What is genuinely local to
+// this tool — its three mode shapes — lives in taskBlock. (The old prose-draft.prompt.md is retired;
+// its internal-artifact rules moved into prose/internal.task.md.)
+export function loadStylePrompt() {
+  return [
+    loadPromptBody(projectAsset('prose/cpo-persona.md')), // a TEMPLATE FILL-IN the project owns
+    loadPromptBody(join(__dirname, 'prose', 'internal.task.md')),
+  ].join('\n\n');
+}
+
+export function buildPrompt({ style, kind, sources, lessons = '' }) {
+  // buildWriterPrompt owns the style→lessons→task ordering for BOTH backends, so the lessons file
+  // cannot reach one surface and silently miss the other.
+  return buildWriterPrompt({ style, lessons, task: `${taskBlock(kind)}\n\n${sources}` });
+}
+
+// ── main ────────────────────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2);
+  let kind, epic, sprint;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--kind') kind = need(args[++i], '--kind');
+    else if (args[i] === '--epic') epic = need(args[++i], '--epic');
+    else if (args[i] === '--sprint') sprint = need(args[++i], '--sprint');
+    else die(`unknown arg ${args[i]}`);
+  }
+  if (!kind || !KINDS.includes(kind)) die(`--kind is required (${KINDS.join(' | ')})`);
+
+  if (!hasCmd('devin') && !hasCmd('agy')) {
+    die('no prose writer available — this rail needs devin or agy on PATH (see scripts/README.md).');
+  }
+
+  let sources;
+  if (kind === 'sprint-wrap') {
+    if (!sprint) die('--sprint <path/to/sprint-N.md> is required for --kind sprint-wrap');
+    sources = gatherSprintSources(resolve(REPO_ROOT, sprint));
+  } else {
+    if (!epic) die(`--epic <path/to/epic-dir> is required for --kind ${kind}`);
+    sources = gatherEpicSources(resolve(REPO_ROOT, epic));
+  }
+
+  const prompt = buildPrompt({ style: loadStylePrompt(), kind, sources, lessons: loadLessons() });
+
+  // These are INTERNAL engineering artifacts, so two guard rules that fit a chat-message report would
+  // misfire here: refs/dates are required (not invented), and the length budget is a document, not 60
+  // words. `allowsBeneficiary` stays TRUE because a retro legitimately discusses merchants and buyers.
+  // The size cap is gone with the argv path — devin takes the prompt in a file.
+  const result = await writeProse({
+    prompt,
+    evidence: {
+      allowsFixClaim: true,
+      allowsBeneficiary: true,
+      allowsMarkdown: true,
+      maxWords: 4000,
+      minWords: 40,
+    },
+  });
+  if (!result.text) die(result.error || 'no prose writer produced a draft.');
+
+  // Advisory banner: names the writer AND the model that actually ran, plus whether the guard passed
+  // clean — so a paste-without-reading stays self-identifying in review.
+  const decided = result.guard?.decider ? ` by ${result.guard.decider}` : '';
+  const verdict = result.ok
+    ? `guard: clean${decided}`
+    : `guard: FLAGGED${decided} (${result.guard.findings.map((f) => f.code).join(', ')})`;
+  writeSync(
+    1,
+    `<!-- draft: prose-draft.mjs --kind ${kind} · writer ${result.writer}/${result.model} · ${verdict} · EDIT BEFORE COMMITTING -->\n${result.text}\n`
+  );
+
+  if (!result.ok) {
+    process.stderr.write(
+      `\n⚠ The guard rejected this draft and it did NOT converge after a revision pass:\n` +
+        result.guard.findings.map((f) => `  · ${f.code}: ${f.note}`).join('\n') +
+        `\n  Read it carefully before committing.\n\n`
+    );
+  }
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain)
+  main().catch((e) => {
+    process.stderr.write(`prose-draft: ${e?.message || e}\n`);
+    process.exit(1);
+  });

package/dist/prose-lessons.md

@@ -0,0 +1,59 @@
+<!--
+  prose-lessons.md — accumulated corrections, injected into EVERY writer prompt on BOTH backends
+  (scripts/lib/prose-writer.mjs's loadLessons, and the routine brief for the standup/weekly).
+
+  HOW TO USE THIS FILE
+  Every line below is a mistake a real draft actually made and a human had to catch. When you catch a
+  new one, add a line — that is the whole mechanism by which this rail gets better. Two rules:
+
+    1. Quote the ACTUAL bad sentence. A rule stated abstractly ("be accurate") changes nothing; the
+       verbatim failure is what a model can pattern-match against.
+    2. If the failure is mechanically detectable, ALSO add it to scripts/lib/prose-guard.mjs with a
+       test. A lesson reduces a mistake; a guard catches it. Prefer both.
+
+  Keep it short. A long file dilutes every line in it, and the guard is where hard enforcement lives.
+
+  Provenance: the first six lessons are inherited from golden-beans, where they were measured on a
+  live rail rather than imagined — a cheap model given a dense engineering commit produced material
+  falsehoods on two of its first three runs. They are kept verbatim because the failures they
+  describe are model behaviour, not repo-specific. The flag-state lesson is ours.
+-->
+
+---
+
+**Never invent a beneficiary.** A real draft wrote _"Tenants now benefit from a new pure-logic
+unit-test suite"_ about internal test tooling. Tenants do not run our tests. If a change is
+internal, say so plainly and name the real beneficiary — usually whoever builds here next — and the
+real effect: a bug class that can no longer reach production unnoticed, a mistake caught in seconds
+instead of after a deploy.
+
+**Never report a fix this change did not make.** A real draft wrote _"the previous backslash bypass
+is blocked, eliminating a potential open-redirect attack"_ about a commit that only ADDED TESTS for
+a fix shipped weeks earlier. Commit messages and roadmap docs here routinely cite a past incident to
+explain why present work matters — that is context, never the outcome. If the verb belongs to an
+earlier change, it is background.
+
+**Never claim a capability is live when its flag is off.** In the project these lessons were first
+learned in, five flag-gated epics shipped in a fortnight, every one of them born OFF. "Accounts can
+now be handed to a partner" is FALSE when `partner_handoff_enabled` is off — the correct sentence is that
+the rail is built and stays dark until the flag is flipped. This is our highest-risk falsehood
+because it reads as good news and nobody checks a flag before believing a report.
+
+**Never invent a deadline, a due date or a sign-off.** A real standup draft ended _"design sign-off
+on the Sprint 2 layout is owed before tomorrow"_ — no such commitment existed anywhere in the source
+data. Commits and roadmap docs contain no deadlines, so any date you attach is fabricated by
+construction. This is the most corrosive mistake on this list: it reads as perfectly ordinary
+standup language and it makes people chase work nobody agreed to. If something is genuinely owed,
+name what and to whom, with no date.
+
+**Never name tools, frameworks or models.** Real drafts leaked _"Playwright"_, _"Gemini"_ and
+_"Antigravity"_ despite the brief forbidding it. The reader either knows the stack or does not need
+it. Describe the effect, not the machinery.
+
+**Finish the last sentence.** A real draft ended _"…broader error handling is planned"_ mid-thought
+after running out of room. A trailing fragment reads as a broken tool, not as brevity. Plan the
+ending before starting it; stop at the previous full stop instead.
+
+**Say "no user-visible effect" when that is the truth.** It is a correct and useful report. Reaching
+for a vague benefit to avoid an honest "this is internal" is the failure that produces every other
+one on this list.