@givolt/i3-composer-agent 3.2.1 → 4.0.1

package/scripts/run-evals-test.js

@@ -56,8 +56,7 @@ function makeSandbox() {
   fs.mkdirSync(path.join(root, 'evals', 'cases'), { recursive: true });
   fs.mkdirSync(path.join(root, 'evals', 'fixtures', 'project'), { recursive: true });
   fs.copyFileSync(RUNNER, path.join(root, 'scripts', 'run-evals.js'));
-  fs.mkdirSync(path.join(root, 'scripts', 'lib'), { recursive: true });
-  fs.copyFileSync(path.join(__dirname, 'lib', 'skill-lint.js'), path.join(root, 'scripts', 'lib', 'skill-lint.js'));
+  fs.cpSync(path.join(__dirname, 'lib'), path.join(root, 'scripts', 'lib'), { recursive: true });
   fs.writeFileSync(path.join(root, 'evals', 'fixtures', 'project', 'context.txt'), 'fixture\n');
   return root;
 }
@@ -69,19 +68,20 @@ function run(root, args = []) {
   });
 }
 
-function runBehavioralWithGrading(root, raw) {
+function runBehavioralWithGrading(root, raw, options = {}) {
   writeSkill(root, 'alpha-skill', 'Handles alpha widgets.');
   const evalCase = completeCase('alpha-skill', 'change alpha widget');
-  evalCase.evals = [{ ...behavioralEval([]), kind: 'dialogue' }];
+  evalCase.evals = (options.ids || [1]).map((id) => ({ ...behavioralEval([]), id, kind: 'dialogue' }));
   writeJson(path.join(root, 'evals', 'cases', 'alpha-skill.json'), evalCase);
   const stub = path.join(root, 'stub-claude.cjs');
   fs.writeFileSync(stub, `
     const assert = require('node:assert/strict');
     require('child_process').execFileSync = (command, args) => {
       assert.equal(command, 'claude');
-      return args.includes('--output-format')
-        ? '{"type":"result","result":"done"}\\n'
-        : ${JSON.stringify(raw)};
+      const executor = args.includes('--output-format');
+      require('node:fs').appendFileSync(${JSON.stringify(path.join(root, 'claude-calls.txt'))}, executor ? 'executor\\n' : 'grader\\n');
+      if (executor && ${JSON.stringify(Boolean(options.error))}) throw Object.assign(new Error('executor failed'), ${JSON.stringify(options.error || {})});
+      return executor ? ${JSON.stringify(options.trace ?? '{"type":"result","subtype":"success","is_error":false,"result":"done"}\n')} : ${JSON.stringify(raw)};
     };
   `);
   return spawnSync(process.execPath, [
@@ -90,6 +90,80 @@ function runBehavioralWithGrading(root, raw) {
   ], { cwd: root, encoding: 'utf8' });
 }
 
+const passingGrading = JSON.stringify({
+  expectations: [{ id: 1, text: 'check', passed: true, evidence: 'observed' }],
+  summary: { passed: 1, failed: 0, total: 1, pass_rate: 1 },
+});
+const terminal = { type: 'result', subtype: 'success', is_error: false };
+const call = { type: 'assistant', message: { content: [{ type: 'tool_use', name: 'Bash', id: 'test', input: {} }] } };
+const returned = (id, is_error = false) => ({ type: 'user', message: { content: [{ type: 'tool_result', tool_use_id: id, is_error }] } });
+const traceOf = (...events) => events.map((event) => JSON.stringify(event)).join('\n') + '\n';
+
+for (const [name, trace] of Object.entries({
+  'terminal error': traceOf({ type: 'result', subtype: 'error_max_turns', is_error: true }),
+  'missing terminal': traceOf(call),
+  'implicit success': traceOf({ type: 'result', subtype: 'success' }),
+  'stale terminal': traceOf(terminal, call),
+  'permission denial': traceOf({ ...terminal, permission_denials: [{ tool_name: 'Read' }] }),
+  'pending tool': traceOf(call, terminal),
+  'unmatched return': traceOf(returned('unknown'), terminal),
+  'malformed event': 'null\n',
+  'invalid JSON': 'not JSON\n',
+  'null assistant message': traceOf({ type: 'assistant', message: null }, terminal),
+  'array assistant message': traceOf({ type: 'assistant', message: [] }, terminal),
+  'null assistant content': traceOf({ type: 'assistant', message: { content: null } }, terminal),
+  'object assistant content': traceOf({ type: 'assistant', message: { content: { type: 'tool_use', id: 'hidden' } } }, terminal),
+  'null user message': traceOf({ type: 'user', message: null }, terminal),
+  'null content block': traceOf({ type: 'assistant', message: { content: [null] } }, terminal),
+})) {
+  test(`does not grade an incomplete execution: ${name}`, () => {
+    const root = makeSandbox();
+    try {
+      const result = runBehavioralWithGrading(root, passingGrading, { trace });
+      assert.equal(result.status, 1, result.stdout + result.stderr);
+      assert.match(result.stdout, /execution incomplete/);
+      const base = path.join(root, 'evals/results/alpha-skill.eval-1');
+      assert.equal(fs.existsSync(`${base}.grading.json`), false);
+      assert.equal(fs.readFileSync(`${base}.execution.raw.txt`, 'utf8'), trace);
+      assert.equal(fs.readFileSync(path.join(root, 'claude-calls.txt'), 'utf8'), 'executor\n');
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+}
+
+test('a returned failed probe can recover before successful completion', () => {
+  const root = makeSandbox();
+  try {
+    const next = { ...call, message: { content: [{ ...call.message.content[0], id: 'green' }] } };
+    const trace = traceOf(call, returned('test', true),
+      { type: 'user', message: { content: 'Continue the repair.' } }, next, returned('green'), terminal,
+      { type: 'system', subtype: 'status', status: 'idle' });
+    const result = runBehavioralWithGrading(root, passingGrading, { trace });
+    assert.equal(result.status, 0, result.stdout + result.stderr);
+    assert.equal(fs.existsSync(path.join(root, 'evals/results/alpha-skill.eval-1.grading.json')), true);
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+});
+
+for (const code of ['ETIMEDOUT', 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER']) {
+  test(`retains partial execution evidence and continues after ${code}`, () => {
+    const root = makeSandbox();
+    try {
+      const trace = traceOf(call);
+      const result = runBehavioralWithGrading(root, passingGrading,
+        { error: { code, stdout: trace, stderr: 'captured diagnostic' }, ids: [1, 2] });
+      assert.equal(result.status, 1, result.stdout + result.stderr);
+      assert.match(result.stdout, /eval 2: executing/);
+      for (const id of [1, 2]) {
+        const base = path.join(root, `evals/results/alpha-skill.eval-${id}`);
+        assert.equal(fs.existsSync(`${base}.grading.json`), false);
+        assert.equal(fs.readFileSync(`${base}.execution.raw.txt`, 'utf8'), trace);
+        assert.match(fs.readFileSync(`${base}.execution.error.txt`, 'utf8'), new RegExp(code));
+        assert.match(fs.readFileSync(`${base}.execution.error.txt`, 'utf8'), /captured diagnostic/);
+      }
+      assert.equal(fs.readFileSync(path.join(root, 'claude-calls.txt'), 'utf8'), 'executor\nexecutor\n');
+    } finally { fs.rmSync(root, { recursive: true, force: true }); }
+  });
+}
+
 for (const passed of [true, false]) {
   for (const evidence of ['', ' \t\r\n', '\u00a0\u2003']) {
     test(`behavioral CLI diagnoses blank evidence for ${passed ? 'passing' : 'failing'} verdict ${JSON.stringify(evidence)}`, () => {
@@ -424,6 +498,78 @@ test('rejects an invalid rank-1 floor', () => {
   assert.match(result.stderr, /--min-rank1 must be a number from 0 to 100/);
 });
 
+test('routes clipped prompt forms to their long-form skill (see #660)', () => {
+  const root = makeSandbox();
+  // Note: the skill name must not contain the clipped form itself — name
+  // tokens are weighted 2x, which would route the prompt even without the
+  // alias map. The prompt shares no vocabulary with the description except
+  // the clipped/long pair (auth/authentication): without the alias map the
+  // skill scores zero and the positive prompt fails.
+  writeSkill(
+    root,
+    'credential-skill',
+    'Protects credential verification. Use when configuring authentication ceremonies.',
+  );
+  writeSkill(root, 'paint-skill', 'Paints sheds. Use when choosing exterior paint colors.');
+  writeJson(
+    path.join(root, 'evals', 'cases', 'credential-skill.json'),
+    completeCase('credential-skill', 'fix broken auth checks', 1),
+  );
+  writeJson(
+    path.join(root, 'evals', 'cases', 'paint-skill.json'),
+    completeCase('paint-skill', 'choose exterior paint colors', 1),
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+});
+
+test('folds -ifications to their -ify verb, not to the unrelated "specific" (see #660)', () => {
+  const root = makeSandbox();
+  // "specification" is a nominalization of "specify", so it must reach the
+  // spec skill. Stripping a bare "-ation" instead yields "specific", which
+  // silently cross-merges the two words and starves the spec skill. Each
+  // prompt shares vocabulary with its own skill only.
+  writeSkill(root, 'spec-skill', 'Agree on requirements up front. Use when you specify behaviour.');
+  writeSkill(root, 'specific-skill', 'Narrow a choice down. Use when one target matters.');
+  writeJson(
+    path.join(root, 'evals', 'cases', 'spec-skill.json'),
+    completeCase('spec-skill', 'document a specification for the billing rollout', 1),
+  );
+  writeJson(
+    path.join(root, 'evals', 'cases', 'specific-skill.json'),
+    completeCase('specific-skill', 'narrow the choice down to one target', 1),
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+});
+
+test('strips -ations as well as -ation so plurals do not out-stem singulars (see #660)', () => {
+  const root = makeSandbox();
+  // "migration" and "migrations" are the same word, so both forms have to
+  // reach the migration skill. With only "-ation" in the suffix list the
+  // plural keeps its "-s" ("migration" -> "migr" vs "migrations" ->
+  // "migration"), which splits the pair and halves the score. Neither
+  // prompt shares vocabulary with the other skill.
+  writeSkill(root, 'migration-skill', 'Move old data stores off production without downtime.');
+  writeSkill(root, 'recipe-skill', 'Plan tonight dinner from what is already in the cupboard.');
+  writeJson(
+    path.join(root, 'evals', 'cases', 'migration-skill.json'),
+    completeCase('migration-skill', 'plan the database migrations', 1),
+  );
+  writeJson(
+    path.join(root, 'evals', 'cases', 'recipe-skill.json'),
+    completeCase('recipe-skill', 'plan tonight dinner from the cupboard', 1),
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+});
+
 // ---------- parseGrading expectation-binding tests ----------
 
 test('accepts reordered-but-complete grader results', () => {
@@ -616,6 +762,8 @@ test('a grader that throws leaves no result file behind', () => {
     // Stale files from a prior run
     fs.writeFileSync(`${base}.grading.json`, '{"previous":"run"}\n');
     fs.writeFileSync(`${base}.grading.raw.txt`, 'previous raw output');
+    fs.writeFileSync(`${base}.execution.raw.txt`, 'previous partial trace');
+    fs.writeFileSync(`${base}.execution.error.txt`, 'previous execution failure');
 
     clearGradingSlot(base);
 
@@ -623,6 +771,8 @@ test('a grader that throws leaves no result file behind', () => {
 
     assert.equal(fs.existsSync(`${base}.grading.json`), false, 'stale grading.json must not survive a crash');
     assert.equal(fs.existsSync(`${base}.grading.raw.txt`), false, 'stale grading.raw.txt must not survive a crash');
+    assert.equal(fs.existsSync(`${base}.execution.raw.txt`), false, 'old partial trace must not survive a new attempt');
+    assert.equal(fs.existsSync(`${base}.execution.error.txt`), false, 'old execution failure must not survive a new attempt');
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }

package/scripts/run-evals.js

@@ -32,6 +32,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { parseFrontmatter } = require('./lib/skill-lint');
+const { executionFailure } = require('./lib/execution-status');
 const { execFileSync } = require('child_process');
 
 const ROOT = path.join(__dirname, '..');
@@ -70,7 +71,16 @@ const STOP = new Set([
 function stem(t) {
   // Light suffix stripping so "conflicts"/"conflict", "branching"/"branch",
   // "architectural"/"architecture" cluster together. Not a real stemmer.
-  for (const suf of ['ally', 'ing', 'ed', 'es', 'al']) {
+  // "ations"/"ation" fold Latinate nominalizations ("documentation"/"document",
+  // "configuration"/"configure") the same way. Both forms are listed so a
+  // plural doesn't survive the rule as a longer stem than its singular
+  // ("migration" -> "migr" but "migrations" -> "migration").
+  // "-ification" nouns are built on "-ify" verbs, so they fold to the verb's
+  // "-ifi" stem ("specification"/"specify", "verification"/"verify") rather
+  // than losing "-ication" and colliding with an unrelated word
+  // ("specification"/"specific"). Checked first so it wins over "-ation".
+  if (t.length > 10 && /ifications?$/.test(t)) t = t.replace(/ications?$/, 'i');
+  for (const suf of ['ally', 'ing', 'ations', 'ation', 'ed', 'es', 'al']) {
     if (t.length > suf.length + 3 && t.endsWith(suf)) {
       t = t.slice(0, -suf.length);
       break;
@@ -87,11 +97,32 @@ function stem(t) {
   return t;
 }
 
+// Clipped forms users type that never share a stem with the long form used
+// in descriptions ("docs" vs "documentation", "auth" vs "authentication").
+// Applied before stemming; each value is the canonical long form, so both
+// registers stem identically. Explicit and easy to extend (see #660) —
+// prefer adding an entry here over padding descriptions with clipped forms,
+// which would only teach skills to game the lexical proxy.
+const TOKEN_ALIASES = new Map(
+  Object.entries({
+    doc: 'document',
+    docs: 'document',
+    config: 'configuration',
+    configs: 'configuration',
+    auth: 'authenticate',
+    authentication: 'authenticate',
+    repo: 'repository',
+    repos: 'repository',
+    dep: 'dependency',
+    deps: 'dependency',
+  }),
+);
+
 const chineseSegmenter = new Intl.Segmenter('zh-CN', { granularity: 'word' });
 const chineseStop = new Set(['请问', '帮我', '一下', '这个', '那个', '使用', '适用于', '用于', '需要', '进行', '以及', '如何', '是否', '我们', '当前']);
 function tokenize(text) {
   const english = text.toLowerCase().replace(/[^a-z0-9\s-]/g, ' ').split(/[\s-]+/)
-    .filter(t => t.length > 2 && !STOP.has(t)).map(stem);
+    .filter(t => t.length > 2 && !STOP.has(t)).map(t => stem(TOKEN_ALIASES.get(t) || t));
   const chinese = [...chineseSegmenter.segment(text)].filter(part => part.isWordLike
     && /[\u3400-\u9fff]/.test(part.segment) && part.segment.length > 1 && !chineseStop.has(part.segment))
     .map(part => part.segment);
@@ -537,8 +568,9 @@ function extractExecutorModel(trace) {
 }
 
 function clearGradingSlot(base) {
-  fs.rmSync(`${base}.grading.json`, { force: true });
-  fs.rmSync(`${base}.grading.raw.txt`, { force: true });
+  for (const suffix of ['grading.json', 'grading.raw.txt', 'execution.raw.txt', 'execution.error.txt']) {
+    fs.rmSync(`${base}.${suffix}`, { force: true });
+  }
 }
 
 function persistGradingOutcome(base, grading, raw, runMeta) {
@@ -614,14 +646,29 @@ function runBehavioral(skillName, dryRun) {
     // headless denials would force the exact narrate-instead-of-perform
     // failure mode that trace grading exists to catch.
     try {
-    const trace = execFileSync(
-      'claude',
-      ['-p', ...(process.env.I3_EVAL_MODEL ? ['--model', process.env.I3_EVAL_MODEL] : []), '--verbose', '--output-format', 'stream-json',
-        '--permission-mode', 'acceptEdits',
-        '--allowedTools', EXECUTOR_TOOLS,
-        '--append-system-prompt', `Follow this skill exactly:\n\n${fs.readFileSync(skillFile, 'utf8')}`],
-      { input: ev.prompt, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, cwd: workspace, timeout: EXECUTOR_TIMEOUT_MS },
-    );
+    let trace;
+    let executorError;
+    try {
+      trace = execFileSync(
+        'claude',
+        ['-p', ...(process.env.I3_EVAL_MODEL ? ['--model', process.env.I3_EVAL_MODEL] : []), '--verbose', '--output-format', 'stream-json',
+          '--permission-mode', 'acceptEdits',
+          '--allowedTools', EXECUTOR_TOOLS,
+          '--append-system-prompt', `Follow this skill exactly:\n\n${fs.readFileSync(skillFile, 'utf8')}`],
+        { input: ev.prompt, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, cwd: workspace, timeout: EXECUTOR_TIMEOUT_MS },
+      );
+    } catch (error) {
+      trace = String(error.stdout || '');
+      executorError = error;
+    }
+    const failure = executorError ? `${executorError.code || 'process failed'}: ${executorError.message}` : executionFailure(trace);
+    if (failure) {
+      fs.writeFileSync(`${base}.execution.raw.txt`, trace);
+      fs.writeFileSync(`${base}.execution.error.txt`, `${failure}\n${executorError?.stderr || ''}`);
+      console.log(`  ✗  eval ${ev.id}: execution incomplete: ${failure}; raw execution retained`);
+      failures++;
+      continue;
+    }
     const gradingInstructions = kind === 'dialogue'
       ? [
         'You are grading an agent dialogue transcript against explicit expectations.',

package/scripts/ui-demo-test.js

@@ -49,7 +49,7 @@ test('i3-ui-demo template resolution works without another prototype skill and n
   assert.equal(detection.design.availability, 'missing');
   assert.equal(detection.official.availability, 'missing');
   const ownGeneration = path.join(own, 'assets/templates/enterprise-admin/generation.json');
-  const foreign = path.join(temporary, 'skills', path.basename(resources.root).startsWith('i3-') ? 'i3-ui-prototype' : 'i3-ui-prototype', 'assets/templates/enterprise-admin');
+  const foreign = path.join(temporary, 'skills', path.basename(resources.root).startsWith('i3-') ? 'i3-ui-prototype' : 'ui-prototype', 'assets/templates/enterprise-admin');
   fs.cpSync(path.dirname(ownGeneration), foreign, { recursive: true });
   fs.unlinkSync(ownGeneration);
   assert.throws(() => isolated.resolveResources(), /missing/i);
@@ -121,7 +121,7 @@ test('i3-ui-demo reads selected page structure, behavior and styles without an i
   assert.ok(page.styleFiles.includes('reference/styles/tokens.css'));
   assert.ok(page.elements.length > 0);
   assert.ok(page.elements.some(element => element.events.length > 0));
-  assert.ok(!JSON.stringify(page).includes('i3-ui-prototype'));
+  assert.ok(!JSON.stringify(page).includes('ui-prototype'));
   assert.equal(isolated.readCapability('pagination').defaults.minimumTestPages, 3);
 });
 

package/scripts/validate-artifact-paths-test.js

@@ -104,6 +104,20 @@ test('ignores non-artifact markdown references (no false positives)', () => {
   assert.match(result.stdout, /1 files checked — 0 error\(s\) — PASSED/);
 });
 
+test('does not mistake the tail of an unrelated filename for an artifact path', () => {
+  const root = makeSandbox();
+  writeFile(
+    root,
+    'skills/i3-planning-and-task-breakdown/SKILL.md',
+    'Attach `test-plan.md` and `release_todo.md`. Save the plan to `tasks/plan.md`.\n',
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 files checked — 0 error\(s\) — PASSED/);
+});
+
 test('skips guarded files that do not exist', () => {
   const root = makeSandbox();
   writeFile(root, '.claude/commands/spec.md', 'Save the spec as `SPEC.md`.\n');

package/scripts/validate-artifact-paths.js

@@ -71,8 +71,10 @@ const GUARDED_FILES = [
 // Matches a path-like token ending in a spec/plan/todo artifact filename,
 // including an optional directory prefix with bracket placeholders like
 // docs/features/[feature-name]/spec.md. Case-insensitive so SPEC.md and a
-// drifted spec.md are both caught, then compared against the allowlist.
-const ARTIFACT_RE = /(?:[A-Za-z0-9._[\]-]+\/)*(?:spec|plan|todo)\.md/gi;
+// drifted spec.md are both caught, then compared against the allowlist. The
+// lookbehind keeps the match from starting mid-word, so `test-plan.md` or
+// `release_todo.md` are not mistaken for a drifted `plan.md` / `todo.md`.
+const ARTIFACT_RE = /(?<![A-Za-z0-9._[\]-])(?:[A-Za-z0-9._[\]-]+\/)*(?:spec|plan|todo)\.md/gi;
 
 GUARDED_FILES.push(...GUARDED_FILES.filter(relative => /(?:^|\/)commands\//.test(relative)).map(relative => relative.replace(/(commands\/)([^/]+)(\.md|\.toml)$/, '$1i3-$2$3')));
 

package/skills/i3-api-and-interface-design/SKILL.md

@@ -208,7 +208,9 @@ The unique constraint *is* the mechanism. A store that cannot enforce uniqueness
 
 ```typescript
 if (existing.requestHash !== hash(req.body)) {
-  return res.status(422).json({ error: 'idempotency key reused with a different payload' });
+  return res.status(422).json({
+    error: { code: 'IDEMPOTENCY_KEY_REUSED', message: 'Idempotency key reused with a different payload' },
+  });
 }
 ```
 

package/skills/i3-ci-cd-and-automation/SKILL.md

@@ -196,7 +196,7 @@ Agent fixes → pushes → CI runs again
 **Key patterns:**
 
 ```
-Lint failure → Agent runs `npm run lint --fix` and commits
+Lint failure → Agent runs `npm run lint -- --fix` and commits
 Type error  → Agent reads the error location and fixes the type
 Test failure → Agent follows i3-debugging-and-error-recovery skill
 Build error → Agent checks config and dependencies
@@ -275,9 +275,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Rollback deployment
+        env:
+          VERSION: ${{ inputs.version }}
         run: |
-          # Deploy the specified previous version
-          npx vercel rollback ${{ inputs.version }}
+          # Deploy the specified previous version. Pass the input through env,
+          # never interpolate it into the script (shell injection).
+          npx vercel rollback "$VERSION"
 ```
 
 ## Environment Management
@@ -325,7 +328,7 @@ When the pipeline exceeds 10 minutes, apply these strategies in order of impact:
 ```
 Slow CI pipeline?
 ├── Cache dependencies
-│   └── Use actions/cache or setup-node cache option for node_modules
+│   └── Use the setup-node cache option (or actions/cache) for the package manager cache, not node_modules
 ├── Run jobs in parallel
 │   └── Split lint, typecheck, test, build into separate parallel jobs
 ├── Only run what changed

package/skills/i3-code-simplification/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: i3-code-simplification
-description: "在保持行为不变的前提下简化代码。适用于简化现有代码结构、重构复杂逻辑、保留全部现有行为，并提高可读性、维护性与可扩展性。"
-# i3-description-source: "description: Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity."
+description: "在保持行为不变的前提下简化代码。适用于简化现有代码结构、重构复杂逻辑、保留全部现有行为，并提高可读性、维护性与可扩展性；也适用于直接粘贴函数或模块，要求简化、清理或减少嵌套而无需其他改动的请求。"
+# i3-description-source: "description: Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity. Use when asked to simplify, clean up, or reduce the nesting of a function or module that already works, even when the code is pasted inline and nothing else needs to change."
 ---
 
 <!-- i3:zh-CN:start -->
@@ -12,7 +12,7 @@ description: "在保持行为不变的前提下简化代码。适用于简化现
 Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
 严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
 
-适用说明：在保持行为不变的前提下简化代码。适用于简化现有代码结构、重构复杂逻辑、保留全部现有行为，并提高可读性、维护性与可扩展性。
+适用说明：在保持行为不变的前提下简化代码。适用于简化现有代码结构、重构复杂逻辑、保留全部现有行为，并提高可读性、维护性与可扩展性；也适用于直接粘贴函数或模块，要求简化、清理或减少嵌套而无需其他改动的请求。
 <!-- i3:zh-CN:end -->
 
 # Code Simplification

package/skills/i3-constraint-driven-development/SKILL.md

@@ -125,7 +125,7 @@ Last reviewed: 2026-08-08 by @addy
 |-----------|------|-----------|---------|
 | Types | Zero type errors | `tsc --noEmit` | every edit |
 | Lint | Zero errors from our config | `biome check` | every edit |
-| Secrets | No secrets in source | `gitleaks detect --redact` | every edit |
+| Secrets | No secrets in source | `gitleaks dir . --redact` | every edit |
 | Coverage | Changed lines ≥ 80% covered | `vitest run --coverage` + git diff | task end, CI |
 | Security: code | No high findings | `semgrep scan --config p/default` | CI |
 | Security: deps | Nothing at high or above | `osv-scanner scan source -r .` | CI |
@@ -160,10 +160,10 @@ Picking a dimension means installing something. Don't leave the user with a numb
 | Types (TS) | tsc | already there | `tsc --noEmit` | any error |
 | Types (Python) | mypy | `pip install mypy` | `mypy .` | any error |
 | Lint | your existing config | already there | `eslint .` / `biome check` / `ruff check` | any error |
-| Coverage (JS) | your test runner | already there | `vitest run --coverage` (or `jest --coverage`) | coverage of changed lines |
+| Coverage (JS) | your test runner | Vitest: `npm i -D @vitest/coverage-v8`; Jest: already there | `vitest run --coverage` (or `jest --coverage`) | coverage of changed lines |
 | Coverage (Python) | pytest-cov | `pip install pytest-cov` | `pytest --cov --cov-report=lcov` | same |
 | Security: code | Semgrep | `pipx install semgrep` | `semgrep scan --config p/default --config p/owasp-top-ten` | any high finding |
-| Security: secrets | gitleaks | `brew install gitleaks` | `gitleaks detect --redact --no-banner` | any finding |
+| Security: secrets | gitleaks | `brew install gitleaks` | `gitleaks dir . --redact --no-banner` | any finding |
 | Security: dependencies | osv-scanner | `brew install osv-scanner` | `osv-scanner scan source -r .` | high or above |
 | Performance: page | Lighthouse | `npm i -D lighthouse` | `lighthouse $URL --output=json --quiet` | LCP, CLS, performance score |
 | Performance: bundle | size-limit | `npm i -D size-limit` | `size-limit --json` | per-entry byte budget |
@@ -184,7 +184,7 @@ Add each one to the project's own script so it's reproducible without an agent:
 ```json
 {
   "scripts": {
-    "check:fast": "tsc --noEmit && eslint . && gitleaks detect --redact --no-banner",
+    "check:fast": "tsc --noEmit && eslint . && gitleaks dir . --redact --no-banner",
     "check:task": "npm run check:fast && vitest run --coverage",
     "check:full": "npm run check:task && semgrep scan --config p/default && osv-scanner scan source -r ."
   }

package/skills/i3-constraint-driven-development/references/floor-guard.md

@@ -131,8 +131,8 @@ const ruleKey = (t) => {
 const isException = (t) => /^\| *(W|E)\d+ *\|/.test(t.trim());
 const MIN_BEFORE = /(>=|>|≥|at least|minimum|\bmin\b|no less than|not fall|not drop)\s*$/;
 const MAX_BEFORE = /(<=|<|≤|at most|maximum|\bmax\b|no more than|under|below|not grow|not exceed)\s*$/;
-const MIN_AFTER = /^\s*\S*\s*(or more|or higher|must not fall|must not drop)/;
-const MAX_AFTER = /^\s*\S*\s*(or less|or lower|must not grow|must not exceed)/;
+const MIN_AFTER = /^\s*\S*\s*(?:\|\s*)?(or more|or higher|must not fall|must not drop)/;
+const MAX_AFTER = /^\s*\S*\s*(?:\|\s*)?(or less|or lower|must not grow|must not exceed)/;
 const thresholds = (t) => {
   const out = [], re = /\d+(?:\.\d+)?/g;
   let m;

package/skills/i3-context-engineering/SKILL.md

@@ -62,7 +62,7 @@ Create a rules file that persists across sessions. This is the highest-leverage
 ## Commands
 - Build: `npm run build`
 - Test: `npm test`
-- Lint: `npm run lint --fix`
+- Lint: `npm run lint -- --fix`
 - Dev: `npm run dev`
 - Type check: `npx tsc --noEmit`
 

package/skills/i3-debugging-and-error-recovery/SKILL.md

@@ -93,7 +93,7 @@ npm test -- --grep "test name"
 npm test -- --verbose
 
 # Run in isolation (rules out test pollution)
-npm test -- --testPathPattern="specific-file" --runInBand
+npm test -- specific-file --runInBand
 ```
 
 ### Step 2: Localize

package/skills/i3-deprecation-and-migration/SKILL.md

@@ -157,6 +157,11 @@ class LegacyTaskService implements OldTaskAPI {
     const task = this.newService.findById(String(id));
     return this.toOldFormat(task);
   }
+
+  // Translate the new shape back into what old consumers expect
+  private toOldFormat(task: Task): OldTask {
+    return { id: Number(task.id), title: task.title, done: task.status === 'done' };
+  }
 }
 ```
 
@@ -169,7 +174,7 @@ function getTaskService(userId: string): TaskService {
   if (featureFlags.isEnabled('new-task-service', { userId })) {
     return new NewTaskService();
   }
-  return new LegacyTaskService();
+  return new OldTaskService();
 }
 ```
 

package/skills/i3-documentation-and-adrs/SKILL.md

@@ -123,8 +123,9 @@ Comment the *why*, not the *what*:
 counter += 1;
 
 // GOOD: Explains non-obvious intent
-// Rate limit uses a sliding window — reset counter at window boundary,
-// not on a fixed schedule, to prevent burst attacks at window edges
+// Rate limit uses a fixed window that opens on the first request after the
+// previous one expires, not on a clock schedule. Known gap: a client can spend
+// the full limit just before a reset and again just after (2x in a moment)
 if (now - windowStart > WINDOW_SIZE_MS) {
   counter = 0;
   windowStart = now;