@jaybeeuu/agent-cortex 2.6.0 → 2.8.0

package/docs/skills/skill-anatomy.md

@@ -0,0 +1,212 @@
+# Skill Anatomy
+
+This document is the **canonical skill anatomy** for `agent-cortex` skills.
+Use it as the source of truth for `SKILL.md` structure, language, and review quality gates.
+
+## Front-matter spec
+
+Required fields:
+- `name`: kebab-case skill identifier.
+- `description`: max 1024 characters.
+
+Frontmatter is machine-validated: `pnpm lint` runs `check:skills`, which fails on a
+frontmatter block that would make pi silently drop the skill.
+
+Optional fields:
+- `argument-hint`: input prompt shown to users at invocation.
+- `disable-model-invocation`: hides the skill from automatic model routing; explicit
+  `/skill-name` invocation still works. Set it when the danger is a fuzzy description
+  match, e.g. a skill whose steps are destructive. Preserved and honoured by pi and
+  Claude Code. See `docs/research/disable-model-invocation.md`.
+
+## Description format rules
+
+- Target ≤200 characters even though max is 1024.
+- Write in third-person declarative voice.
+- Sentence 1: what the skill does.
+- Sentence 2: starts with `Use when ...`.
+- Include 2-4 natural user trigger phrases (quoted) such as "diagnose this" or "something is broken".
+- Prefer user vocabulary over internal jargon.
+
+## Voice and tone rules
+
+- Write the body in imperative second-person: "Run X", "Check Y", "Report Z".
+- Use positive framing; reserve "do not" only for hard safety/correctness boundaries.
+- Add one rationale sentence for non-obvious rules so behavior generalizes in novel cases.
+- Avoid ALL-CAPS emphasis.
+
+## Tool references
+
+Reference agent tools by token, never by a hardcoded harness-specific name such as `bash`,
+`task`, or `read_agent`. A tool token is the tool's canonical authoring name prefixed with
+`TOOL:` and wrapped in doubled curly braces — two `{` before it and two `}` after it. The
+wrapper is literal syntax: installers match it and substitute the per-harness name from
+`token-map.json` at install time. Add any new tool to the map's `tools` section in the same
+change; unknown tokens are hard errors. See `token-map.README.md` for the full authoring rules.
+
+## Required sections
+
+Every skill must include:
+1. `## When to use`
+2. `## Workflow` (numbered steps)
+3. `## Verification checklist` (`- [ ]` items)
+
+## Optional sections
+
+For each optional section, define **what it is**, include an **example snippet**, and state **when to include** and **when to omit**.
+
+| Section | What it is | Example snippet | When to include | When to omit |
+|---|---|---|---|---|
+| `When NOT to use` | Explicit out-of-scope invocation boundaries | `- When NOT to use: single-line typo fixes with no process risk.` | Skills with similar neighbors where invocation precision matters | Truly unique one-purpose utility skills |
+| `Red Flags` | Detectable anti-patterns the agent should self-correct during execution | `- Red flag: skipping boundary validation to save time.` | Discipline-enforcement skills (security, TDD, review) | Simple utility wrappers |
+| `Common Rationalizations` | Excuses models use to skip process with rebuttals | `| "This is small" | Small changes still need invariants checked. |` | Process-critical skills where shortcut pressure is common | Mechanical one-step skills |
+| `Philosophy / rationale` | Why the method exists and what trade-offs it protects | `- We front-load validation because downstream rollback cost is higher.` | Opinionated skills expected to handle novel variants | Purely mechanical instructions |
+| `Phase-gate checklists` | Mid-workflow gates that must pass before proceeding | `- [ ] Phase 1 complete: baseline tests captured.` | Multi-phase workflows (3+ distinct phases) | Linear single-phase tasks |
+| `See Also` | Explicit handoff to another skill for a real sub-task: a relative link to its `SKILL.md` plus the reason to load it | `- [review-security](../../review/review-security/SKILL.md) — run before committing.` | Another skill owns a sub-domain better than restating it | Self-contained skills |
+| `Examples` | Full worked sample of expected outcome/output | `- Input: ... Output: ...` | Any non-trivial output contract | Trivially self-evident skills |
+| `Workflow diagrams` | Inline ASCII diagram showing step flow and decision points | Fenced block of `[Box]`, `|`, `-`, `>`, `v` arrows, e.g. `[Start] --> [Validate] --> [Run]` | Multi-step or branching workflows where a glanceable flow improves comprehension | Simple linear workflows already clear from numbered steps |
+
+`## See Also` entries are one-line handoffs: a relative link to the related skill's `SKILL.md`, an
+em-dash, and the reason a reader of this skill would load that one. A bare skill name leaves the
+reader guessing whether the link matters; the reason is what turns a link list into routing.
+
+Write the path against the authored tree (`../../<group>/<skill>/SKILL.md` from a skill directory).
+The Claude Code installer flattens skills and rewrites these targets at copy time, so a hand-written
+link that resolves here resolves in both install layouts. List only genuine handoffs — inline calls
+inside `## Workflow` already cover skills used as a step, and `using-agent-skills` already maps the
+whole corpus, so a duplicate entry adds noise.
+
+## Workflow diagram style guide
+
+When a skill includes a workflow diagram, follow these rules so it renders
+reliably in any CLI:
+
+- **ASCII only** — never Mermaid, images, or unicode box-drawing characters.
+  Keep to `|`, `-`, `>`, `+`, and `v`.
+- **Fenced block** — wrap the diagram in a fenced code block so monospace is
+  preserved.
+- **At most 80 characters per line** — narrow enough for terminal-width readers.
+- **Short box labels** — imperative verbs or nouns (e.g. `[Validate scope]`),
+  never full sentences.
+- **Read left-to-right, top-down** — prefer one branch level over dense joins.
+- **Mirror the numbered workflow** — the diagram is a glanceable summary of the
+  `## Workflow` steps, never a source of truth that contradicts them.
+
+## Section ordering
+
+### When to use
+
+State concrete invocation triggers using natural language phrases users actually type.
+
+### When NOT to use
+
+Place this section immediately after `When to use` whenever present.
+
+### Workflow
+
+Provide ordered, deterministic steps with observable outcomes.
+
+### Verification checklist
+
+Provide completion gates that are testable and stage-scoped.
+
+## File layout and progressive disclosure
+
+- Target ~150 lines for `SKILL.md`.
+- Split long docs into purpose-named support files:
+  - `EXAMPLES.md` for worked examples.
+  - `FORMAT.md` for schemas/templates.
+  - `REFERENCE.md` for rare edge cases.
+- Use slash-command references when another skill should be invoked.
+
+## Acceptance criteria checklist
+
+A skill passes anatomy review when:
+- [ ] Front matter uses required fields and valid description format.
+- [ ] Tool references use doubled-brace `TOOL:` tokens, not hardcoded tool names.
+- [ ] Required sections exist and follow canonical ordering.
+- [ ] Optional sections (if present) include what/when/example guidance.
+- [ ] `See Also` entries link the target `SKILL.md` relatively and state why to load it.
+- [ ] Workflow diagrams (if present) are ASCII-only and follow the workflow diagram style guide.
+- [ ] Verification checklist contains concrete, machine-checkable items.
+- [ ] Supporting docs are split by purpose when `SKILL.md` would exceed ~150 lines.
+
+## Annotated template
+
+```md
+---
+name: skill-name
+description: This skill performs a specific capability. Use when a user asks for a matching workflow such as "triage this", "investigate this", or "prepare a handoff".
+argument-hint: Optional prompt shown to users when extra input is needed.
+disable-model-invocation: false
+---
+
+# Skill Name
+
+## When to use
+
+- Trigger phrases users actually say, e.g. "triage this failure".
+- Include 2-4 concrete patterns.
+
+## When NOT to use
+
+- Out-of-scope cases that should route elsewhere.
+
+## Workflow
+
+1. Gather required context and validate scope boundaries.
+2. Reject early with the reason when validation fails; otherwise continue.
+3. Execute deterministic steps in order, recording key decisions.
+4. Produce the required output artifact or terminal response.
+
+Workflow at a glance (include only when the flow branches):
+
+              [Trigger]
+                  |
+                  v
+          [Gather context]
+                  |
+                  v
+          [Validate scope] --(invalid)--> [Reject early]
+                  |
+              (valid)
+                  v
+      [Run deterministic steps]
+                  |
+                  v
+      [Produce output artifact]
+
+## Red Flags
+
+- Red flag: skipping validation of unknown external input.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "This is too small for process" | Process protects against regressions regardless of size. |
+
+## Philosophy / rationale
+
+- We optimize for explicit boundaries because they reduce rework and improve reliability.
+
+## Phase-gate checklist
+
+- [ ] Phase 1 complete and baseline checks captured.
+- [ ] Phase 2 complete and contract validation passed.
+
+## See Also
+
+- [review-security](../../review/review-security/SKILL.md) — run before committing any externally exposed change.
+
+## Examples
+
+Input: "Investigate this flaky suite"
+Output: concise root-cause summary, failing tests list, and next action.
+
+## Verification checklist
+
+- [ ] Output matches requested format.
+- [ ] Required tests/lints were run and results recorded.
+- [ ] No unrelated files were changed.
+```

