@refactco/refact-os 1.5.0

package/templates/base/agent/scripts/sync-asana.mjs

@@ -0,0 +1,408 @@
+#!/usr/bin/env node
+// .cursor/scripts/sync-asana.mjs
+//
+// Read-only Asana sync: pulls every task in the configured Asana project
+// (open + completed) along with its details and comments, and writes one
+// markdown file per task into `docs/task/open/` (open) or `docs/task/closed/`
+// (completed). Idempotent: re-running updates existing files in place and
+// preserves the `processed:` flag from any prior run.
+//
+// Requires:
+//   - .refact-os.json → `asana.projectId` (numeric Asana project GID)
+//   - .env             → `ASANA_TOKEN` (Asana personal access token)
+//
+// Usage:
+//   node .cursor/scripts/sync-asana.mjs                  # full project sync
+//   node .cursor/scripts/sync-asana.mjs --ticket <gid>   # sync one task
+//   node .cursor/scripts/sync-asana.mjs --dry-run        # no file writes
+//
+// This script never writes back to Asana. Creating tickets, adding comments,
+// or any other mutation must remain a deliberate, future change.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PROJECT_ROOT = path.resolve(__dirname, "..", "..");
+const CONFIG_PATH = path.join(PROJECT_ROOT, ".refact-os.json");
+const ENV_PATH = path.join(PROJECT_ROOT, ".env");
+const ASANA_DIR = path.join(PROJECT_ROOT, "docs", "asana");
+const CLOSED_DIR = path.join(ASANA_DIR, "closed");
+
+const ASANA_BASE = process.env.ASANA_API_BASE || "https://app.asana.com/api/1.0";
+const TASK_OPT_FIELDS = [
+  "name",
+  "notes",
+  "completed",
+  "completed_at",
+  "completed_by.name",
+  "completed_by.email",
+  "created_at",
+  "modified_at",
+  "due_on",
+  "due_at",
+  "start_on",
+  "start_at",
+  "assignee.name",
+  "assignee.email",
+  "parent.gid",
+  "parent.name",
+  "projects.name",
+  "memberships.section.name",
+  "tags.name",
+  "custom_fields.name",
+  "custom_fields.display_value",
+  "custom_fields.type",
+  "num_subtasks",
+  "permalink_url",
+  "resource_subtype",
+  "followers.name",
+].join(",");
+const STORY_OPT_FIELDS = [
+  "created_at",
+  "created_by.name",
+  "created_by.email",
+  "text",
+  "type",
+  "resource_subtype",
+].join(",");
+const SUBTASK_OPT_FIELDS = ["name", "gid", "completed"].join(",");
+const ATTACHMENT_OPT_FIELDS = ["name", "permanent_url", "view_url", "host"].join(",");
+
+function parseArgs(argv) {
+  const args = { ticket: null, dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--ticket" || a === "-t") {
+      args.ticket = (argv[i + 1] || "").trim();
+      i += 1;
+    } else if (a.startsWith("--ticket=")) {
+      args.ticket = a.slice("--ticket=".length).trim();
+    } else if (a === "--dry-run") {
+      args.dryRun = true;
+    }
+  }
+  return args;
+}
+
+function loadDotEnv(filePath) {
+  if (!existsSync(filePath)) return {};
+  const raw = readFileSync(filePath, "utf8");
+  const out = {};
+  for (const rawLine of raw.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+function loadConfig() {
+  if (!existsSync(CONFIG_PATH)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf8")) || {};
+  } catch {
+    return {};
+  }
+}
+
+function die(message, code = 1) {
+  process.stderr.write(`sync-asana: ${message}\n`);
+  process.exit(code);
+}
+
+async function asanaFetch(token, urlPath, params = {}) {
+  const url = new URL(urlPath.startsWith("http") ? urlPath : `${ASANA_BASE}${urlPath}`);
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined && v !== null && v !== "") {
+      url.searchParams.set(k, v);
+    }
+  }
+  let attempt = 0;
+  while (true) {
+    attempt += 1;
+    const res = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+      },
+    });
+    if (res.status === 429 && attempt < 4) {
+      const retryAfter = Number(res.headers.get("retry-after") || 2);
+      await new Promise((r) => setTimeout(r, retryAfter * 1000));
+      continue;
+    }
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`Asana ${res.status} ${res.statusText} for ${url.pathname}: ${body.slice(0, 200)}`);
+    }
+    return res.json();
+  }
+}
+
+async function* paginate(token, urlPath, params) {
+  let offset;
+  while (true) {
+    const page = await asanaFetch(token, urlPath, { ...params, offset });
+    for (const item of page.data || []) {
+      yield item;
+    }
+    const next = page.next_page?.offset;
+    if (!next) return;
+    offset = next;
+  }
+}
+
+async function fetchProjectTaskGids(token, projectGid) {
+  const gids = [];
+  for await (const t of paginate(token, `/projects/${projectGid}/tasks`, {
+    completed_since: "2000-01-01T00:00:00.000Z",
+    limit: 100,
+    opt_fields: "gid",
+  })) {
+    gids.push(t.gid);
+  }
+  return gids;
+}
+
+async function fetchTask(token, gid) {
+  const detail = await asanaFetch(token, `/tasks/${gid}`, { opt_fields: TASK_OPT_FIELDS });
+  return detail.data;
+}
+
+async function fetchStories(token, gid) {
+  const out = [];
+  for await (const s of paginate(token, `/tasks/${gid}/stories`, {
+    limit: 100,
+    opt_fields: STORY_OPT_FIELDS,
+  })) {
+    out.push(s);
+  }
+  return out;
+}
+
+async function fetchSubtasks(token, gid) {
+  const out = [];
+  for await (const s of paginate(token, `/tasks/${gid}/subtasks`, {
+    limit: 100,
+    opt_fields: SUBTASK_OPT_FIELDS,
+  })) {
+    out.push(s);
+  }
+  return out;
+}
+
+async function fetchAttachments(token, gid) {
+  const out = [];
+  for await (const a of paginate(token, `/tasks/${gid}/attachments`, {
+    limit: 100,
+    opt_fields: ATTACHMENT_OPT_FIELDS,
+  })) {
+    out.push(a);
+  }
+  return out;
+}
+
+function readPreservedProcessed(filePath) {
+  if (!existsSync(filePath)) return false;
+  const text = readFileSync(filePath, "utf8");
+  const m = text.match(/^---[\s\S]*?\nprocessed:\s*(true|false)\s*\n[\s\S]*?---/m);
+  return m ? m[1] === "true" : false;
+}
+
+function findExistingFile(gid) {
+  const open = path.join(ASANA_DIR, `${gid}.md`);
+  if (existsSync(open)) return { path: open, dir: "open" };
+  const closed = path.join(CLOSED_DIR, `${gid}.md`);
+  if (existsSync(closed)) return { path: closed, dir: "closed" };
+  return null;
+}
+
+function renderMarkdown(task, stories, subtasks, attachments) {
+  const statusLabel = task.completed ? "Completed" : "Open";
+  const assignee = task.assignee
+    ? `${task.assignee.name}${task.assignee.email ? ` (${task.assignee.email})` : ""}`
+    : "Unassigned";
+  const due = task.due_at || task.due_on || "—";
+  const start = task.start_at || task.start_on || "—";
+  const section = task.memberships?.[0]?.section?.name;
+  const tags = (task.tags || []).map((t) => t.name).filter(Boolean);
+  const headerLines = [
+    "---",
+    "source: asana",
+    "added-by: sync-asana.mjs",
+    `processed: ${task._preservedProcessed ? "true" : "false"}`,
+    `asana-gid: ${task.gid}`,
+    `asana-permalink: ${task.permalink_url || ""}`,
+    `asana-modified-at: ${task.modified_at || ""}`,
+    `asana-completed: ${task.completed ? "true" : "false"}`,
+    "---",
+    "",
+  ];
+  const lines = [];
+  lines.push(`# ${task.name || "(untitled)"}`);
+  lines.push("");
+  lines.push(
+    `**Status:** ${statusLabel} · **Assignee:** ${assignee} · **Due:** ${due} · **Start:** ${start}`,
+  );
+  if (section) lines.push(`**Section:** ${section}`);
+  if (tags.length) lines.push(`**Tags:** ${tags.join(", ")}`);
+  if (task.parent?.gid) {
+    lines.push(`**Parent task:** ${task.parent.name || ""} (gid: ${task.parent.gid})`);
+  }
+  if (task.completed_at) {
+    const by = task.completed_by?.name ? ` by ${task.completed_by.name}` : "";
+    lines.push(`**Completed at:** ${task.completed_at}${by}`);
+  }
+  lines.push("");
+  if (task.notes) {
+    lines.push("## Notes");
+    lines.push("");
+    lines.push(task.notes);
+    lines.push("");
+  }
+  const customFields = (task.custom_fields || []).filter((cf) => cf.display_value);
+  if (customFields.length) {
+    lines.push("## Custom fields");
+    lines.push("");
+    for (const cf of customFields) {
+      lines.push(`- **${cf.name}:** ${cf.display_value}`);
+    }
+    lines.push("");
+  }
+  if (subtasks.length) {
+    lines.push(`## Subtasks (${subtasks.length})`);
+    lines.push("");
+    for (const s of subtasks) {
+      const box = s.completed ? "[x]" : "[ ]";
+      lines.push(`- ${box} ${s.name || "(untitled)"} \`gid:${s.gid}\``);
+    }
+    lines.push("");
+  }
+  if (attachments.length) {
+    lines.push(`## Attachments (${attachments.length})`);
+    lines.push("");
+    for (const a of attachments) {
+      const url = a.permanent_url || a.view_url || "";
+      lines.push(`- [${a.name || "attachment"}](${url})${a.host ? ` _(${a.host})_` : ""}`);
+    }
+    lines.push("");
+  }
+  if (stories.length) {
+    lines.push(`## Comments / activity (${stories.length})`);
+    lines.push("");
+    for (const s of stories) {
+      const author = s.created_by?.name || "Unknown";
+      const subtype = s.resource_subtype || s.type || "";
+      lines.push(`### ${s.created_at || ""} — ${author} _(${subtype})_`);
+      lines.push("");
+      if (s.text) {
+        lines.push(s.text);
+        lines.push("");
+      }
+    }
+  }
+  return headerLines.join("\n") + lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}
+
+function writeTaskFile(task, stories, subtasks, attachments, dryRun) {
+  const targetDir = task.completed ? CLOSED_DIR : ASANA_DIR;
+  const targetPath = path.join(targetDir, `${task.gid}.md`);
+  const existing = findExistingFile(task.gid);
+  task._preservedProcessed = existing ? readPreservedProcessed(existing.path) : false;
+  const content = renderMarkdown(task, stories, subtasks, attachments);
+
+  let action = "unchanged";
+  if (dryRun) {
+    if (!existing) action = "would-create";
+    else if (existing.path !== targetPath) action = "would-move";
+    else if (readFileSync(existing.path, "utf8") !== content) action = "would-update";
+    return { action, targetPath };
+  }
+
+  mkdirSync(targetDir, { recursive: true });
+  if (existing && existing.path !== targetPath) {
+    unlinkSync(existing.path);
+    action = "moved";
+  } else if (!existing) {
+    action = "created";
+  } else if (readFileSync(existing.path, "utf8") !== content) {
+    action = "updated";
+  }
+  if (action !== "unchanged") {
+    writeFileSync(targetPath, content, "utf8");
+  }
+  return { action, targetPath };
+}
+
+function summarize(results) {
+  const counts = results.reduce((acc, r) => {
+    acc[r.action] = (acc[r.action] || 0) + 1;
+    return acc;
+  }, {});
+  return counts;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const env = { ...loadDotEnv(ENV_PATH), ...process.env };
+  const token = (env.ASANA_TOKEN || "").trim();
+  const config = loadConfig();
+  const projectId = config.asana?.projectId;
+
+  if (!token) {
+    die("ASANA_TOKEN is not set. Add it to .env (https://app.asana.com/0/my-apps).");
+  }
+  if (!args.ticket && (projectId === undefined || projectId === null || projectId === "")) {
+    die(
+      "asana.projectId is missing in .refact-os.json. Run `npx refact-os-scaffold init` to fill it in, or pass --ticket <gid> to sync a single ticket.",
+    );
+  }
+
+  let taskGids;
+  if (args.ticket) {
+    taskGids = [args.ticket];
+  } else {
+    process.stdout.write(`Fetching task list for Asana project ${projectId}…\n`);
+    taskGids = await fetchProjectTaskGids(token, projectId);
+    process.stdout.write(`  found ${taskGids.length} task(s).\n`);
+  }
+
+  const results = [];
+  for (const gid of taskGids) {
+    try {
+      const task = await fetchTask(token, gid);
+      const [stories, subtasks, attachments] = await Promise.all([
+        fetchStories(token, gid),
+        task.num_subtasks > 0 ? fetchSubtasks(token, gid) : Promise.resolve([]),
+        fetchAttachments(token, gid),
+      ]);
+      const { action, targetPath } = writeTaskFile(task, stories, subtasks, attachments, args.dryRun);
+      results.push({ gid, action, path: targetPath });
+      process.stdout.write(`  ${action.padEnd(13)} ${path.relative(PROJECT_ROOT, targetPath)}\n`);
+    } catch (err) {
+      results.push({ gid, action: "error", error: err.message });
+      process.stderr.write(`  error ${gid}: ${err.message}\n`);
+    }
+  }
+
+  const counts = summarize(results);
+  process.stdout.write(`\nDone. ${JSON.stringify(counts)}\n`);
+}
+
+main().catch((err) => {
+  process.stderr.write(`sync-asana: ${err.message || err}\n`);
+  process.exit(1);
+});

