@jaybeeuu/agent-cortex 1.39.0 → 1.41.0

package/pi/settings.json

@@ -4,26 +4,37 @@
     "maxNameLength": 40,
     "maxSummaryLength": 100
   },
-  "lastChangelogVersion": "0.83.0",
+  "lastChangelogVersion": "0.87.1",
   "packages": [
-    "../../src/agent-cortex",
+    {
+      "source": "../../src/agent-cortex",
+      "skills": []
+    },
     "npm:pi-web-access@0.10.7",
     "npm:@getpipher/vision",
     "npm:@hypabolic/pi-hypa",
-    "npm:context-mode"
+    "npm:context-mode",
+    "npm:pi-questions"
   ],
   "defaultProvider": "opencode-go",
-  "defaultModel": "qwen3.7-max",
+  "defaultModel": "deepseek-v4.1-flash",
   "theme": "dark",
   "defaultThinkingLevel": "high",
   "enabledModels": [
-    "opencode/nemotron-3-ultra-free",
-    "opencode-go/qwen3.7-max",
-    "opencode/kimi-k2.7-code",
-    "opencode/mimo-v2.5-free",
-    "opencode-go/mimo-v2.5",
-    "opencode/deepseek-v4-flash-free",
+    "opencode/big-pickle",
+    "opencode-go/qwen3.7-plus",
     "opencode-go/deepseek-v4-flash",
-    "opencode/big-pickle"
-  ]
+    "opencode-go/kimi-k3",
+    "opencode/deepseek-v4-flash",
+    "opencode/mimo-v2.5-free",
+    "opencode-go/deepseek-v4.1-flash"
+  ],
+  "compaction": {
+    "enabled": true
+  },
+  "steeringMode": "all",
+  "followUpMode": "all",
+  "tuiMode": "regular",
+  "treeFilterMode": "default",
+  "hideThinkingBlock": true
 }

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-cortex",
   "description": "Personal Copilot CLI plugin with custom agents and skills",
-  "version": "1.39.0",
+  "version": "1.41.0",
   "author": {
     "name": "jaybeeuu"
   },

package/scripts/build-copilot-agents.mjs

@@ -27,4 +27,4 @@ import { installCopilot } from "../bin/installers/copilot.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
-installCopilot({ root: ROOT, output: join(ROOT, "agents") });
+await installCopilot({ root: ROOT, output: join(ROOT, "agents") });

package/scripts/check-no-sync.mjs

@@ -0,0 +1,49 @@
+// Repo convention: never block the main thread — no `*Sync` functions
+// (fs/child_process/...) in tooling code. Runs via `pnpm lint` (CI) and
+// locally. Scans the toolchain and test dirs: bin/, scripts/, lib/, hooks/,
+// test/. Skill-owned scripts (skills/*/scripts) and extensions are separate
+// follow-up surfaces tracked outside this check.
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(fileURLToPath(new URL(".", import.meta.url)), "..");
+const SCAN_DIRS = ["bin", "scripts", "lib", "hooks", "test"];
+const EXTENSIONS = new Set([".mjs", ".js", ".ts"]);
+const SELF = "scripts/check-no-sync.mjs";
+
+const SYNC_CALL = /\b\w*Sync\s*\(/;
+
+/** Recursively collect files under dir, skipping this script and node_modules. */
+async function collect(dir) {
+  const out = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (e.name === "node_modules") continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await collect(full)));
+    else if (EXTENSIONS.has(e.name.slice(e.name.lastIndexOf(".")))) out.push(full);
+  }
+  return out;
+}
+
+const offenders = [];
+for (const dir of SCAN_DIRS) {
+  const abs = join(ROOT, dir);
+  for (const file of await collect(abs)) {
+    const rel = relative(ROOT, file);
+    if (rel === SELF) continue;
+    const src = await readFile(file, "utf-8");
+    const hits = src.split("\n").map((line, i) => ({ line: i + 1, text: line })).filter((l) => SYNC_CALL.test(l.text));
+    if (hits.length) offenders.push({ rel, hits });
+  }
+}
+
+if (offenders.length) {
+  console.error("✗ Never block the main thread — *Sync function calls found:");
+  for (const { rel, hits } of offenders) {
+    for (const { line, text } of hits) console.error(`  ${rel}:${line}: ${text.trim()}`);
+  }
+  process.exit(1);
+}
+console.log("✓ no *Sync calls in tooling code (bin/, scripts/, lib/, hooks/, test/)");

