@dtlabs/ai-toolkit 0.6.0 → 0.8.0

package/bin/cli.js

@@ -67,6 +67,92 @@ function askConfirm(question) {
   });
 }
 
+// ── allowlist ─────────────────────────────────────────────────────────────────
+
+// INFRA-T01: Canonical Bash permission lists (FTR-012, AC-11, AC-12).
+// These are fixed baselines — one combined list covering base read-only,
+// .NET, and npm commands. Unused entries in a project are harmless.
+const CANONICAL_ALLOW = [
+  'ls', 'dir', 'cat', 'head', 'tail', 'find', 'grep', 'rg', 'wc', 'echo',
+  'pwd', 'which', 'date',
+  'git status', 'git diff', 'git log', 'git show', 'git branch', 'git rev-parse',
+  'git add', 'git commit',
+  'dotnet build', 'dotnet test', 'dotnet restore',
+  'npm test', 'npm run build',
+];
+
+// Dangerous outward-facing commands that must always surface a human prompt.
+// git checkout stays on ask: it runs only in the implement-feature main loop
+// (Step 5), never inside pm-phase3 worker agents. If pm-phase3 ever gains
+// branch-management steps, this decision must be revisited.
+const CANONICAL_ASK = [
+  'git push', 'gh pr create', 'rm', 'del',
+  'git checkout', 'git reset', 'git clean',
+];
+
+// INFRA-T01: Format a raw command string into a Claude Code permission token.
+// Every command — including no-argument ones like 'pwd' — is formatted as
+// 'Bash(<cmd>:*)' for consistency across all entries.
+function commandToPermission(cmd) {
+  return `Bash(${cmd}:*)`;
+}
+
+// INFRA-T02: Ensure an object parsed from settings.local.json has the expected
+// shape. Mutates and returns the object so callers can chain immediately.
+function normalizeSettings(obj) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) obj = {};
+  if (!obj.permissions || typeof obj.permissions !== 'object') obj.permissions = {};
+  if (!obj.permissions.Bash || typeof obj.permissions.Bash !== 'object') obj.permissions.Bash = {};
+  if (!Array.isArray(obj.permissions.Bash.allow)) obj.permissions.Bash.allow = [];
+  if (!Array.isArray(obj.permissions.Bash.ask)) obj.permissions.Bash.ask = [];
+  return obj;
+}
+
+// INFRA-T03: Return the dedup union of two arrays (preserves insertion order,
+// all elements of a appear before novel elements of b).
+function mergeArrays(a, b) {
+  return [...new Set([...a, ...b])];
+}
+
+// INFRA-T03: Remove from allow every entry that also appears in ask.
+// This enforces the ask-beats-allow invariant: a command that could be
+// dangerous is never silently auto-approved just because it was also listed
+// in an allow array.
+function applyAskBeatsAllow(allow, ask) {
+  const askSet = new Set(ask);
+  return allow.filter(cmd => !askSet.has(cmd));
+}
+
+// INFRA-T04: Read {destDir}/.claude/settings.local.json.
+// Returns a descriptor so callers can distinguish missing vs. malformed.
+//   { exists: false, data: null,  malformed: false }  — file absent
+//   { exists: true,  data: <obj>, malformed: false }  — parsed OK
+//   { exists: true,  data: null,  malformed: true  }  — invalid JSON
+function readSettings(destDir) {
+  const settingsPath = path.join(destDir, '.claude', 'settings.local.json');
+  if (!fs.existsSync(settingsPath)) return { exists: false, data: null, malformed: false };
+  let raw;
+  try { raw = fs.readFileSync(settingsPath, 'utf8'); } catch (err) {
+    console.error(`Warning: could not read settings.local.json — ${err.message}`);
+    return { exists: true, data: null, malformed: true };
+  }
+  try {
+    const data = JSON.parse(raw);
+    return { exists: true, data, malformed: false };
+  } catch {
+    return { exists: true, data: null, malformed: true };
+  }
+}
+
+// INFRA-T04: Write {destDir}/.claude/settings.local.json, creating the
+// .claude/ directory if it does not exist. Throws on I/O failure so callers
+// can catch and report gracefully.
+function writeSettings(destDir, data) {
+  const settingsPath = path.join(destDir, '.claude', 'settings.local.json');
+  ensureDir(settingsPath);
+  fs.writeFileSync(settingsPath, JSON.stringify(data, null, 2), 'utf8');
+}
+
 // ── file enumeration ─────────────────────────────────────────────────────────
 
 function expandMappings(mappings) {
@@ -155,9 +241,71 @@ async function checkVersion(destRoot, force) {
   return true;
 }
 
+// ── manifest ──────────────────────────────────────────────────────────────────
+
+const MANIFEST_FILE = '.ai-toolkit-manifest.json';
+
+function readManifest(destRoot) {
+  const manifestPath = path.join(destRoot, '.claude', MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) return { files: [] };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    if (!parsed || !Array.isArray(parsed.files)) return { files: [] };
+    parsed.files = parsed.files.map(f => f.replace(/\\/g, '/'));
+    return parsed;
+  } catch {
+    console.log(dim('Previous manifest is corrupt; treating as empty'));
+    return { files: [] };
+  }
+}
+
+function computeOrphans(oldFiles, newFiles) {
+  const newSet = new Set(newFiles.map(f => f.replace(/\\/g, '/')));
+  return oldFiles
+    .map(f => f.replace(/\\/g, '/'))
+    .filter(f => !newSet.has(f));
+}
+
+function moveToTrash(destRoot, relativePath) {
+  const source = path.join(destRoot, relativePath);
+  if (!fs.existsSync(source)) return;
+  const trashPath = path.join(destRoot, '.claude', '.ai-toolkit-trash', relativePath);
+  ensureDir(trashPath);
+  try {
+    fs.renameSync(source, trashPath);
+  } catch (err) {
+    if (err.code === 'EXDEV') {
+      fs.copyFileSync(source, trashPath);
+      fs.unlinkSync(source);
+    } else {
+      throw err;
+    }
+  }
+}
+
+function writeManifest(destRoot, fileList) {
+  const manifestPath = path.join(destRoot, '.claude', MANIFEST_FILE);
+  const trashDir = path.join(destRoot, '.claude', '.ai-toolkit-trash');
+  const filtered = fileList.filter(rel => {
+    const abs = path.join(destRoot, rel);
+    return !abs.startsWith(trashDir + path.sep) && abs !== trashDir;
+  });
+  const manifest = {
+    version: TOOLKIT_VERSION,
+    installedAt: new Date().toISOString(),
+    files: filtered.map(f => f.replace(/\\/g, '/')),
+  };
+  try {
+    ensureDir(manifestPath);
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+  } catch (err) {
+    console.log(dim(`Warning: could not write manifest — ${err.message}`));
+  }
+}
+
 // ── install ───────────────────────────────────────────────────────────────────
 
