liteagents 2.24.1 → 3.5.0

package/packages/ampcode/skills/remember/sync-rules.cjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * sync-rules.cjs — keeps a repo's AGENT_RULES.md current with the installed
+ * template, without ever destroying what was there.
+ *
+ * Run every /remember, from the target repo. Before this existed, the rules
+ * were bootstrapped once and never refreshed, so a measured 35 local repos
+ * drifted to a body many releases old and three hand sweeps failed to hold.
+ *
+ * Three outcomes, decided by a byte compare — not a stored hash, because the
+ * only question is "am I about to change this file?", which any careful copy
+ * asks anyway:
+ *
+ *   absent     copy it in and say so
+ *   identical  do nothing at all: no write, no backup, no output
+ *   differs    move the old body aside, copy the new one in, say so loudly
+ *
+ * THE BACKUP IS A SINGLE FILE and is overwritten on each differing run. A
+ * customised file therefore survives exactly one update: fold your changes
+ * into the new AGENT_RULES.md before the next release, or the next sync
+ * replaces the backup with a vanilla body. This is a deliberate trade — see
+ * docs/product/agent-rules-freshness-prd.md §5 — chosen over accumulating
+ * timestamped backups.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Per-kit PROJECT dir. NOTE this is not always the global config dir: amp
+// installs to ~/.config/amp but writes .amp/ in a repo, and opencode likewise.
+// This is the ONE line that differs across packages.
+const PROJECT_DIR = '.amp';
+
+const RULES = 'AGENT_RULES.md';
+const BACKUP = 'AGENT_RULES.md.bak';   // keeps the origin name; not .md, so doc tooling ignores it
+
+/** lstat, not existsSync: existsSync follows links, so a DANGLING link reads
+ *  as absent and gets walked straight past. */
+function lexists(p) {
+  try { fs.lstatSync(p); return true; } catch (e) { return false; }
+}
+
+/**
+ * True when writing to `target` would land outside `repo`.
+ *
+ * There are two ways out and a guard on only one of them is false safety:
+ * `target` may itself be a symlink — including a dangling one, which reads as
+ * "the file is absent" and is still followed on write — or any parent
+ * directory may be a link pointing elsewhere. This runs across a whole fleet
+ * of repos, so a relative link only has to reach a sibling checkout.
+ *
+ * A link that stays INSIDE the repo is not an escape: a repo that keeps its
+ * rules or its config behind an in-repo symlink is an ordinary setup, and
+ * refusing it would strand that repo forever. So the leaf is followed by hand
+ * with readlink — which works on a dangling link, where realpath cannot — and
+ * each hop re-resolves the parents, because the file a link points at can sit
+ * behind a linked directory of its own.
+ */
+function escapesRepo(repo, target) {
+  let root;
+  try { root = fs.realpathSync(repo); } catch (e) { return true; }
+
+  let p = path.resolve(target);
+  for (let hop = 0; hop < 40; hop++) {
+    // Resolve the existing part of the path. Walk up to the deepest ancestor
+    // that exists; anything below it cannot be a link yet.
+    const tail = [];
+    let dir = path.dirname(p);
+    while (!lexists(dir)) {
+      tail.unshift(path.basename(dir));
+      const up = path.dirname(dir);
+      if (up === dir) return true;                  // walked off the filesystem root
+      dir = up;
+    }
+    try { p = path.join(fs.realpathSync(dir), ...tail, path.basename(p)); }
+    catch (e) { return true; }                      // an ancestor is a dangling link
+
+    let to;
+    try { to = fs.readlinkSync(p); } catch (e) {
+      return p !== root && !p.startsWith(root + path.sep);   // not a link: decide here
+    }
+    p = path.resolve(path.dirname(p), to);
+  }
+  return true;                                      // a link cycle: refuse
+}
+
+function templatePath() {
+  // Ships beside this script, so no path guessing and no dependence on where
+  // the kit was installed.
+  return path.join(__dirname, RULES);
+}
+
+function targetPath(repo) {
+  return path.join(repo, PROJECT_DIR, 'remember', RULES);
+}
+
+/**
+ * @returns {{action:string, detail?:string}} action is one of:
+ *   'no-template' | 'bootstrapped' | 'unchanged' | 'updated' | 'failed'
+ */
+function sync(repo) {
+  const tpl = templatePath();
+  let template;
+  try {
+    template = fs.readFileSync(tpl);
+  } catch (e) {
+    return { action: 'no-template', detail: tpl };
+  }
+
+  const target = targetPath(repo);
+  if (escapesRepo(repo, target)) return { action: 'escapes', detail: target };
+
+  let current = null;
+  try { current = fs.readFileSync(target); } catch (e) { /* absent */ }
+
+  // Byte compare. No normalisation on either side: the copy below is a plain
+  // byte write, so a mismatch here means the content really differs.
+  if (current && current.equals(template)) return { action: 'unchanged' };
+
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (current) {
+      // Single backup, overwritten. rename() is atomic on the same filesystem
+      // and cannot leave a half-written backup the way copy+truncate could.
+      fs.renameSync(target, path.join(path.dirname(target), BACKUP));
+    }
+    fs.writeFileSync(target, template);
+  } catch (e) {
+    return { action: 'failed', detail: e.message };
+  }
+
+  return current ? { action: 'updated' } : { action: 'bootstrapped' };
+}
+
+function main() {
+  const repo = process.argv[2] || process.cwd();
+  const r = sync(repo);
+  const rel = path.join(PROJECT_DIR, 'remember', RULES);
+
+  switch (r.action) {
+    case 'unchanged':
+      break;                                  // silent: nothing happened
+    case 'bootstrapped':
+      process.stdout.write(`${rel} created from the installed template\n`);
+      break;
+    case 'updated':
+      process.stdout.write(
+        `${rel} updated from the installed template `
+        + `(previous body kept as ${BACKUP} — fold your changes in before the `
+        + `next release, it is a single file and the next update replaces it)\n`);
+      break;
+    case 'escapes':
+      // Loud, never repaired: the path is under the repo but does not stay
+      // there, so any write lands somewhere the run was not invited.
+      process.stdout.write(
+        `${rel} not synced: it leaves the repo via a symlink — refusing to `
+        + `write through it\n`);
+      break;
+    case 'no-template':
+      // Loud: this means the install is incomplete, not that nothing changed.
+      process.stdout.write(
+        `AGENT_RULES.md not synced: no template beside this script (${r.detail})\n`);
+      break;
+    case 'failed':
+      process.stdout.write(`AGENT_RULES.md not synced: ${r.detail}\n`);
+      break;
+  }
+}
+
+if (require.main === module) {
+  // A passenger on /remember, like version-check.cjs: it never gets to fail
+  // the run it rides in.
+  try { main(); } catch (e) { /* silent */ }
+}
+
+module.exports = { sync, PROJECT_DIR, RULES, BACKUP };