package/extensions/post-merge-watch/README.md

@@ -0,0 +1,133 @@
+# Post-Merge Watch Extension
+
+Wakes an idle PI session with the verdict of a post-merge CI run.
+
+A human merges the feature PR, and the CI run for the merge commit decides what
+happens next: nothing, a fix, or a revert. That merge lands outside the session,
+so nothing tells the agent when the run concludes. This extension polls the
+deterministic post-merge check and delivers the verdict as a follow-up message,
+which starts a turn in an idle session.
+
+## Usage
+
+```bash
+pi --post-merge-watch <bead>
+```
+
+| Input | Meaning |
+| --- | --- |
+| `--post-merge-watch <bead>` | Watch the post-merge check for this bead and wake the session with the verdict |
+| `AGENT_CORTEX_POST_MERGE_CHECK` | Path of the check script, when the shipped one is not the one to run |
+
+The flag is registered at load time, so it is accepted on the command line. A
+session without the flag starts no watch, spawns no process, and writes no state.
+
+The default script is `skills/workflow/ralph/scripts/post-merge-check.mjs`,
+resolved relative to this extension's own file. In a staged install
+(`extensions/` beside `skills/`) and in a checkout of this repository the same
+relative path resolves, so no absolute path is baked in.
+
+## What it does
+
+1. At session start, with the flag set, it records the watch and runs the check.
+2. It runs the check every 15 seconds, up to 40 times (about 10 minutes).
+3. When the check exits `0` (passed) or `1` (failed), or the attempt cap is
+   reached, it sends one message and stops watching.
+
+Each invocation passes `--wait 0`, so the script reports once instead of waiting
+inside itself: the poll interval and the bound belong to this extension, and a
+stopped watch never blocks on a running child process.
+
+The wake uses the confirmed PI signature
+`pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true })`: an idle
+session starts a turn from it, and a session in the middle of a turn reads it
+after that turn instead of being interrupted.
+
+The message names the bead, the verdict, the exit code, the reason, the run URL,
+the project, and the number of checks made. It carries the same fields as message
+`details`, so a renderer can read them without parsing the text.
+
+## What it never does
+
+- **No verdict logic.** The check's exit code is the verdict: `0` passed, `1`
+  failed, every other code (including a timeout kill) inconclusive. The run URL
+  and the reason are read from the script's JSON report and forwarded verbatim.
+  The extension never decides whether a run passed and never re-runs a workflow.
+- **No model call.** No prompt, no summarisation, no title generation. One turn
+  happens only because the delivered message starts one.
+- **No `@earendil-works/*` value import.** Types only, so the staged install
+  loads with pi absent from the extension's own `node_modules`
+  (`test/pi-extensions-load.test.mjs` proves this).
+- **No second watch for the same bead.** A session reload re-fires
+  `session_start`; the extension starts one watch per bead.
+
+## State
+
+| Item | Value |
+| --- | --- |
+| Directory | `~/.pi/agent-cortex/post-merge-watch/` |
+| File name | `<project dir name>-<bead>-<digest of full project path and bead>.json` |
+| Written | At watch start, then after each poll |
+| Removed | When the watch settles, when the session shuts down, and again if a write was still in flight |
+
+The digest covers the whole project path, so two checkouts whose directory names
+match — or two projects watching the same bead — never share a file. A watch that
+is still polling is the only thing the directory should hold.
+
+The write and the removal can race: a stop removes the file, and a write that is
+still in flight then recreates it. The write therefore re-checks whether the
+watch stopped once it completes, and removes the file again, so a stop cannot
+leave a state file behind. One narrow case survives: a write that **fails** while
+a stop is in progress returns before that re-check, so it can leave a partial
+file. No code reads the directory, so a partial file is cosmetic; do not read it
+as a live watch.
+
+The in-flight record is diagnostic: it names the bead, the project, the script,
+the pid, the attempt count, and the last exit code and reason. Nothing reads it
+back, so a watch never resumes from it; a new session with the same flag starts a
+new watch.
+
+## Bounds and shutdown
+
+| Bound | Value |
+| --- | --- |
+| Poll interval | 15 s |
+| Checks | 40 |
+| One check invocation | 120 s, then pi kills it |
+
+The pending timer is unref'd, so a watch never holds the host process open. On
+`session_shutdown` the timer is cancelled, a check already in flight is ignored,
+and the state file is removed: an abandoned watch wakes nobody and leaves nothing
+behind.
+
+## What has been proven
+
+The wake path has been run once end to end against a stub check script: the RPC
+wake itself was reproduced (`agent_settled` → `agent_start`, the custom message
+arriving with no client prompt), and a real model turn ran on it. That run did not
+read a real CI run, because the shipped `post-merge-check.mjs` was replaced by a
+stub: the poll-and-wake path is proven, and the check's own judgement is covered
+by `test/post-merge-check.test.mjs`, not by any test here. Treat the pair as one
+path only after a watch has read a genuine merge-commit run.
+
+## Claude Code parity
+
+PI-only. Claude Code has its own watch tools, which the Claude side uses instead of
+an extension.
+
+## Development
+
+```bash
+pnpm test        # the poll lifecycle, the wake payload, the state file, the wiring
+pnpm typecheck   # tsc --noEmit
+```
+
+`watch.test.ts` drives the whole lifecycle with a scheduler it steps by hand and a
+check runner that returns scripted exit codes, so no test sleeps or waits on a
+timer. `index.test.ts` drives the extension through a partial `ExtensionAPI`
+double; the complete-literal guard that fails `tsc` when pi's interface grows is
+`extensions/agent-modes/index.test.ts`.
+
+To watch the poll end to end against a script that is not the shipped one, point
+`AGENT_CORTEX_POST_MERGE_CHECK` at any executable that follows the check's
+contract: JSON on stdout and exit `0`/`1`/`2`.