-async function runInstall(label, mappings, force) {
+async function runInstall(label, mappings, force, destRoot) {
   const files    = expandMappings(mappings);
   const entries  = categorize(files);
 
@@ -165,6 +313,58 @@ async function runInstall(label, mappings, force) {
   const modified = entries.filter(e => e.status === 'modified');
   const same     = entries.filter(e => e.status === 'same');
 
+  // ── prune phase (before file copy) ───────────────────────────────────────────
+  const oldManifest = readManifest(destRoot);
+  const newFileSet  = files.map(f => path.relative(destRoot, f.dest).replace(/\\/g, '/'));
+  const orphans     = computeOrphans(oldManifest.files, newFileSet);
+
+  const existingOrphans = orphans.filter(o => fs.existsSync(path.join(destRoot, o)));
+
+  if (existingOrphans.length > 0) {
+    console.log();
+    console.log(`${bold('📦 Orphan cleanup')}  ${clr('gray', '→')}  ${clr('red', `${existingOrphans.length} stale file(s) found`)}`);
+    console.log(divider());
+    for (const orphan of existingOrphans) {
+      console.log(`  ${clr('red', '∅')} ${clr('red', 'REMOVED ')}  ${orphan}`);
+    }
+    console.log(divider());
+  }
+
+  let removedCount = 0;
+  let keptCount    = 0;
+
+  if (force) {
+    for (const orphan of existingOrphans) {
+      moveToTrash(destRoot, orphan);
+      removedCount++;
+      console.log(`     ${clr('red', '∅')} ${dim(orphan)}`);
+    }
+  } else {
+    for (const orphan of existingOrphans) {
+      const fullPath = path.join(destRoot, orphan);
+      if (!fs.existsSync(fullPath)) continue;
+      const ok = await askConfirm(`  Move to trash  ${clr('red', orphan)}?`);
+      if (ok) {
+        moveToTrash(destRoot, orphan);
+        console.log(`     ${clr('green', '✔')} Moved to trash\n`);
+        removedCount++;
+      } else {
+        console.log(`     ${clr('gray', '✖')} Kept as-is\n`);
+        keptCount++;
+      }
+    }
+  }
+
+  if (existingOrphans.length > 0) {
+    console.log(divider());
+    console.log(
+      `  ${clr('red', `∅ Moved: ${removedCount}`)}` +
+      `  ${clr('gray', `↪ .claude/.ai-toolkit-trash/`)}` +
+      `  ${clr('gray', `✖ Kept: ${keptCount}`)}\n`
+    );
+  }
+
+  // ── install plan display ──────────────────────────────────────────────────────
   console.log();
   console.log(`${bold('📦 Install plan')}  ${clr('gray', '→')}  ${clr('cyan', label)}`);
   console.log(divider());
@@ -186,6 +386,7 @@ async function runInstall(label, mappings, force) {
 
   if (modified.length === 0) {
     console.log(`  ${clr('green', '✔')}  All new files copied. No conflicts.\n`);
+    writeManifest(destRoot, newFileSet);
     return;
   }
 
@@ -196,6 +397,7 @@ async function runInstall(label, mappings, force) {
       fs.copyFileSync(e.src, e.dest);
       console.log(`     ${clr('yellow', '↺')} ${dim(path.relative(process.cwd(), e.dest))}`);
     }
+    writeManifest(destRoot, newFileSet);
     return;
   }
 
@@ -223,6 +425,8 @@ async function runInstall(label, mappings, force) {
     `  ${clr('green', `✔ Overwritten: ${overwritten}`)}` +
     `  ${clr('gray',  `✖ Kept as-is: ${skipped}`)}\n`
   );
+
+  writeManifest(destRoot, newFileSet);
 }
 
 // ── subagent spawn-depth check (verify & advise only — never write) ────────────
@@ -271,6 +475,175 @@ function checkSpawnDepth(destRoot) {
   console.log(`     ${dim('Then restart Claude Code so the variable is loaded.')}\n`);
 }
 
+// ── mergeAllowlist ────────────────────────────────────────────────────────────
+
+// US-01-T01 / US-02-T01 / US-02-T02 / US-03-T01:
+// Core pure function — creates or merges the Bash permission allowlist in
+// {destDir}/.claude/settings.local.json using the canonical lists above.
+//
+// Return values:
+//   { status: 'written' }                     — fresh file created
+//   { status: 'merged', preserved: N }        — merged with N pre-existing rules
+//   { status: 'reset',  reason: 'malformed' } — invalid JSON was replaced
+//   { status: 'error',  message: '...' }      — I/O failure
+function mergeAllowlist(destDir) {
+  if (!destDir || typeof destDir !== 'string') {
+    return { status: 'error', message: 'destDir must be a non-empty string' };
+  }
+  if (!fs.existsSync(destDir) || !fs.statSync(destDir).isDirectory()) {
+    return { status: 'error', message: `destination does not exist or is not a directory: ${destDir}` };
+  }
+
+  const canonicalAllow = CANONICAL_ALLOW.map(commandToPermission);
+  const canonicalAsk   = CANONICAL_ASK.map(commandToPermission);
+
+  const { exists, data, malformed } = readSettings(destDir);
+
+  // Malformed JSON recovery (AC-05)
+  if (malformed) {
+    console.log('Warning: settings.local.json is not valid JSON; resetting to default');
+    const fresh = normalizeSettings({});
+    fresh.permissions.Bash.allow = canonicalAllow;
+    fresh.permissions.Bash.ask   = canonicalAsk;
+    try {
+      writeSettings(destDir, fresh);
+    } catch (err) {
+      return { status: 'error', message: err.message };
+    }
+    return { status: 'reset', reason: 'malformed' };
+  }
+
+  // Fresh install: no existing file (AC-01)
+  if (!exists) {
+    const fresh = normalizeSettings({});
+    fresh.permissions.Bash.allow = canonicalAllow;
+    fresh.permissions.Bash.ask   = canonicalAsk;
+    try {
+      writeSettings(destDir, fresh);
+    } catch (err) {
+      return { status: 'error', message: err.message };
+    }
+    return { status: 'written' };
+  }
+
+  // Merge path: existing file, valid JSON (AC-02, AC-03, AC-04)
+  const existing = normalizeSettings(data);
+  const existingAllow = existing.permissions.Bash.allow;
+  const existingAsk   = existing.permissions.Bash.ask;
+
+  const countBefore = existingAllow.length + existingAsk.length;
+
+  let mergedAllow = mergeArrays(existingAllow, canonicalAllow);
+  const mergedAsk = mergeArrays(existingAsk,   canonicalAsk);
+
+  // ask-beats-allow: strip from allow any cmd that is now in ask
+  mergedAllow = applyAskBeatsAllow(mergedAllow, mergedAsk);
+
+  existing.permissions.Bash.allow = mergedAllow;
+  existing.permissions.Bash.ask   = mergedAsk;
+
+  try {
+    writeSettings(destDir, existing);
+  } catch (err) {
+    return { status: 'error', message: err.message };
+  }
+
+  const preserved = countBefore;
+  return { status: 'merged', preserved };
+}
+
+// INFRA-T01 (FTR-013):
+// Append a new entry to {featureDir}/{prefix}-token-ledger.json atomically.
+// If the file does not exist it is created. If JSON is malformed the file is
+// overwritten with a single-element array containing the new entry.
+//
+// Algorithm:
+//   1. Read and parse the existing ledger (or start with [])
+//   2. Push the new entry
+//   3. Write the full array back in one synchronous write (atomic)
+function appendLedgerEntry(featureDir, prefix, entry) {
+  const filePath = path.join(featureDir, `${prefix}-token-ledger.json`);
+  let ledger = [];
+  if (fs.existsSync(filePath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      ledger = Array.isArray(parsed) ? parsed : [];
+    } catch (_) {
+      console.log(`Warning: could not parse token ledger at ${filePath} — starting fresh`);
+      ledger = [];
+    }
+  }
+  ledger.push(entry);
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(ledger, null, 2), 'utf8');
+}
+
+// INFRA-T02 (FTR-013):
+// Find and update an existing entry in {featureDir}/{prefix}-token-ledger.json
+// by agent key, atomically. Searches from the end of the array so that the most
+// recent entry for a given key is updated (handles any accidental duplicates).
+// If the file does not exist or the key is not found the call is a silent no-op.
+//
+// Algorithm:
+//   1. Read and parse the existing ledger (silent return on missing/malformed)
+//   2. Find the last entry where entry.agent === agentKey
+//   3. Object.assign the updates onto that entry
+//   4. Write the full array back in one synchronous write (atomic)
+function updateLedgerEntry(featureDir, prefix, agentKey, updates) {
+  const filePath = path.join(featureDir, `${prefix}-token-ledger.json`);
+  if (!fs.existsSync(filePath)) return;
+  let ledger;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    ledger = Array.isArray(parsed) ? parsed : [];
+  } catch (_) {
+    console.log(`Warning: could not parse token ledger at ${filePath} — skipping update for "${agentKey}"`);
+    return;
+  }
+  let idx = -1;
+  for (let i = ledger.length - 1; i >= 0; i--) {
+    if (ledger[i] && ledger[i].agent === agentKey) { idx = i; break; }
+  }
+  if (idx === -1) {
+    console.log(`Warning: ledger entry not found for agent key "${agentKey}"`);
+    return;
+  }
+  Object.assign(ledger[idx], updates);
+  fs.writeFileSync(filePath, JSON.stringify(ledger, null, 2), 'utf8');
+}
+
+// US-05-T01:
+// Idempotently append `.claude/settings.local.json` to {destDir}/.gitignore.
+// Creates .gitignore if it does not exist (AC-06, AC-07).
+//
+// Return values:
+//   { status: 'appended' }     — line was added
+//   { status: 'already' }      — line was already present
+//   { status: 'created' }      — .gitignore did not exist; created with line
+//   { status: 'error', message } — I/O failure
+function updateGitignore(destDir) {
+  const GITIGNORE_ENTRY = '.claude/settings.local.json';
+  const gitignorePath   = path.join(destDir, '.gitignore');
+
+  try {
+    if (!fs.existsSync(gitignorePath)) {
+      fs.writeFileSync(gitignorePath, `${GITIGNORE_ENTRY}\n`, 'utf8');
+      return { status: 'created' };
+    }
+
+    const content = fs.readFileSync(gitignorePath, 'utf8');
+    const lines   = content.split('\n').map(l => l.trim());
+    if (lines.includes(GITIGNORE_ENTRY)) return { status: 'already' };
+
+    const trailing = content.endsWith('\n') ? '' : '\n';
+    fs.writeFileSync(gitignorePath, `${content}${trailing}${GITIGNORE_ENTRY}\n`, 'utf8');
+    return { status: 'appended' };
+  } catch (err) {
+    return { status: 'error', message: err.message };
+  }
+}
+
 // ── entry points ──────────────────────────────────────────────────────────────
 
 async function installLocal(targetDir, force) {
@@ -283,7 +656,7 @@ async function installLocal(targetDir, force) {
     { src: path.join(packageRoot, 'docs'),      dest: path.join(targetDir, 'docs') },
     { src: path.join(packageRoot, 'CLAUDE.md'), dest: path.join(targetDir, 'CLAUDE.md') },
   ];
-  await runInstall(`local project`, mappings, force);
+  await runInstall(`local project`, mappings, force, targetDir);
   writeInstalledVersion(targetDir);
   console.log(`  ${clr('green', '✔')}  ${bold('Install complete.')}\n`);
   checkSpawnDepth(targetDir);
@@ -309,7 +682,7 @@ async function installGlobal(force) {
       { src: path.join(packageRoot, 'docs'),                 dest: path.join(target, 'docs') },
       { src: path.join(packageRoot, 'CLAUDE.global.md'),    dest: path.join(target, 'CLAUDE.md') },
     ];
-    await runInstall('global Claude folder', mappings, force);
+    await runInstall('global Claude folder', mappings, force, target);
     writeInstalledVersion(target);
     console.log(`  ${clr('green', '✔')}  ${bold('Global install complete.')}\n`);
     checkSpawnDepth(homedir);
@@ -349,6 +722,42 @@ async function main() {
     await installGlobal(force);
   } else if (argv[0] === 'help' || argv[0] === '--help') {
     help();
+  } else if (argv[0] === 'merge-allowlist') {
+    const destDir = argv[1];
+    if (!destDir) {
+      console.error('Error: merge-allowlist requires a destination directory');
+      process.exit(1);
+    }
+    try {
+      const result = mergeAllowlist(destDir);
+      if (result.status === 'error') {
+        console.error(`Error: ${result.message}`);
+        process.exit(1);
+      }
+      console.log(`Allowlist: ${result.status}${result.preserved !== undefined ? ` (${result.preserved} rules preserved)` : ''}`);
+      process.exit(0);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  } else if (argv[0] === 'update-gitignore') {
+    const destDir = argv[1];
+    if (!destDir) {
+      console.error('Error: update-gitignore requires a destination directory');
+      process.exit(1);
+    }
+    try {
+      const result = updateGitignore(destDir);
+      if (result.status === 'error') {
+        console.error(`Error: ${result.message}`);
+        process.exit(1);
+      }
+      console.log(`Gitignore: ${result.status}`);
+      process.exit(0);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
   } else if (fs.existsSync(argv[0]) && fs.statSync(argv[0]).isDirectory()) {
     await installLocal(argv[0], force);
   } else {
@@ -371,5 +780,21 @@ if (require.main === module) {
     categorize,
     readInstalledVersion,
     NEVER_COPY,
+    readManifest,
+    computeOrphans,
+    moveToTrash,
+    writeManifest,
+    CANONICAL_ALLOW,
+    CANONICAL_ASK,
+    commandToPermission,
+    normalizeSettings,
+    mergeArrays,
+    applyAskBeatsAllow,
+    readSettings,
+    writeSettings,
+    mergeAllowlist,
+    updateGitignore,
+    appendLedgerEntry,
+    updateLedgerEntry,
   };
 }

package/docs/token-pricing.json

@@ -0,0 +1,21 @@
+{
+  "_comment": "Anthropic API pricing (USD per 1M tokens). Update when prices change. EUR conversion uses the rate below.",
+  "_source": "https://www.anthropic.com/pricing — last updated 2026-07-31",
+  "_split": "No per-agent input/output breakdown available in the ledger. Assume 80% input / 20% output as a reasonable approximation.",
+  "usd_to_eur": 0.92,
+  "usd_to_eur_date": "2026-07-31",
+  "models": {
+    "haiku": {
+      "input_per_1m_usd": 0.80,
+      "output_per_1m_usd": 4.00
+    },
+    "sonnet": {
+      "input_per_1m_usd": 3.00,
+      "output_per_1m_usd": 15.00
+    },
+    "opus": {
+      "input_per_1m_usd": 15.00,
+      "output_per_1m_usd": 75.00
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",

package/docs/token-optimization-backlog.md

@@ -1,115 +0,0 @@
-# Token Optimization — Backlog di feature atomiche
-
-> Deriva da `docs/token-optimization.md`. Data: 2026-07-24.
-> Ogni voce è **atomica**: implementabile e verificabile in isolamento.
-> "Criticità" = priorità di ottimizzazione (impatto/rischio), NON severità di difetto.
-> Nessun intervento è un bug attivo → nessun `CRITICAL`.
-> Sequenza consigliata = ordine degli ID.
-
-## Quadro sintetico
-
-| ID | Intervento | Criticità | Sforzo | Rischio | File toccati | Dipende da |
-|----|-----------|-----------|--------|---------|--------------|-----------|
-| OPT-01 ✅ | `model:` esplicito su ogni agent (→ FTR-007, PR #20) | **HIGH** | Basso | Basso | 15 agent (frontmatter) | — |
-| OPT-02 | Deduplicare CLAUDE.md globale vs progetto | **HIGH** | Minimo | Zero | `~/.claude/CLAUDE.md` | — |
-| OPT-03 | Blocco "Compact instructions" in CLAUDE.md | MEDIUM | Minimo | Zero | `CLAUDE.md` (progetto) | — |
-| OPT-04 | Spostare i cataloghi da CLAUDE.md a reference.md | MEDIUM | Basso | Basso | `CLAUDE.md`, `docs/reference.md` | — |
-| OPT-05 | Procedure on-demand — assessment-manager | MEDIUM | Medio | Basso | `assessment-manager.md` | — |
-| OPT-06 | Procedure on-demand — project-manager | MEDIUM | Medio | Basso | `project-manager.md` | — |
-| OPT-07 | Resource-budget testuale negli assessment agent | MEDIUM | Basso | Basso | 3+ assessment agent | — |
-| OPT-08 | Summary/full split negli output di assessment | **HIGH** | Alto | Medio | assessment agents + int-doc + manager | OPT-07 |
-| OPT-09 | Estrarre calcolo deterministico da assessment-manager | **HIGH** | Alto | Medio | `assessment-manager.md` + nuovo script | — |
-| OPT-10 | generic-software-assessment → ruolo triage | MEDIUM | Medio | Medio | `generic-software-assessment.md` + manager | OPT-08 |
-| OPT-11 | Delegation policy negli orchestratori | LOW | Basso | Basso | 2 orchestratori | — |
-| OPT-12 | Hook di filtro output verboso (opzionale) | LOW | Basso | Basso | `settings.json` + script hook | — |
-
----
-
-## Feature atomiche
-
-### OPT-01 — `model:` esplicito su ogni agent
-- **Criticità:** HIGH · **Sforzo:** Basso · **Rischio:** Basso
-- **Obiettivo:** ogni agent dichiara il modello adatto al suo ruolo, così nessuno eredita Opus per default.
-- **Scope (solo frontmatter):** aggiungere `model:` ai 15 agent che ne sono privi. Mappatura:
-  - `sonnet`: `assessment-manager`, `project-manager`, `developer-backend`, `developer-frontend`, `developer-testing`, `god-class-decomposition`, `domain-model-refactoring`, `dependency-injection-refactoring`, `security-hardening`, `dependency-supply-chain-security`, `define-feature`, `init-agents-md`, `install-toolkit`, `intervention-documentation-standard`
-  - `opus`: `review-solution` (unico ruolo con giudizio architetturale profondo)
-- **Fuori scope:** i 7 agent già `haiku` restano invariati.
-- **Criteri di accettazione:** `grep -L "^model:" .claude/agents/*.md` non restituisce nulla; ogni valore ∈ {haiku, sonnet, opus}.
-- **Dipendenze:** nessuna.
-
-### OPT-02 — Deduplicare CLAUDE.md globale vs progetto
-- **Criticità:** HIGH · **Sforzo:** Minimo · **Rischio:** Zero
-- **Obiettivo:** eliminare il duplicato caricato a ogni sessione; il `CLAUDE.md` di progetto resta la fonte unica del catalogo toolkit.
-- **Scope:** ridurre `~/.claude/CLAUDE.md` alle sole preferenze cross-progetto (lingua, stile, convenzioni personali). Rimuovere il catalogo toolkit duplicato.
-- **Criteri di accettazione:** `diff ~/.claude/CLAUDE.md ./CLAUDE.md` NON è più identico; il globale non contiene più le tabelle Skills/Commands/Agents; il Gate Protocol resta accessibile (nel progetto).
-- **Dipendenze:** nessuna. ⚠️ File utente globale — confermare con l'utente prima di modificare.
-
-### OPT-03 — Blocco "Compact instructions" in CLAUDE.md
-- **Criticità:** MEDIUM · **Sforzo:** Minimo · **Rischio:** Zero
-- **Obiettivo:** guidare l'auto-compaction a preservare ciò che conta (decisioni, file, finding IDs) e scartare rumore.
-- **Scope:** aggiungere al `CLAUDE.md` di progetto una sezione `# Compact instructions` (preserva: obiettivo corrente, decisioni confermate, risposte utente, file modificati, errori aperti, finding/artifact IDs; scarta: risultati grep grezzi, output tool riusciti, spiegazioni ripetute, piani superati).
-- **Criteri di accettazione:** la sezione esiste in `CLAUDE.md`; nessun'altra modifica.
-- **Dipendenze:** nessuna. (Coordinare con OPT-04 se si tocca lo stesso file.)
-
-### OPT-04 — Spostare i cataloghi da CLAUDE.md a reference.md
-- **Criticità:** MEDIUM · **Sforzo:** Basso · **Rischio:** Basso
-- **Obiettivo:** CLAUDE.md sotto ~200 righe, solo essenziali operativi; il catalogo di scoperta vive in reference.md.
-- **Scope:** spostare le tabelle Skills / Commands / Agents / Procedures in `docs/reference.md`. In `CLAUDE.md` restano: Dependencies, How it works, override procedure, **Gate Protocol**. Aggiungere in CLAUDE.md un puntatore a reference.md.
-- **Criteri di accettazione:** `CLAUDE.md` < 200 righe; nessuna tabella-catalogo persa (presente in reference.md); Gate Protocol ancora in CLAUDE.md.
-- **Dipendenze:** nessuna.
-
-### OPT-05 — Procedure on-demand (assessment-manager)
-- **Criticità:** MEDIUM · **Sforzo:** Medio · **Rischio:** Basso
-- **Obiettivo:** leggere ogni procedura nella fase in cui serve, non tutte all'avvio.
-- **Scope:** in `assessment-manager.md`, spostare le istruzioni "read at startup" così che `token-estimation.md`/`pricing.md` si leggano in Phase 3-4, `assessment-findings-gate.md` in Phase 5, ecc.
-- **Criteri di accettazione:** nessuna procedura letta prima della fase che la usa; il comportamento delle fasi resta invariato.
-- **Dipendenze:** nessuna. (Se si fa OPT-09, `token-estimation.md` sparisce del tutto dal contesto LLM.)
-
-### OPT-06 — Procedure on-demand (project-manager)
-- **Criticità:** MEDIUM · **Sforzo:** Medio · **Rischio:** Basso
-- **Obiettivo:** stesso principio di OPT-05 applicato al `project-manager` (che legge ancora più procedure).
-- **Scope:** riorganizzare `project-manager.md` per caricare ogni procedura alla fase pertinente (PR-procedure alla fase PR, ecc.).
-- **Criteri di accettazione:** nessuna procedura caricata anticipatamente; pipeline invariata.
-- **Dipendenze:** nessuna.
-
-### OPT-07 — Resource-budget testuale negli assessment agent
-- **Criticità:** MEDIUM · **Sforzo:** Basso · **Rischio:** Basso
-- **Obiettivo:** limiti di lettura/output come **istruzioni nel prompt** (NON frontmatter — `budget:` non è supportato dall'harness).
-- **Scope:** aggiungere una sezione `## Resource budget` in prosa agli assessment agent (es. "Inspect at most ~25 files; ≤2 evidence snippets per finding; stop when evidence is sufficient — do not explore to increase coverage").
-- **Criteri di accettazione:** la sezione è testo del prompt, non YAML; presente in `generic-software-assessment`, `layered-architecture-assessment`, `concurrency-safety-assessment`.
-- **Dipendenze:** nessuna.
-
-### OPT-08 — Summary/full split negli output di assessment
-- **Criticità:** HIGH · **Sforzo:** Alto · **Rischio:** Medio
-- **Obiettivo:** l'orchestratore legge un **summary compatto**, non il documento intero. Il guadagno reale (non il formato JSON in sé).
-- **Scope:** ogni assessment agent produce `{PREFIX}-{area}.full.md` (dettagli) + `{PREFIX}-{area}.summary` (conteggi per severità, finding IDs, path del full). `assessment-manager` e `intervention-documentation-standard` consumano il summary; il full si apre solo per i finding accettati.
-- **Criteri di accettazione:** ogni agent scrive entrambi i file; il manager non legge i `.full` in Phase 3; l'int-doc apre i full solo per i finding selezionati.
-- **Dipendenze:** OPT-07 (budget di output coerente).
-
-### OPT-09 — Estrarre calcolo deterministico da assessment-manager
-- **Criticità:** HIGH · **Sforzo:** Alto · **Rischio:** Medio
-- **Obiettivo:** togliere dal prompt ~3.500 parole di pseudo-codice (calcolo token/effort, registry write) che un LLM esegue in modo costoso e fragile.
-- **Scope:** spostare Token-Estimate / Effort-Estimate / registry-write in uno script (`scripts/estimate.*`) invocato via Bash; il prompt dell'agent si riduce a "esegui lo script con questi input e verifica l'output".
-- **Criteri di accettazione:** i tre file prodotti sono identici (per input noti) a prima; `assessment-manager.md` perde le sezioni di calcolo passo-passo; nessun errore aritmetico possibile lato LLM.
-- **Dipendenze:** nessuna hard; sinergica con OPT-05.
-
-### OPT-10 — generic-software-assessment → ruolo triage
-- **Criticità:** MEDIUM · **Sforzo:** Medio · **Rischio:** Medio
-- **Obiettivo:** evitare che il generic duplichi il lavoro degli specialisti (layer, security, concurrency) sullo stesso codebase.
-- **Scope:** trasformare `generic-software-assessment` in triage: scansione superficiale che decide quali specialisti attivare e copre solo le aree non coperte (Opzione A della gap analysis).
-- **Criteri di accettazione:** il generic non riesamina aree già coperte da uno specialista attivo; l'output indica gli specialisti raccomandati.
-- **Dipendenze:** meglio dopo OPT-08 (contratto di output stabile).
-
-### OPT-11 — Delegation policy negli orchestratori
-- **Criticità:** LOW · **Sforzo:** Basso · **Rischio:** Basso
-- **Obiettivo:** regola esplicita "delega un subagent solo se serve" (task indipendente/parallelo, output voluminoso, riuso multiplo); non delegare ciò che una grep/read risolve.
-- **Scope:** aggiungere una sezione `## Delegation policy` a `assessment-manager` e `project-manager`.
-- **Criteri di accettazione:** entrambi gli orchestratori contengono i criteri delega/non-delega.
-- **Dipendenze:** nessuna.
-
-### OPT-12 — Hook di filtro output verboso (opzionale)
-- **Criticità:** LOW · **Sforzo:** Basso · **Rischio:** Basso
-- **Obiettivo:** filtrare output verbosi (build/test/log) prima che entrino nel contesto.
-- **Scope:** `PreToolUse` su Bash in `settings.json` + script che riduce l'output di test/build alle sole righe rilevanti.
-- **Criteri di accettazione:** l'hook appare in `/hooks`; un comando di test mostra solo failures.
-- **Dipendenze:** nessuna. Fare solo se gli assessment inizieranno a lanciare build/test.