package/templates/base/agent/skills/adopt/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: adopt
+pattern: procedure
+requires_approval: false
+description: Produce a PLAN for bringing an existing, non-conformant repo up to the agent-first standard. Surveys the repo and outputs a phased transition plan as its final response — it does NOT change anything.
+when_to_use: The user wants to understand what it would take to bring an existing repo to the standard — "adopt this repo", "make this repo agent-first", "what's the plan to conform this repo", "plan the migration". Run after `npx github:refactco/refact-os init --no-force` has laid the mechanical seed.
+when_not_to_use: For a brand-new empty project (use `npx github:refactco/refact-os init`). When the user explicitly asks you to EXECUTE a plan that already exists (this skill only plans — execution is a separate, explicit step the user approves).
+inputs:
+  - the target repository (surveyed read-only, not fully read)
+  - the standard at docs/agent-first-repo-best-practices.md (or the refact-os package copy)
+  - the output of `npm run refact:validate` (read-only)
+outputs:
+  - a phased transition plan, presented as the final response. No files are moved, created, or deleted.
+next_skills: []
+sub_agents: []
+---
+
+# Adopt (plan only)
+
+Produce a **plan** for bringing an existing repo to the agent-first standard. This skill is **read-only**: it surveys, reasons, and outputs a phased plan as its final response. It does **not** move, create, or delete files, create branches, or run `init`/`migrate`/`sync`. Execution is a separate step the user explicitly approves *after* reading the plan.
+
+## Absolute rules
+
+- **Change nothing.** No `git mv`, no writes, no deletions, no new branch, no `refact-os init|migrate|sync`. The plan is the only deliverable. If you catch yourself about to edit a file, stop — that's not this skill.
+- **Survey, don't read everything.** Walk the tree; read sizes, first lines, frontmatter, headers; deep-read only what a recommendation needs. For a large repo, fan out one read-only survey sub-agent per top-level area, each returning a short summary. Never try to hold the whole repo at once.
+- **This is the target repo, not refact-os.** You are planning *this* repo's conformance. `refact-os` is the scaffolding tool, not this repo — don't adopt its identity or branding, and don't assume this repo is a refact-os clone. Describe everything in terms of what *this* repo actually is.
+- **Ask only what you must to plan.** If a canonical-vs-duplicate choice blocks the plan, list it as an open question in the plan rather than guessing or acting.
+
+## Steps
+
+1. **Survey** the repo breadth-first (sub-agents per area). For each area note: what's there, which of the six roles it maps to (Evidence/Knowledge/Task/Output/Software/Agent), and anything load-bearing (scripts, automation, hardcoded paths).
+2. **Read the gaps:** run `npm run refact:validate` (read-only) and fold its findings in. If the script/binary isn't wired up yet, fall back to `npx github:refactco/refact-os validate` (read-only, touches nothing in the repo) — don't run `npm install` here, since this skill changes nothing.
+3. **Write the plan** and present it as your final response. Structure it as ordered **phases**, each a small reviewable unit, with: the proposed moves/renames/**deletions**, the references that would need updating, and any open questions. Typical items:
+   - Missing seed → `npx github:refactco/refact-os init --no-force` (additive).
+   - Duplicate canonical map (`INDEX.md` vs `docs/index.md`) → which is canonical; merge the other.
+   - Duplicate contract (root `AGENTS.md` vs `agent/AGENTS.md`) → consolidate into `agent/AGENTS.md`, leave a thin root pointer.
+   - Variant dirs (`docs/tasks` vs `docs/task`) → consolidate onto the standard name.
+   - Forbidden `agent/workflows/` / `agent/evals/` → fold each into `agent/skills/<verb-object>/SKILL.md` (orchestrator/review pattern); propose names.
+   - **Folders to delete** where a folder is genuinely unneeded (e.g. an empty `docs/deliverables/` on a repo that ships nothing) — list them explicitly so the user can approve.
+   - Content not in a clear role → propose a role + destination.
+   - **Preserve** `docs/company/` (upstream for `npx refact-os sync company`) and raw evidence — call these out as intentionally unchanged.
+4. **Stop.** End with: "This is a plan only — nothing was changed. Review it; when you're ready, approve the phases you want and I'll execute them one at a time." Do not proceed to execute.
+
+## Output shape
+
+A short summary, then the phased plan (Phase 1, Phase 2, …) with checkboxes, an "intentionally left unchanged" list, and an "open questions" list. Offer to write the plan to `docs/task/open/<yyyy-mm-dd>-adopt.md` **only if the user asks** — by default, leave the repo untouched.

package/templates/base/agent/skills/close-ticket/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: close-ticket
+description: Close an open ticket by compressing it to a one-line entry in docs/task/closed/ (or closed.md) with its outcome, and remove the open file.
+pattern: procedure
+when_to_use: A tracked ticket in docs/task/open/ is done or no longer needed.
+when_not_to_use: For opening a ticket (use open-ticket) or for recording a decision (use docs/decisions.md directly).
+inputs:
+  - the open ticket file under docs/task/open/
+outputs:
+  - a one-line record under docs/task/closed/ and removal of the open file
+next_skills: []
+sub_agents: []
+---
+
+# Close Ticket
+
+## Steps
+
+1. Read the open ticket in `docs/task/open/<file>.md`.
+2. Append a one-line record to `docs/task/closed/closed.md` (create it if missing):
+   ```
+   - <yyyy-mm-dd> — <title> — <outcome>. (was: <original filename>)
+   ```
+3. If the full body is worth keeping, move it to `docs/task/closed/<filename>`; otherwise the one-liner is enough.
+4. Delete the file from `docs/task/open/`.
+5. If the work produced a finalized decision, also append to `docs/decisions.md`.
+
+## Notes
+
+- Read `closed.md` first to avoid duplicate entries.
+- Keep the one-liner terse — title, date, outcome.

package/templates/base/agent/skills/extract-learnings/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: extract-learnings
+description: Capture a durable, generalizable learning — a preference, project convention, workflow/infra fact, or hard-won approach — into docs/context/learnings.md, promoting any hard rule to agent/AGENTS.md.
+pattern: procedure
+when_to_use: A turn revealed something durable — a user preference, a project convention not in agent/AGENTS.md, a generalizable correction, a workflow/infra fact, or a working approach found after trial-and-error. MUST self-check at the end of any multi-step session that established a new file/convention or pinned down setup wiring.
+when_not_to_use: Routine work that revealed nothing new, one-off debugging steps, or facts already in agent/AGENTS.md, docs/decisions.md, or docs/context/learnings.md.
+next_skills: []
+sub_agents: []
+---
+
+# Extract Learnings
+
+Write down **non-obvious** things from the current chat — user preferences, project conventions, recurring mistakes, hard-won setup recipes — before they're lost.
+
+> **This skill is the project's memory of record, and it takes precedence over personal/global agent memory.** Capture durable *project* facts here, in `docs/context/learnings.md` (and hard rules in `agent/AGENTS.md`) — do **not** also write the same fact to `~/.claude/projects/<dir>/memory/`. The repo is the shared brain; per-user memory is not.
+
+## When to invoke
+
+Fire when the turn revealed one of these:
+
+- Something about the user worth carrying forward — role, expertise, style, environment, tool preferences.
+- An expectation about how the agent should behave.
+- A project convention not already in `agent/AGENTS.md` or `docs/context/`.
+- A correction that generalizes (not a one-off).
+- A concrete workflow fact (branch naming, deploy scripts, review cadence).
+- **A working approach found after trial-and-error.** The winning approach is non-obvious by definition — capture it (plus any gotchas that ruled out wrong paths). Example: "Config changes in `<file>` need a dev-server restart to apply — they aren't hot-reloaded."
+- **Infra wiring that only becomes true after setup** — which command must run after which edit, which port maps to which domain, which env file holds which secrets, which service restart is required for changes to take effect.
+
+Skip when:
+
+- The turn was routine work and nothing new was revealed.
+- Already covered in `agent/AGENTS.md` § Hard rules, `docs/decisions.md`, or `docs/context/learnings.md`.
+- It was a one-off debugging step with no generalizable rule (one bad commit, one stale cache, one transient network blip).
+- The information is trivially derivable by reading the code, running `git log`, or following an existing doc.
+
+Most turns won't trigger this. When unsure, don't fire. **But always self-check at the end of any multi-step session**: *"what did I discover or establish here that the next session would need to know on day one?"* — if the answer is non-empty, capture it. Even a sprawling setup compresses to one bullet that names the key files/paths/commands.
+
+## Workflow
+
+### 1. Identify the learning
+
+Re-read recent turns and ask:
+
+- Did I try multiple approaches before one worked? → The winning approach is a learning.
+- Did I create a file with a specific role (override, example, secrets, proxy config)? → That role is a learning.
+- Did I install or configure infra (reverse proxy, DNS, certs, hosts file)? → The wiring is a learning.
+- Did the user push back on, or confirm, an unusual choice? → That feedback is a learning.
+- Did `.gitignore`, environment, or how secrets flow change? → Capture the new convention.
+- Did a command sequence become load-bearing for future setups? → Capture the recipe (one line, naming the entry points).
+
+Zero bullets is fine — don't pad. Skip anything already in `docs/context/learnings.md`, `agent/AGENTS.md` § Hard rules, or `docs/decisions.md`.
+
+### 2. Append to `docs/context/learnings.md`
+
+Under the `## Entries` heading, **newest first**:
+
+```
+- YYYY-MM-DD — one-line learning.
+```
+
+- Use today's date from the current-date system reminder.
+- One bullet, one idea. A complex setup still fits one line — name the key files/paths/commands; the detail lives in the code itself.
+- If it truly cannot be distilled to one line, write it to `docs/context/open-decisions.md` (or a dedicated doc under `docs/`) and tell the user.
+- Append only. **Never** rewrite or reorder existing entries.
+
+### 3. Promote Hard rules to `agent/AGENTS.md`
+
+If the learning is a hard, non-negotiable rule ("Never X" / "Always X", no edge cases):
+
+1. Append as a numbered bullet under `## Hard rules (never)` in `agent/AGENTS.md`. Match the existing terse voice.
+2. Remove that bullet from `docs/context/learnings.md` (the only allowed edit beyond appending, same run only).
+3. List every promoted rule in your report.
+
+Bar is **high**. When unsure, leave it in `learnings.md` and flag it. Never promote anything contradicting an existing Hard rule — stop and surface the conflict.
+
+### 4. Report
+
+One short sentence:
+
+- Captured only: `Captured learning: <bullet>.`
+- Captured + promoted: `Captured + promoted to agent/AGENTS.md: <rule>.`
+- Nothing durable: stay silent.
+
+## Guardrails
+
+- **Never** rewrite or reorder existing entries in `docs/context/learnings.md`. Append-only — the one exception is removing a bullet you just promoted, same run.
+- **Never** delete unrelated entries without the user's say-so.
+- **Never** paste raw chat excerpts. Distill, don't quote.
+- **Never** auto-promote unless certain it's a hard, universal rule.
+- **Never** edit `agent/AGENTS.md` outside `## Hard rules (never)`.