package/packages/ampcode/skills/remember/version-check.cjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * version-check.cjs — tells the user their liteagents install is behind the
+ * registry, and nothing else.
+ *
+ * Run as step 0 of /remember, alongside friction.cjs. It rides along with a
+ * memory consolidation run, so the only hard requirement is that it can never
+ * cost that run anything: it exits 0 on every path, prints at most one line,
+ * writes nothing but its own cache, and is bounded in wall-clock time.
+ *
+ * Deliberately NOT part of friction.cjs: that file mines friction signals, and
+ * a registry lookup is an unrelated concern.
+ *
+ * A POC (2026-09-03) found the one non-obvious defect guarded here:
+ * req.setTimeout is a socket-INACTIVITY timeout and does not bound connect
+ * time. Against an unroutable host a 2000ms budget overran to 5146ms. Only an
+ * explicit deadline bounds the total, so both are set.
+ *
+ * Environment:
+ *   npm_config_registry            registry base (npm sets this; mirrors work)
+ *   LITEAGENTS_INSTALLED_VERSION   skip local version discovery
+ *   LITEAGENTS_SKIP_NPM_LOOKUP     skip the `npm ls -g` fallback (it is slow)
+ *
+ * Installed version is resolved in cost order: the installer's manifest stamp
+ * (a file read), then our own package.json when run from a checkout, then
+ * `npm ls -g` as a last resort. The last one costs ~500ms on EVERY run, which
+ * is why the installer stamps the manifest at all.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const PKG = 'liteagents';
+// Per-kit config dir. This is the ONE line that differs across packages.
+const CONFIG_DIR = '.claude';
+const TTL_MS = 24 * 60 * 60 * 1000;
+const DEADLINE_MS = 2000;
+const NPM_LOOKUP_MS = 3000;
+
+// --- version comparison --------------------------------------------------
+
+/**
+ * Is `b` a newer release than `a`? Numeric per component, so 2.9.0 < 2.10.0 —
+ * a string compare gets that backwards. A prerelease suffix is stripped, so
+ * 2.24.2-beta.1 counts as newer than 2.24.1: it is still a later release, and
+ * a user on it does not need advice about 2.24.1.
+ */
+function isNewer(a, b) {
+  const parse = (v) => String(v).trim().replace(/^v/, '').split('-')[0]
+    .split('.').map((n) => parseInt(n, 10) || 0);
+  const [x, y] = [parse(a), parse(b)];
+  for (let i = 0; i < 3; i++) {
+    const d = (y[i] || 0) - (x[i] || 0);
+    if (d !== 0) return d > 0;
+  }
+  return false;
+}
+
+// --- installed version ---------------------------------------------------
+
+// Walk up from this file looking for our own package.json. Finds it when
+// running from a checkout; finds nothing when installed into ~/.claude, which
+// is why the npm fallback exists.
+function versionFromPackageJson() {
+  let dir = __dirname;
+  for (let i = 0; i < 8; i++) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+      if (pkg && pkg.name === PKG && pkg.version) return String(pkg.version);
+    } catch (e) { /* keep walking */ }
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+// The installer stamps the release it wrote into <install root>/manifest.json.
+// version-check.cjs sits at <root>/<skills|commands|command>/remember/, so the root
+// two levels up. This is the fast path: reading a file beats spawning npm.
+function versionFromManifest() {
+  try {
+    const m = JSON.parse(fs.readFileSync(
+      path.join(__dirname, '..', '..', 'manifest.json'), 'utf8'));
+    // NOT m.version -- that is the manifest schema version, a different thing.
+    return m && m.liteagents_version ? String(m.liteagents_version) : null;
+  } catch (e) { return null; }
+}
+
+function versionFromNpm() {
+  if (process.env.LITEAGENTS_SKIP_NPM_LOOKUP) return null;
+  try {
+    const r = require('child_process').spawnSync(
+      'npm', ['ls', '-g', PKG, '--depth=0', '--json'],
+      { encoding: 'utf8', timeout: NPM_LOOKUP_MS }
+    );
+    if (!r.stdout) return null;
+    const deps = JSON.parse(r.stdout).dependencies || {};
+    return deps[PKG] && deps[PKG].version ? String(deps[PKG].version) : null;
+  } catch (e) { return null; }
+}
+
+function installedVersion() {
+  const env = (process.env.LITEAGENTS_INSTALLED_VERSION || '').trim();
+  if (env) return env;
+  return versionFromManifest() || versionFromPackageJson() || versionFromNpm();
+}
+
+// --- cache ---------------------------------------------------------------
+
+// Home-scoped, not per-repo: it describes the global install, so a per-repo
+// cache would make every repo fetch the same answer.
+function cachePath() {
+  return path.join(os.homedir(), CONFIG_DIR, `.${PKG}-version.json`);
+}
+
+function readCache() {
+  try {
+    const c = JSON.parse(fs.readFileSync(cachePath(), 'utf8'));
+    if (typeof c.checked_at !== 'number' || typeof c.latest !== 'string') return null;
+    if (Date.now() - c.checked_at > TTL_MS) return null;
+    return c.latest;
+  } catch (e) { return null; }
+}
+
+// Best effort. An unwritable cache dir means we re-fetch next run, never that
+// we withhold the advice we already have.
+function writeCache(latest) {
+  try {
+    fs.mkdirSync(path.dirname(cachePath()), { recursive: true });
+    fs.writeFileSync(cachePath(), JSON.stringify({ checked_at: Date.now(), latest }));
+  } catch (e) { /* not worth a word */ }
+}
+
+// --- registry ------------------------------------------------------------
+
+function fetchLatest(cb) {
+  let base = process.env.npm_config_registry || 'https://registry.npmjs.org/';
+  if (!/\/$/.test(base)) base += '/';
+  const url = `${base}${PKG}/latest`;
+
+  let mod;
+  try { mod = url.startsWith('http://') ? require('http') : require('https'); }
+  catch (e) { return cb(null); }
+
+  let settled = false;
+  let req = null;
+  const finish = (v) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(deadline);
+    if (v === null && req) { try { req.destroy(); } catch (e) { /* */ } }
+    cb(v);
+  };
+
+  // The hard bound. req.setTimeout below does not cover connect time.
+  const deadline = setTimeout(() => finish(null), DEADLINE_MS);
+
+  try {
+    req = mod.get(url, { headers: { accept: 'application/json' } }, (res) => {
+      if (res.statusCode !== 200) { res.resume(); return finish(null); }
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (c) => {
+        body += c;
+        if (body.length > 1e6) finish(null); // a packument this big is not ours
+      });
+      res.on('end', () => {
+        try {
+          const v = JSON.parse(body).version;
+          finish(typeof v === 'string' && v ? v : null);
+        } catch (e) { finish(null); }
+      });
+      res.on('error', () => finish(null));
+    });
+    req.setTimeout(DEADLINE_MS, () => finish(null));
+    req.on('error', () => finish(null));
+  } catch (e) { finish(null); }
+}
+
+// --- main ----------------------------------------------------------------
+
+function advise(installed, latest) {
+  if (!installed || !latest) return;            // never guess
+  if (!isNewer(installed, latest)) return;      // current, or ahead of the registry
+  process.stdout.write(
+    `liteagents ${installed} -> ${latest} available: `
+    + `npm i -g ${PKG}@latest && ${PKG}\n`
+  );
+}
+
+function main() {
+  const installed = installedVersion();
+
+  const cached = readCache();
+  if (cached) return advise(installed, cached);
+
+  fetchLatest((latest) => {
+    if (!latest) return;                        // offline, slow, or broken: silent
+    writeCache(latest);
+    advise(installed, latest);
+  });
+}
+
+if (require.main === module) {
+  // Every failure is silent by contract. This command is a passenger; it does
+  // not get to fail the run it is riding in.
+  try { main(); } catch (e) { /* silent */ }
+} 
+
+module.exports = { isNewer };