package/scripts/lib/compose-agent.mjs

@@ -29,9 +29,19 @@
 //
 // Zero dependencies so it runs on the CI Node (20) and local Node alike.
 
-import { readFileSync, existsSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 
+/** True when a path exists (stat succeeds). */
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // ─── Token substitution ──────────────────────────────────────────────────────
 
 const TOOL_RE = /\{\{TOOL:([^}]+)\}\}/g;
@@ -92,22 +102,30 @@ export function substituteTokens(content, harness, tokenMap, options = {}) {
  * @param {string} harness Harness id: "copilot" | "claude" | "pi"
  * @returns {{ name: string, description: string, tools: string[], model?: string, argumentHint?: string, body: string }}
  */
-export function composeAgent(root, name, harness, options = {}) {
+export async function composeAgent(root, name, harness, options = {}) {
   const { dropNullTools = false, pluginRoot, resolveRelativePaths = false, warn = noop } = options;
   const agentDir = join(root, "agents", name);
-  const frontmatter = parseFrontmatter(join(agentDir, harness, "frontmatter.json"), name, harness);
-  const tokenMap = loadTokenMap(root);
+  const frontmatter = await parseFrontmatter(join(agentDir, harness, "frontmatter.json"), name, harness);
+  const tokenMap = await loadTokenMap(root);
 
-  let body = readFileSync(join(agentDir, "agent.md"), "utf-8");
+  let body = await readFile(join(agentDir, "agent.md"), "utf-8");
 
-  // 1. {{SECTION:name}} → <harness>/<name>.md (may itself contain TOOL/PATH tokens)
-  body = body.replace(/\{\{SECTION:([^}]+)\}\}/g, (_token, section) => {
+  // 1. {{SECTION:name}} → <harness>/<name>.md (may itself contain TOOL/PATH
+  //    tokens). Single pass over the original body — inserted section content
+  //    is never rescanned (same semantics as the sync replace()).
+  const sectionRe = /\{\{SECTION:([^}]+)\}\}/g;
+  let out = "";
+  let last = 0;
+  for (let m = sectionRe.exec(body); m; m = sectionRe.exec(body)) {
+    const section = m[1];
     const sectionPath = join(agentDir, harness, `${section}.md`);
-    if (!existsSync(sectionPath)) {
+    if (!(await pathExists(sectionPath))) {
       throw new Error(`agent "${name}": missing section "${section}" for harness "${harness}" (${sectionPath})`);
     }
-    return readFileSync(sectionPath, "utf-8").trim();
-  });
+    out += body.slice(last, m.index) + (await readFile(sectionPath, "utf-8")).trim();
+    last = m.index + m[0].length;
+  }
+  body = out + body.slice(last);
 
   // 2. + 3. TOOL/PATH substitution (contextualised for error messages)
   body = substituteTokens(body, harness, tokenMap, {
@@ -127,8 +145,8 @@ const REQUIRED_FIELDS = ["name", "description", "tools"];
 const KNOWN_OPTIONAL_FIELDS = ["model", "argumentHint"];
 
 /** Parse and schema-check a harness frontmatter.json (strict, per agents/README.md). */
-function parseFrontmatter(path, name, harness) {
-  const raw = readFileSync(path, "utf-8");
+async function parseFrontmatter(path, name, harness) {
+  const raw = await readFile(path, "utf-8");
   let fm;
   try {
     fm = JSON.parse(raw);
@@ -225,11 +243,11 @@ export function translateToolList(tools, tokenMap, harness, { warn = noop } = {}
 // ─── Token map ───────────────────────────────────────────────────────────────
 
 /** Load token-map.json from the package root; missing/incomplete maps hard-fail. */
-export function loadTokenMap(root) {
+export async function loadTokenMap(root) {
   const path = join(root, "token-map.json");
   let raw;
   try {
-    raw = readFileSync(path, "utf-8");
+    raw = await readFile(path, "utf-8");
   } catch {
     throw new Error(`missing ${path} — the composer requires token-map.json`);
   }

package/scripts/lib/fs.mjs

@@ -0,0 +1,31 @@
+// Shared async filesystem predicates. The install-time generators all need the
+// same "does this path exist and is it a file/directory?" probe, and the repo
+// convention is async-only (no *Sync) in tooling code — see scripts/check-no-sync.mjs.
+//
+// Both probes are stat-based and resolve `false` on any error (missing path,
+// permission denied, broken symlink), so callers can branch on existence
+// without a separate try/catch:
+//
+//   if (await isFile(join(dir, "agent.md"))) { … }
+//
+// Zero dependencies so it runs on the CI Node (20) and local Node alike.
+
+import { stat } from "node:fs/promises";
+
+/** True when `p` exists and is a regular file; false on any error. */
+export async function isFile(p) {
+  try {
+    return (await stat(p)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** True when `p` exists and is a directory; false on any error. */
+export async function isDirectory(p) {
+  try {
+    return (await stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/skills/engineering/grill-with-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grill-with-docs
-description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when the user wants to stress-test a plan against their project's language and documented decisions: "grill my plan", "check this against our docs".
+description: "Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when the user wants to stress-test a plan against their project's language and documented decisions: \"grill my plan\", \"check this against our docs\"."
 ---
 
 # Grill With Docs

package/skills/planning/classify-bead/REFERENCE.md

@@ -0,0 +1,85 @@
+# classify-bead reference
+
+Detail behind `SKILL.md`. The executable `scripts/classify-bead.mjs` is the source of
+truth for the deterministic tiers; this document mirrors it for verification.
+
+## Tier precedence
+
+| Tier | `source` | Evidence | Applies the label? |
+|---|---|---|---|
+| 1 | `label` | An `implementation-type:afk` or `implementation-type:hitl` label is already present | no — it is already there |
+| 2 | `type-field` | The legacy `## Type` section in the bead body declares `AFK`/`HITL` (block or inline form, case-insensitive) | yes |
+| 3 | `heuristic` | A conservative natural-language signal (below) | yes |
+| 4 | *(none)* | Nothing deterministic matched → `escalate: true`; a small/cheap model applies the rubric | after the model decides |
+
+When both `implementation-type` labels are present, AFK wins — matching the
+pre-existing skill wording, which checks `implementation-type:afk` first.
+
+The classifier runs `bd show <id> --json` and `bd tag <id> <label>`; it never
+re-reads prose from the rendered `bd show` output.
+
+## Heuristic signals
+
+Heuristics only fire on explicit phrasing. They are checked in this order,
+mirroring the rubric's "a human is required if any criterion is true" rule.
+
+HITL (human required):
+
+- `requires human`, `human sign-off|approval|judgement|decision`
+- `manual step|action|intervention`
+- `visually review|inspect|verify`
+- `stakeholder sign-off|approval`
+- `credentials|secrets setup|rotation|provisioning`
+- `provisioning` within 40 characters of `infrastructure|infra|server|cluster`
+
+AFK (explicitly no human):
+
+- `no human action|input|review|intervention|judgement`
+
+AFK (machine-checkable acceptance):
+
+- `machine-checkable`
+- `automated test|tests|check|checks|verification`
+
+Anything else escalates. Widening this list trades model calls for
+misclassification risk; only add phrasing that maps directly onto a rubric
+criterion.
+
+Matching is literal, not semantic, and the patterns are not negation-aware —
+"no human approval is required" still matches the HITL tier. The error direction
+is toward HITL, which is visible and correctable, so prefer unambiguous phrasing
+over more patterns.
+
+## CLI
+
+```bash
+node classify-bead.mjs <bead-id> [--dry-run]   # resolve (and tag) one bead
+node classify-bead.mjs --audit [--limit <n>]   # measure the split over recent beads
+```
+
+Run from the target project's directory — `bd` resolves its beads DB from cwd.
+JSON goes to stdout:
+
+- Classification: `{ id, classification, source, reason, escalate, applied, label }`
+- Audit: `{ sampled, bySource, deterministic, needsRubric, deterministicRatio }`
+
+Exit codes: `0` success (including `escalate`, which is a valid outcome), `2`
+usage error, `1` `bd` failure. `BD_PATH` overrides the `bd` executable.
+
+## Measured split
+
+This is the "measure first" number that sizes the win over spawning a subagent.
+Reproduce it against the repo's beads DB:
+
+```bash
+node <skill-scripts>/classify-bead.mjs --audit --limit 100
+```
+
+Measured 2026-09-18 on `agent-cortex`: 78 of the newest 100 beads resolved
+deterministically (77 from an existing label, 1 from a heuristic) and 22 needed
+the rubric. That is the share of classifications that skip the model entirely
+when the caller runs the classifier before spawning a subagent. The sample is
+the newest 100 beads, so the ratio moves as beads are created — re-run the
+command rather than quoting this snapshot. The deterministic rate is higher on
+backlogs labelled at planning time; freshly created beads with neither a label
+nor a `## Type` field lean on the heuristic tier.

package/skills/planning/classify-bead/SKILL.md

@@ -5,7 +5,7 @@ description: Classify a bead as AFK or HITL and apply the implementation-type la
 
 # Classify Bead
 
-Determine whether a bead requires human action (HITL) or can be completed autonomously by an agent (AFK), then persist the result as an `implementation-type` label.
+Determine whether a bead requires human action (HITL) or can be completed autonomously by an agent (AFK), then persist the result as an `implementation-type` label. A deterministic classifier settles the common cases; only genuine rubric judgement reaches a model.
 
 ## When to use
 
@@ -21,71 +21,67 @@ Determine whether a bead requires human action (HITL) or can be completed autono
 
 ## Invocation
 
-Run this skill as a background subagent via {{TOOL:task}} so bead content never loads into the calling agent's context. Classification is a rubric lookup, not code generation — a small, cheap model is sufficient. Pass the bead ID and the `bd prime` output; the subagent runs the workflow below and reports back the classification plus the `bd tag` command it applied.
+Run the deterministic classifier first. It resolves the existing label, the legacy `## Type` field, and explicit heuristic signals without a model call:
 
-Only run inline when no task-spawning capability exists in the current environment.
+```bash
+# Run from the TARGET project's directory — bd resolves its beads DB from cwd.
+node <skill-scripts>/classify-bead.mjs <bead-id>
+```
 
-**Callers should check `bd label list <id>` themselves first.** If `implementation-type` is already present, skip spawning this skill entirely — spawning a subagent purely to re-read a label that already exists wastes a full agent call.
+- Output carries `"classification": "afk" | "hitl"` → done. The classifier applied the label; report the classification. Do not spawn a subagent.
+- Output carries `"escalate": true` → no deterministic signal. Spawn this skill as a background subagent via {{TOOL:task}} (a small, cheap model) with the bead ID and the `bd prime` output; the subagent applies the rubric below and tags the bead.
+- `--dry-run` resolves without applying the label. `--audit [--limit <n>]` reports the deterministic-vs-rubric split over recent beads.
 
-## Workflow
-
-1. **Check for an existing label.**
-
-   ```bash
-   bd label list <id>
-   ```
+`<skill-scripts>` is the absolute path to this skill's own `scripts/` directory, resolved from wherever this skill was loaded — it varies by harness and install location, so never hardcode one harness's path. Only run inline when no task-spawning capability exists in the current environment.
 
-   - `implementation-type:afk` present → classification is **AFK**. Stop here.
-   - `implementation-type:hitl` present → classification is **HITL**. Stop here.
+**Callers should run the classifier themselves before spawning this subagent.** If `implementation-type` is already present, or the classifier resolves the bead, there is no subagent call to make.
 
-2. **Check the `## Type` field (back-compat).**
+## Workflow
 
-   ```bash
-   bd show <id>
-   ```
+1. **Check for an existing label.** `bd label list <id>` — `implementation-type:afk` present → **AFK**; `implementation-type:hitl` present → **HITL**. Stop.
 
-   Locate the `## Type` section in the bead body. `HITL` or `AFK` (case-insensitive) determines the classification; continue to step 4. This field predates the label system, so treat it as authoritative when present.
+2. **Run the deterministic classifier.** `node <skill-scripts>/classify-bead.mjs <id>`. A resolved classification is already tagged; stop and report it.
 
-3. **Classify from first principles** — only when neither the label nor the `## Type` field is present. Read the full bead body and apply the rubric:
+3. **Apply the rubric** — only when the classifier reports `escalate: true`. Read the full bead body:
 
-   **HITL** — the bead requires a human if at least one of the following is true:
+   **HITL** — a human is required if at least one of the following holds:
    - The outcome cannot be verified by an agent (e.g. visual review, stakeholder sign-off, UX judgement call).
    - A manual action only a human can perform is required (e.g. credential setup, secrets management, external service configuration, infrastructure provisioning outside the codebase).
    - A decision must be made that the agent cannot make unilaterally (e.g. architectural choice between equally valid options, regulatory or legal sign-off).
 
-   **AFK** — the agent can implement, verify, and complete the task autonomously, and all acceptance criteria are machine-checkable.
-
-4. **Apply the label.**
+   **AFK** — otherwise: the agent can implement, verify, and complete the task autonomously, and all acceptance criteria are machine-checkable.
 
-   ```bash
-   bd tag <id> implementation-type:afk    # or implementation-type:hitl
-   ```
+4. **Apply the label.** `bd tag <id> implementation-type:afk` (or `:hitl`). The classifier does this for the deterministic tiers; do it yourself only after step 3.
 
 5. **Return the classification.** Report `AFK` or `HITL` so the calling skill or agent can act on it.
 
+Tier precedence (label → `## Type` → heuristics → rubric), the heuristic signal list, the CLI contract, and the measured deterministic split are in `REFERENCE.md`.
+
 ## Red Flags
 
-- Classifying a bead without the caller-side `bd label list` check — you either overwrite a recorded decision or waste an agent spawn re-reading a label that already exists.
+- Classifying a bead without the caller-side `bd label list` check — you either overwrite a recorded decision or waste a call re-reading a label that already exists.
+- Spawning the rubric subagent when the classifier returned a classification — the deterministic tier is the point.
 - Defaulting to HITL for a complex task whose acceptance criteria are machine-checkable — complexity alone is not a criterion.
-- Choosing a class without reading the bead body when neither the label nor `## Type` is present.
+- Choosing a class without reading the bead body when the classifier escalated.
 
 ## Common Rationalizations
 
 | Rationalization | Rebuttal |
-|---|---|
 | "This task is complex, so it must be HITL" | Complexity is not a criterion. HITL applies only when a human is genuinely required to complete or verify. |
 | "I'll mark it HITL to be safe" | HITL consumes scarce human attention. Prefer AFK — ralph's review gates still catch agent mistakes. |
-| "The label is probably already there, I'll skip the check" | One `bd label list` command settles it. Skipping it either overwrites a decision or spawns an agent to re-read a label. |
+| "The label is probably already there, I'll skip the check" | One `bd label list` command settles it, and the classifier checks it too. |
+| "Heuristics are good enough for this one" | The classifier uses conservative, explicit signals only. If it escalated, read the body. |
 
 ## Philosophy / rationale
 
-- Classification gates automation against human attention: AFK beads feed ralph's autonomous pipeline, HITL beads are routed to a person. We prefer AFK because human time is the scarce resource, and later review gates still catch agent mistakes — escalate only when completion or verification genuinely requires a human.
-- The rubric is deterministic, so this skill is a lookup rather than deep reasoning — which is why a cheap subagent suffices and the step 1 early exit exists.
+- Classification gates automation against human attention: AFK beads feed ralph's autonomous pipeline, HITL beads route to a person. Prefer AFK because human time is the scarce resource, and later review gates still catch agent mistakes.
+- The rubric is deterministic, so most classifications are a lookup. The executable encodes that lookup once, and the model is reserved for beads whose evidence is genuinely ambiguous.
 
 ## Verification checklist
 
 - [ ] `bd label list <id>` was checked before any other step.
-- [ ] Classification followed the precedence order: existing label → `## Type` → first-principles rubric.
-- [ ] The full bead body was read before classifying from first principles (step 3).
-- [ ] `bd tag <id> implementation-type:<afk|hitl>` was applied.
-- [ ] The calling skill or agent received the classification in the report.
+- [ ] The deterministic classifier ran before any rubric subagent.
+- [ ] A rubric subagent ran only when the classifier reported `escalate: true`.
+- [ ] The full bead body was read before classifying from first principles.
+- [ ] `bd tag <id> implementation-type:<afk|hitl>` is present afterwards.
+- [ ] The calling skill or agent received the classification in the report.