package/extensions/post-merge-watch/index.test.ts

@@ -0,0 +1,247 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { createTempRoot } from "../../test/helpers/temp-root.mjs";
+import postMergeWatchExtension, { CHECK_SCRIPT_ENV, WATCH_FLAG, checkScript } from "./index.ts";
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+const tempRoot = createTempRoot("post-merge-watch-index-");
+
+interface FlagRegistration {
+  name: string;
+  options: { description?: string; type: "string" | "boolean"; default?: string | boolean };
+}
+
+interface SentMessage {
+  message: { customType: string; content: string | unknown[]; display: boolean; details?: unknown };
+  options: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" } | undefined;
+}
+
+interface ExecCall {
+  command: string;
+  args: string[];
+  options: { cwd?: string; timeout?: number } | undefined;
+}
+
+/** An event handler as `pi.on` recorded it, called through `Reflect.apply`. */
+type RecordedHandler = (...args: never[]) => unknown;
+
+interface FakePi {
+  pi: ExtensionAPI;
+  flags: FlagRegistration[];
+  sent: SentMessage[];
+  execs: ExecCall[];
+  notifications: Array<{ message: string; type: string | undefined }>;
+  /** Fire every handler pi registered for `event`. */
+  fire(event: string, payload: unknown, context: unknown): Promise<void>;
+}
+
+/**
+ * A double for the five `ExtensionAPI` members this extension reaches.
+ *
+ * Deliberately partial: the complete-literal guard is
+ * `extensions/agent-modes/index.test.ts`, whose fake fails `tsc` when pi's
+ * interface grows a member.
+ */
+function createFakePi(options: {
+  flag: string | undefined;
+  scriptExitCode: number;
+  scriptStdout?: string;
+}): FakePi {
+  const flags: FlagRegistration[] = [];
+  const sent: SentMessage[] = [];
+  const execs: ExecCall[] = [];
+  const notifications: Array<{ message: string; type: string | undefined }> = [];
+  const handlers = new Map<string, RecordedHandler[]>();
+
+  const pi = {
+    registerFlag: (name: string, registration: FlagRegistration["options"]) => {
+      flags.push({ name, options: registration });
+    },
+    getFlag: (name: string) => (name === WATCH_FLAG ? options.flag : undefined),
+    on: (event: string, handler: RecordedHandler) => {
+      handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+      return () => {};
+    },
+    exec: async (command: string, args: string[], execOptions: ExecCall["options"]) => {
+      execs.push({ command, args, options: execOptions });
+      return {
+        stdout: options.scriptStdout ?? "",
+        stderr: "",
+        code: options.scriptExitCode,
+        killed: false,
+        truncated: false,
+      };
+    },
+    sendMessage: (message: SentMessage["message"], sendOptions?: SentMessage["options"]) => {
+      sent.push({ message, options: sendOptions });
+    },
+  } as unknown as ExtensionAPI;
+
+  return {
+    pi,
+    flags,
+    sent,
+    execs,
+    notifications,
+    async fire(event, payload, context) {
+      for (const handler of handlers.get(event) ?? []) {
+        await Reflect.apply(handler, undefined, [
+          payload,
+          {
+            cwd: "/projects/one",
+            ui: { notify: (message: string, type?: string) => notifications.push({ message, type }) },
+            ...(context as object),
+          },
+        ]);
+      }
+    },
+  };
+}
+
+/** The startup event pi sends before a session is usable. */
+const SESSION_START = { type: "session_start", reason: "startup" } as const;
+
+/** Run one session start with `HOME` pointed at a temp root, so no test reads the real home. */
+async function withTempHome<T>(run: (home: string) => Promise<T>): Promise<T> {
+  const home = await tempRoot.createWorkspace();
+  const previousHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    return await run(home);
+  } finally {
+    process.env.HOME = previousHome;
+  }
+}
+
+/** The state directory the extension uses for a given home. */
+function stateDirFor(home: string): string {
+  return join(home, ".pi", "agent-cortex", "post-merge-watch");
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Flag registration ───────────────────────────────────────────────────────
+
+describe("post-merge-watch extension", () => {
+  it("registers its CLI flag in the factory, before any session starts", async () => {
+    const fake = createFakePi({ flag: undefined, scriptExitCode: 2 });
+
+    postMergeWatchExtension(fake.pi);
+
+    assert.deepEqual(
+      fake.flags.map((flag) => ({ name: flag.name, type: flag.options.type })),
+      [{ name: "post-merge-watch", type: "string" }],
+    );
+  });
+
+  it("resolves the shipped check script without a hardcoded absolute path", () => {
+    const previous = process.env[CHECK_SCRIPT_ENV];
+    delete process.env[CHECK_SCRIPT_ENV];
+    try {
+      assert.match(checkScript(), /skills[/\\]workflow[/\\]ralph[/\\]scripts[/\\]post-merge-check\.mjs$/);
+    } finally {
+      if (previous !== undefined) process.env[CHECK_SCRIPT_ENV] = previous;
+    }
+  });
+
+  it("polls the script the environment names, so an install can be pointed at a stub", async () => {
+    const previous = process.env[CHECK_SCRIPT_ENV];
+    process.env[CHECK_SCRIPT_ENV] = "/stub/post-merge-check.mjs";
+    try {
+      assert.equal(checkScript(), "/stub/post-merge-check.mjs");
+    } finally {
+      if (previous === undefined) delete process.env[CHECK_SCRIPT_ENV];
+      else process.env[CHECK_SCRIPT_ENV] = previous;
+    }
+  });
+
+  // ─── Session lifecycle ─────────────────────────────────────────────────────
+
+  it("starts one watch at session start and wakes the session when the check settles", async () => {
+    await withTempHome(async (home) => {
+      const fake = createFakePi({
+        flag: "agnt-ctx-86u4.2",
+        scriptExitCode: 1,
+        scriptStdout: JSON.stringify({ reason: "run-failed", runs: [{ url: "https://gh/run/9" }] }),
+      });
+      postMergeWatchExtension(fake.pi);
+
+      await fake.fire("session_start", SESSION_START, {});
+
+      assert.equal(fake.execs.length, 1);
+      assert.deepEqual(
+        { args: fake.execs[0].args.slice(1), cwd: fake.execs[0].options?.cwd },
+        { args: ["--wait", "0"], cwd: "/projects/one" },
+      );
+      assert.equal(fake.sent.length, 1);
+      assert.deepEqual(fake.sent[0].options, { deliverAs: "followUp", triggerTurn: true });
+      assert.match(fake.sent[0].message.content as string, /agnt-ctx-86u4\.2/);
+      assert.deepEqual(fake.sent[0].message.details, {
+        bead: "agnt-ctx-86u4.2",
+        verdict: "failed",
+        runUrl: "https://gh/run/9",
+        exitCode: 1,
+        reason: "run-failed",
+        attempts: 1,
+        project: "/projects/one",
+      });
+    });
+  });
+
+  it("starts no watch when the flag is absent", async () => {
+    await withTempHome(async (home) => {
+      const fake = createFakePi({ flag: undefined, scriptExitCode: 1 });
+      postMergeWatchExtension(fake.pi);
+
+      await fake.fire("session_start", SESSION_START, {});
+
+      assert.deepEqual(fake.execs, []);
+      assert.equal(await exists(stateDirFor(home)), false);
+    });
+  });
+
+  it("records the watch under the agent-cortex state directory, then clears it on session shutdown", async () => {
+    await withTempHome(async (home) => {
+      const fake = createFakePi({ flag: "agnt-ctx-86u4.2", scriptExitCode: 2 });
+      postMergeWatchExtension(fake.pi);
+
+      await fake.fire("session_start", SESSION_START, {});
+
+      assert.deepEqual(
+        (await readdir(stateDirFor(home))).length,
+        1,
+        "the in-flight watch is recorded under ~/.pi/agent-cortex",
+      );
+      assert.equal(fake.sent.length, 0, "no verdict yet, so no wake");
+
+      await fake.fire("session_shutdown", { type: "session_shutdown", reason: "quit" }, {});
+
+      assert.deepEqual(await readdir(stateDirFor(home)), [], "an abandoned watch leaves no state file");
+      assert.deepEqual(fake.sent, [], "an abandoned watch wakes nobody");
+    });
+  });
+
+  it("starts no second watch when the session reloads for the same bead", async () => {
+    await withTempHome(async () => {
+      const fake = createFakePi({ flag: "agnt-ctx-86u4.2", scriptExitCode: 2 });
+      postMergeWatchExtension(fake.pi);
+
+      await fake.fire("session_start", SESSION_START, {});
+      await fake.fire("session_start", { type: "session_start", reason: "reload" }, {});
+
+      assert.equal(fake.execs.length, 1);
+    });
+  });
+});