package/packages/ampcode/skills/root-cause/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: root-cause
+description: Use when any test fails, bug appears, or behaviour surprises you, before proposing a fix - find the cause and prove it, by reading real evidence, tracing bad values back to their origin, comparing against a working case, and testing one hypothesis at a time
+allowed-tools: Read, Grep, Glob
+---
+
+# Root Cause
+
+**Find the cause before you change any code.**
+
+## The Law
+
+```
+NO FIX WITHOUT A CAUSE YOU CAN POINT AT
+```
+
+A fix at the place the error *appeared* is a symptom fix. It is a failure even when
+the symptom goes away, because the real cause is still there and will surface
+somewhere else, later, with less context.
+
+You cannot propose a fix until Phase 1 is done.
+
+## When to Use
+
+Any technical issue: a failing test, a production bug, unexpected behaviour, a
+performance problem, a broken build, an integration that will not talk.
+
+**Especially when it feels like overkill:**
+- Under time pressure — emergencies are exactly when guessing is most tempting and most expensive
+- "Just one quick fix" looks obvious
+- You have already tried a fix and it did not work
+- You do not fully understand the issue
+
+Simple bugs have root causes too, and finding one takes minutes. Guess-and-check
+takes hours and leaves damage behind.
+
+---
+
+## Phase 1 — Gather Evidence
+
+Do all of this **before** forming any opinion about the fix.
+
+### 1. Read the error completely
+
+Do not skim past it. Read the whole message, the whole stack trace, every warning
+above it. Note line numbers, file paths, error codes. The answer is often written
+there in full.
+
+### 2. Reproduce it consistently
+
+Can you trigger it on demand? What are the exact steps? Does it happen every time?
+
+If it is not reproducible, gather more data. Do not start guessing — an
+intermittent bug you cannot trigger is a bug you cannot prove you fixed.
+
+### 3. Check what changed
+
+Recent commits, the working diff, new dependencies, config edits, environment
+differences between the place it works and the place it does not.
+
+Be careful here: the most recent change is the most *available* suspect, not the
+most likely one. Recency is a lead to test, never a conclusion.
+
+### 4. Instrument the boundaries (multi-component systems)
+
+When the path crosses components — CI → build → sign, API → service → database,
+workflow → script → tool — do not reason about where it breaks. Measure it.
+
+For each boundary, log what goes **in** and what comes **out**, and confirm
+configuration and environment actually propagated across it.
+
+```bash
+echo "=== layer 1: is the secret present in the workflow? ==="
+echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+echo "=== layer 2: did it survive into the build script? ==="
+env | grep IDENTITY || echo "IDENTITY not in environment"
+
+echo "=== layer 3: what does the tool actually see? ==="
+security find-identity -v
+```
+
+Run it **once** to find which boundary fails, then investigate only that
+component. This turns "somewhere in the pipeline" into a named layer.
+
+### 5. Trace the bad value back to where it was born
+
+When the error surfaces deep in the call stack, the place it exploded is almost
+never the place it went wrong. Walk backwards.
+
+**The chain:**
+
+1. **Observe the symptom** — `git init` ran in the source directory
+2. **Find the immediate cause** — the code that directly did it:
+   `execFileAsync('git', ['init'], { cwd: projectDir })`
+3. **Ask what called this, and with what value** — `projectDir` was `''`, and an
+   empty `cwd` silently resolves to the process's own directory
+4. **Keep going up** — who passed the empty string? and who gave it to *them*?
+5. **Stop at the origin** — the point where a correct value first became wrong
+
+Fix it **there**. Then, if the value is dangerous, validate it at each layer on
+the way down as well, so the same mistake cannot recur through a different path.
+
+**When you cannot trace it by reading, instrument it:**
+
+```typescript
+async function gitInit(directory: string) {
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    stack: new Error().stack,
+  });
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+- Capture the **stack**, not just the value — it names the caller you are looking for
+- Log **before** the dangerous operation, not in its failure handler
+- Include surrounding context: the directory, the working directory, relevant environment
+- In tests, write to standard error directly; a project logger may be suppressed
+
+**When something pollutes a test run but you cannot tell which test:** bisect.
+Run the tests one at a time and stop at the first one that leaves the mess behind.
+`find-polluter.sh` in this skill's directory does exactly that.
+
+---
+
+## Phase 2 — Compare Against Something That Works
+
+You are looking for a difference, and the fastest way to see one is a side-by-side.
+
+- **Find a working example** — similar code in the same codebase that behaves correctly
+- **Read the reference completely** if you are following a pattern. Every line. Skimming a
+  reference and adapting "the idea" is how half-understood patterns ship
+- **List every difference**, however small. Do not filter by "that can't matter" — that
+  judgement is exactly what you do not have yet
+- **Check the dependencies**: what config, what environment, what other components does
+  the working one have that the broken one does not?
+
+---
+
+## Phase 3 — One Hypothesis, One Variable
+
+- **State it in writing:** "I think X is the cause, because Y." Specific, not vague.
+- **Test it with the smallest possible change.** One variable. A controlled test that
+  isolates your suspect beats a plausible story about the most recent commit.
+- **Read the result honestly.** Confirmed → Phase 4. Not confirmed → form a *new*
+  hypothesis. Never stack a second fix on top of an unconfirmed first one.
+- **Say when you do not know.** "I don't understand why X happens" is a real state and a
+  useful thing to report. Pretending to know produces confident wrong fixes.
+
+---
+
+## Phase 4 — Fix at the Source
+
+### 1. Write the failing test first
+
+The simplest reproduction you can manage — an automated test if there is a suite, a
+throwaway script if there is not.
+
+**Run it against the unfixed code and watch it fail, for the reason you expect.** A
+test written after the fix, or one that passes both before and after, proves nothing.
+This is the step that converts your hypothesis into evidence.
+
+### 2. Make one change
+
+Fix the cause you identified. One change. No "while I'm here" improvements, no bundled
+refactoring — those make it impossible to tell what actually worked.
+
+### 3. Verify
+
+Does the new test pass? Does the rest of the suite still pass? Is the original symptom
+actually gone — checked, not assumed?
+
+### 4. If the fix did not work, stop and count
+
+Under three attempts: return to Phase 1 with what you just learned. The failed attempt
+is evidence.
+
+**Three or more failed fixes means you have the wrong model of the problem.** Do not
+attempt a fourth. The pattern to watch for: each fix uncovers a new problem somewhere
+else, or each one needs "just a bit of refactoring" to land.
+
+That is an architecture question, not a hypothesis question. Stop and raise it.
+
+---
+
+## Red Flags — Stop and Return to Phase 1
+
+- "Quick fix now, investigate later"
+- "Just try changing X and see"
+- Several changes at once, then run the tests
+- "Skip the test, I'll check it by hand"
+- "It's probably X" — probably is not a cause
+- "I don't fully understand this, but this might work"
+- Listing fixes before tracing where the bad value came from
+- "One more attempt" when two have already failed
+- Each fix revealing a new problem somewhere else
+
+## Quick Reference
+
+| Phase | You do | Done when |
+|---|---|---|
+| **1. Evidence** | Read the error, reproduce, check changes, instrument boundaries, trace the value back | You can say what happened and where it started |
+| **2. Compare** | Find a working case, read it fully, list every difference | You know what is different |
+| **3. Hypothesis** | State one cause, test one variable | Confirmed, or you have a new hypothesis |
+| **4. Fix** | Failing test first, one change, verify | The test that failed now passes, and nothing else broke |
+
+## When There Really Is No Root Cause
+
+It happens — a genuine race, an upstream bug, a hardware fault. But roughly nineteen
+times in twenty, "no root cause" means the investigation stopped early.
+
+Before you conclude it: can you reproduce it? Did you instrument every boundary? Did
+you trace the value to its origin, or only to the last function you recognised?
+
+## Related
+
+- **AGENT_RULES.md → Testing Standards** — what makes the Phase 4 test a real one
+- **`/test-generate`** — build out the suite once the cause is fixed

package/packages/{claude/commands/security.md → ampcode/skills/security/SKILL.md}

@@ -1,9 +1,9 @@
 ---
 name: security
 description: Security audit — recurring six, injection, auth, trust boundaries
-usage: /security
 argument-hint: [file, directory, or leave empty for full scan]
 allowed-tools: Read, Grep, Glob, Bash(git log:*), Bash(git grep:*), Bash(rg:*)
+disable-model-invocation: true
 ---
 Audit $ARGUMENTS for security vulnerabilities. **Reports, never edits** — it
 verifies every claim, then hands the findings to whoever asked.

package/packages/{claude/commands/ship.md → ampcode/skills/ship/SKILL.md}

@@ -1,8 +1,8 @@
 ---
 name: ship
 description: Mechanical pre-deploy gate — tests, build, tree state
-usage: /ship
 allowed-tools: Read, Grep, Glob, Bash(git:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(pytest:*), Bash(python:*), Bash(go:*), Bash(cargo:*), Bash(make:*)
+disable-model-invocation: true
 ---
 Mechanical pre-deploy / pre-merge gate. Every item here is answerable by
 **running a command** and reading its exit code — no code judgment. Code