@fro.bot/systematic 3.24.1 → 3.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/HARNESSES.md +18 -11
  2. package/dist/cli.js +305 -186
  3. package/dist/{index-vkmdceqk.js → index-bmsgc2em.js} +9 -10
  4. package/dist/index.js +1 -1
  5. package/dist/lib/config.d.ts +23 -7
  6. package/dist/lib/pi-subagents-export.d.ts +40 -7
  7. package/dist/lib/pi-subagents-personas.d.ts +9 -0
  8. package/dist/pi-subagents/agents/systematic-adversarial-document-reviewer.md +87 -0
  9. package/dist/pi-subagents/agents/systematic-adversarial-reviewer.md +102 -0
  10. package/dist/pi-subagents/agents/systematic-api-contract-reviewer.md +43 -0
  11. package/dist/pi-subagents/agents/systematic-architecture-strategist.md +50 -0
  12. package/dist/pi-subagents/agents/systematic-best-practices-researcher.md +112 -0
  13. package/dist/pi-subagents/agents/systematic-bug-reproduction-validator.md +88 -0
  14. package/dist/pi-subagents/agents/systematic-cli-readiness-reviewer.md +65 -0
  15. package/dist/pi-subagents/agents/systematic-code-simplicity-reviewer.md +84 -0
  16. package/dist/pi-subagents/agents/systematic-coherence-reviewer.md +37 -0
  17. package/dist/pi-subagents/agents/systematic-correctness-reviewer.md +43 -0
  18. package/dist/pi-subagents/agents/systematic-data-migrations-reviewer.md +47 -0
  19. package/dist/pi-subagents/agents/systematic-deployment-verification-agent.md +157 -0
  20. package/dist/pi-subagents/agents/systematic-design-lens-reviewer.md +44 -0
  21. package/dist/pi-subagents/agents/systematic-feasibility-reviewer.md +40 -0
  22. package/dist/pi-subagents/agents/systematic-framework-docs-researcher.md +91 -0
  23. package/dist/pi-subagents/agents/systematic-git-history-analyzer.md +44 -0
  24. package/dist/pi-subagents/agents/systematic-issue-intelligence-analyst.md +207 -0
  25. package/dist/pi-subagents/agents/systematic-maintainability-reviewer.md +43 -0
  26. package/dist/pi-subagents/agents/systematic-pattern-recognition-specialist.md +55 -0
  27. package/dist/pi-subagents/agents/systematic-performance-reviewer.md +45 -0
  28. package/dist/pi-subagents/agents/systematic-previous-comments-reviewer.md +59 -0
  29. package/dist/pi-subagents/agents/systematic-product-lens-reviewer.md +68 -0
  30. package/dist/pi-subagents/agents/systematic-reliability-reviewer.md +43 -0
  31. package/dist/pi-subagents/agents/systematic-repo-research-analyst.md +322 -0
  32. package/dist/pi-subagents/agents/systematic-scope-guardian-reviewer.md +52 -0
  33. package/dist/pi-subagents/agents/systematic-security-lens-reviewer.md +36 -0
  34. package/dist/pi-subagents/agents/systematic-security-reviewer.md +45 -0
  35. package/dist/pi-subagents/agents/systematic-spec-flow-analyzer.md +82 -0
  36. package/dist/pi-subagents/agents/systematic-testing-reviewer.md +43 -0
  37. package/dist/pi.js +186 -12
  38. package/package.json +17 -9
  39. package/skills/using-systematic/references/pi-profile.md +12 -8
package/dist/cli.js CHANGED
@@ -28,13 +28,14 @@ import {
28
28
  toSourcedPiSubagentsOverlays,
29
29
  resolveRouting,
30
30
  loadConfigWithSources,
31
+ isAgentDisabled,
31
32
  collectRoutingTargets,
32
33
  getConfigPaths,
33
34
  findAgentsInDir,
34
35
  findCommandsInDir,
35
36
  findSkillsInDir,
36
37
  discoverSkills
37
- } from "./index-vkmdceqk.js";
38
+ } from "./index-bmsgc2em.js";
38
39
  var __defProp = Object.defineProperty;
39
40
  var __returnValue = (v) => v;
40
41
  function __exportSetter(name, newValue) {
@@ -1109,6 +1110,9 @@ function generatePersonaManifest(sourceRelPath, rawContent, _repoRoot) {
1109
1110
  reason: compat.reasons.length > 0 ? compat.reasons.join("; ") : undefined
1110
1111
  };
1111
1112
  }
1113
+ function isWrittenEntry(entry) {
1114
+ return entry.status !== "excluded-critical" && Boolean(entry.content);
1115
+ }
1112
1116
  function generateAll(repoRoot) {
1113
1117
  const entries = [];
1114
1118
  const byFoldedFilename = new Map;
@@ -1145,6 +1149,18 @@ Remove these personas from CURATED_PERSONAS or fix the coupling.`);
1145
1149
  }
1146
1150
  return entries;
1147
1151
  }
1152
+ function parseSourceCategoryAndKey(sourceRelPath) {
1153
+ const parts = sourceRelPath.split("/");
1154
+ if (parts.length >= 3 && parts[0] === "agents") {
1155
+ const fileName = parts.at(-1) ?? "";
1156
+ return {
1157
+ category: parts[1],
1158
+ agentKey: fileName.replace(/\.md$/, "")
1159
+ };
1160
+ }
1161
+ const fileName = parts.at(-1) ?? sourceRelPath;
1162
+ return { category: undefined, agentKey: fileName.replace(/\.md$/, "") };
1163
+ }
1148
1164
 
1149
1165
  // src/lib/pi-subagents-export.ts
1150
1166
  var MANIFEST_FILENAME = ".systematic-personas.json";
@@ -1432,9 +1448,10 @@ function snapshotFiles(filePaths) {
1432
1448
  }
1433
1449
  return { ok: true, backup };
1434
1450
  }
1435
- function restoreFromBackup(backup) {
1451
+ function restoreFromBackup(backup, paths) {
1436
1452
  const failed = [];
1437
- for (const [p, content] of backup) {
1453
+ for (const p of paths) {
1454
+ const content = backup.get(p);
1438
1455
  try {
1439
1456
  if (content === undefined) {
1440
1457
  if (fs3.existsSync(p))
@@ -1451,17 +1468,19 @@ function restoreFromBackup(backup) {
1451
1468
  function rollbackMessage(failed) {
1452
1469
  return failed.length === 0 ? "rolled back" : `partial rollback (restoration failed for: ${failed.map((p) => path2.basename(p)).join(", ")})`;
1453
1470
  }
1454
- function runWithRollback(pathsToWatch, ops) {
1455
- const snapshot = snapshotFiles(pathsToWatch);
1471
+ function runWithRollback(steps) {
1472
+ const snapshot = snapshotFiles(steps.map((step) => step.path));
1456
1473
  if (!snapshot.ok) {
1457
1474
  return { ok: false, error: snapshot.error, rollbackFailed: [] };
1458
1475
  }
1459
1476
  const backup = snapshot.backup;
1460
- for (const op of ops) {
1477
+ const completed = [];
1478
+ for (const step of steps) {
1461
1479
  try {
1462
- op();
1480
+ step.run();
1481
+ completed.push(step.path);
1463
1482
  } catch (err) {
1464
- const rollbackFailed = restoreFromBackup(backup);
1483
+ const rollbackFailed = restoreFromBackup(backup, completed);
1465
1484
  const rb = rollbackMessage(rollbackFailed);
1466
1485
  return {
1467
1486
  ok: false,
@@ -1482,18 +1501,6 @@ function ownedFilenames(manifest) {
1482
1501
  }
1483
1502
  return s;
1484
1503
  }
1485
- function parseSourceCategoryAndKey(sourceRelPath) {
1486
- const parts = sourceRelPath.split("/");
1487
- if (parts.length >= 3 && parts[0] === "agents") {
1488
- const fileName = parts.at(-1) ?? "";
1489
- return {
1490
- category: parts[1],
1491
- agentKey: fileName.replace(/\.md$/, "")
1492
- };
1493
- }
1494
- const fileName = parts.at(-1) ?? sourceRelPath;
1495
- return { category: undefined, agentKey: fileName.replace(/\.md$/, "") };
1496
- }
1497
1504
  function lookupOverlay(map, category, agentKey) {
1498
1505
  if (!map)
1499
1506
  return;
@@ -1569,7 +1576,7 @@ ${trimmedBody}`;
1569
1576
  }
1570
1577
  function applyConfigToEntries(entries, config, overlays, piSubagentsOverlays) {
1571
1578
  return entries.map((entry) => {
1572
- if (entry.status === "excluded-critical" || !entry.content)
1579
+ if (!isWrittenEntry(entry))
1573
1580
  return entry;
1574
1581
  const { category, agentKey } = parseSourceCategoryAndKey(entry.sourceRelPath);
1575
1582
  const content = applyConfigToContent(entry.content, config, overlays, piSubagentsOverlays, category, agentKey);
@@ -1577,15 +1584,32 @@ function applyConfigToEntries(entries, config, overlays, piSubagentsOverlays) {
1577
1584
  return { ...entry, content, hash };
1578
1585
  });
1579
1586
  }
1587
+ function wantedFilenames(entries) {
1588
+ return new Set(entries.filter(isWrittenEntry).map((e) => e.filename));
1589
+ }
1580
1590
  function generateEntries(repoRoot, configOptions) {
1581
1591
  const entries = generateAll(repoRoot);
1582
1592
  if (!configOptions)
1583
- return entries;
1593
+ return { entries, disabledFilenames: new Set };
1584
1594
  const { config, overlays } = loadConfigWithSources(configOptions.cwd, {
1585
1595
  includeProject: configOptions.scope === "project"
1586
1596
  });
1597
+ const disabledAgents = new Set(config.disabled_agents);
1598
+ const enabled = [];
1599
+ const disabledFilenames = new Set;
1600
+ for (const entry of entries) {
1601
+ const { category, agentKey } = parseSourceCategoryAndKey(entry.sourceRelPath);
1602
+ if (isAgentDisabled(disabledAgents, overlays.agents, category ?? "", agentKey)) {
1603
+ disabledFilenames.add(entry.filename);
1604
+ } else {
1605
+ enabled.push(entry);
1606
+ }
1607
+ }
1587
1608
  const piSubagentsOverlays = toSourcedPiSubagentsOverlays(config.pi_subagents);
1588
- return applyConfigToEntries(entries, config, overlays, piSubagentsOverlays);
1609
+ return {
1610
+ entries: applyConfigToEntries(enabled, config, overlays, piSubagentsOverlays),
1611
+ disabledFilenames
1612
+ };
1589
1613
  }
1590
1614
  function findPackageRoot() {
1591
1615
  const thisFile = fileURLToPath(import.meta.url);
@@ -1604,8 +1628,7 @@ function findPackageRoot() {
1604
1628
  throw new Error("Could not locate package root (no package.json found)");
1605
1629
  }
1606
1630
  function planExistingEntry(absRoot, filename, hash, owned) {
1607
- const diskContent = fs3.readFileSync(path2.join(absRoot, filename), "utf-8");
1608
- const diskHash = crypto2.createHash("sha256").update(diskContent).digest("hex");
1631
+ const diskHash = hashOfFile(path2.join(absRoot, filename));
1609
1632
  if (owned.has(filename)) {
1610
1633
  return diskHash !== hash ? { action: "update", filename } : { action: "skip", filename };
1611
1634
  }
@@ -1618,25 +1641,25 @@ function planExistingEntry(absRoot, filename, hash, owned) {
1618
1641
  function planEntryActions(absRoot, entries, owned) {
1619
1642
  const actions = [];
1620
1643
  for (const entry of entries) {
1621
- if (entry.status === "excluded-critical" || !entry.content)
1644
+ if (!isWrittenEntry(entry))
1622
1645
  continue;
1623
1646
  const exists = fs3.existsSync(path2.join(absRoot, entry.filename));
1624
1647
  actions.push(exists ? planExistingEntry(absRoot, entry.filename, entry.hash, owned) : { action: "create", filename: entry.filename });
1625
1648
  }
1626
1649
  return actions;
1627
1650
  }
1628
- function planRemoveActions(absRoot, manifest, currentFilenames) {
1651
+ function planRemoveActions(absRoot, manifest, currentFilenames, disabledFilenames) {
1629
1652
  if (!manifest)
1630
1653
  return [];
1631
- const removes = [];
1632
- for (const mEntry of manifest.files) {
1633
- if (currentFilenames.has(mEntry.filename))
1634
- continue;
1635
- const safe = safeFilePath(absRoot, mEntry.filename);
1636
- if (safe !== null && fs3.existsSync(safe))
1637
- removes.push({ action: "remove", filename: mEntry.filename });
1638
- }
1639
- return removes;
1654
+ const { remove, retained } = findStalePaths(absRoot, manifest, currentFilenames, disabledFilenames);
1655
+ return [
1656
+ ...remove.map((target) => ({ action: "remove", filename: target.filename })),
1657
+ ...retained.map((r) => ({
1658
+ action: "retain",
1659
+ filename: r.filename,
1660
+ reason: r.reason
1661
+ }))
1662
+ ];
1640
1663
  }
1641
1664
  function preview(agentsRoot, configOptions) {
1642
1665
  const absRoot = path2.resolve(agentsRoot);
@@ -1650,9 +1673,9 @@ function preview(agentsRoot, configOptions) {
1650
1673
  };
1651
1674
  }
1652
1675
  const manifest = manifestResult.kind === "ok" ? manifestResult.manifest : null;
1653
- let entries;
1676
+ let generated;
1654
1677
  try {
1655
- entries = generateEntries(findPackageRoot(), configOptions);
1678
+ generated = generateEntries(findPackageRoot(), configOptions);
1656
1679
  } catch (err) {
1657
1680
  return {
1658
1681
  status: "error",
@@ -1661,16 +1684,26 @@ function preview(agentsRoot, configOptions) {
1661
1684
  actions: []
1662
1685
  };
1663
1686
  }
1687
+ const { entries, disabledFilenames } = generated;
1664
1688
  const owned = ownedFilenames(manifest);
1665
- const currentFilenames = new Set(entries.filter((e) => e.status !== "excluded-critical" && e.content).map((e) => e.filename));
1666
- return {
1667
- status: "ok",
1668
- agentsRoot: absRoot,
1669
- actions: [
1670
- ...planEntryActions(absRoot, entries, owned),
1671
- ...planRemoveActions(absRoot, manifest, currentFilenames)
1672
- ]
1673
- };
1689
+ const currentFilenames = wantedFilenames(entries);
1690
+ try {
1691
+ return {
1692
+ status: "ok",
1693
+ agentsRoot: absRoot,
1694
+ actions: [
1695
+ ...planEntryActions(absRoot, entries, owned),
1696
+ ...planRemoveActions(absRoot, manifest, currentFilenames, disabledFilenames)
1697
+ ]
1698
+ };
1699
+ } catch (err) {
1700
+ return {
1701
+ status: "error",
1702
+ error: err instanceof Error ? err.message : String(err),
1703
+ agentsRoot: absRoot,
1704
+ actions: []
1705
+ };
1706
+ }
1674
1707
  }
1675
1708
  function classifyOneExportEntry(absRoot, entry, owned) {
1676
1709
  const safePath = safeFilePath(absRoot, entry.filename);
@@ -1682,8 +1715,7 @@ function classifyOneExportEntry(absRoot, entry, owned) {
1682
1715
  reason: "File exists but is not owned by a previous export (user file)"
1683
1716
  };
1684
1717
  if (fs3.existsSync(safePath)) {
1685
- const diskHash = crypto2.createHash("sha256").update(fs3.readFileSync(safePath, "utf-8")).digest("hex");
1686
- if (diskHash === entry.hash)
1718
+ if (hashOfFile(safePath) === entry.hash)
1687
1719
  return { kind: "skip", safePath };
1688
1720
  }
1689
1721
  return { kind: "write", safePath };
@@ -1692,11 +1724,10 @@ function classifyExportEntries(absRoot, entries, owned) {
1692
1724
  const toWrite = [];
1693
1725
  const toSkip = [];
1694
1726
  const refused = [];
1695
- const currentFilenames = new Set;
1727
+ const currentFilenames = wantedFilenames(entries);
1696
1728
  for (const entry of entries) {
1697
- if (entry.status === "excluded-critical" || !entry.content)
1729
+ if (!isWrittenEntry(entry))
1698
1730
  continue;
1699
- currentFilenames.add(entry.filename);
1700
1731
  const result = classifyOneExportEntry(absRoot, entry, owned);
1701
1732
  if (result.kind === "refuse") {
1702
1733
  refused.push({
@@ -1711,7 +1742,7 @@ function classifyExportEntries(absRoot, entries, owned) {
1711
1742
  }
1712
1743
  return { toWrite, toSkip, refused, currentFilenames };
1713
1744
  }
1714
- function buildNewManifestFiles(toWrite, toSkip) {
1745
+ function buildNewManifestFiles(toWrite, toSkip, carriedOver = []) {
1715
1746
  const toFileEntry = (e) => ({
1716
1747
  filename: e.filename,
1717
1748
  hash: e.hash,
@@ -1719,11 +1750,19 @@ function buildNewManifestFiles(toWrite, toSkip) {
1719
1750
  });
1720
1751
  return [
1721
1752
  ...toSkip.map(({ entry }) => toFileEntry(entry)),
1722
- ...toWrite.map(({ entry }) => toFileEntry(entry))
1753
+ ...toWrite.map(({ entry }) => toFileEntry(entry)),
1754
+ ...carriedOver
1723
1755
  ];
1724
1756
  }
1725
1757
  function makeExportError(error) {
1726
- return { status: "error", written: 0, skipped: 0, refused: [], error };
1758
+ return {
1759
+ status: "error",
1760
+ written: 0,
1761
+ skipped: 0,
1762
+ refused: [],
1763
+ retained: [],
1764
+ error
1765
+ };
1727
1766
  }
1728
1767
  function prepareExportRoot(agentsRoot) {
1729
1768
  let preStat = null;
@@ -1740,34 +1779,61 @@ function prepareExportRoot(agentsRoot) {
1740
1779
  }
1741
1780
  }
1742
1781
  function assertHashMatchesOrThrow(filePath, expectedHash, filename, verb) {
1743
- const diskContent = fs3.readFileSync(filePath, "utf-8");
1744
- const diskHash = crypto2.createHash("sha256").update(diskContent).digest("hex");
1745
- if (diskHash !== expectedHash) {
1746
- throw new Error(`Refusing to ${verb} "${filename}": content on disk does not match the ` + `manifest hash (drifted or tampered). Resolve manually or re-export/refresh first.`);
1782
+ if (hashOfFile(filePath) !== expectedHash) {
1783
+ throw new Error(`Refusing to ${verb} "${filename}": content on disk does not match the ` + `manifest hash (drifted or tampered). Resolve it manually: revert the file to its exported content or delete it by hand, then run the command again.`);
1747
1784
  }
1748
1785
  }
1749
- function findStalePaths(absRoot, prevManifest, currentFilenames) {
1786
+ function staleReason(filename, disabled) {
1787
+ return disabled.has(filename) ? "persona disabled" : "persona no longer exported";
1788
+ }
1789
+ function retainedReason(filename, disabled) {
1790
+ return `${staleReason(filename, disabled)}, but the file was edited since export; left in place`;
1791
+ }
1792
+ function findStalePaths(absRoot, prevManifest, currentFilenames, disabledFilenames) {
1793
+ const remove = [];
1794
+ const retained = [];
1750
1795
  if (!prevManifest)
1751
- return [];
1752
- const stale = [];
1796
+ return { remove, retained };
1753
1797
  for (const mEntry of prevManifest.files) {
1754
1798
  if (currentFilenames.has(mEntry.filename))
1755
1799
  continue;
1756
1800
  const safe = safeFilePath(absRoot, mEntry.filename);
1757
1801
  if (safe === null || !fs3.existsSync(safe))
1758
1802
  continue;
1759
- assertHashMatchesOrThrow(safe, mEntry.hash, mEntry.filename, "remove stale file");
1760
- stale.push({ path: safe, filename: mEntry.filename, hash: mEntry.hash });
1803
+ if (hashOfFile(safe) === mEntry.hash) {
1804
+ remove.push({
1805
+ path: safe,
1806
+ filename: mEntry.filename,
1807
+ hash: mEntry.hash,
1808
+ reason: staleReason(mEntry.filename, disabledFilenames)
1809
+ });
1810
+ } else {
1811
+ retained.push({
1812
+ filename: mEntry.filename,
1813
+ reason: retainedReason(mEntry.filename, disabledFilenames),
1814
+ entry: mEntry
1815
+ });
1816
+ }
1761
1817
  }
1762
- return stale;
1818
+ return { remove, retained };
1819
+ }
1820
+ function unlinkStaleOwned({ path: p, filename, hash }) {
1821
+ if (!fs3.existsSync(p))
1822
+ return;
1823
+ assertHashMatchesOrThrow(p, hash, filename, "remove stale file");
1824
+ fs3.unlinkSync(p);
1825
+ }
1826
+ function hashOfFile(filePath) {
1827
+ return crypto2.createHash("sha256").update(fs3.readFileSync(filePath, "utf-8")).digest("hex");
1763
1828
  }
1764
1829
  function exportPersonas(agentsRoot, configOptions) {
1765
- let entries;
1830
+ let generated;
1766
1831
  try {
1767
- entries = generateEntries(findPackageRoot(), configOptions);
1832
+ generated = generateEntries(findPackageRoot(), configOptions);
1768
1833
  } catch (err) {
1769
1834
  return makeExportError(`Failed to generate personas: ${err instanceof Error ? err.message : String(err)}`);
1770
1835
  }
1836
+ const { entries, disabledFilenames } = generated;
1771
1837
  const anchor = anchorForScope(configOptions, agentsRoot);
1772
1838
  try {
1773
1839
  assertAnchoredPathSafe(anchor, path2.resolve(agentsRoot));
@@ -1790,30 +1856,35 @@ function exportPersonas(agentsRoot, configOptions) {
1790
1856
  const prevManifest = manifestResult.kind === "ok" ? manifestResult.manifest : null;
1791
1857
  const owned = ownedFilenames(prevManifest);
1792
1858
  const { toWrite, toSkip, refused, currentFilenames } = classifyExportEntries(absRoot, entries, owned);
1793
- let staleOwned;
1859
+ let stale;
1794
1860
  try {
1795
- staleOwned = findStalePaths(absRoot, prevManifest, currentFilenames);
1861
+ stale = findStalePaths(absRoot, prevManifest, currentFilenames, disabledFilenames);
1796
1862
  } catch (err) {
1797
1863
  return makeExportError(err instanceof Error ? err.message : String(err));
1798
1864
  }
1865
+ const staleOwned = stale.remove;
1866
+ const retained = stale.retained.map(({ filename, reason }) => ({
1867
+ filename,
1868
+ reason
1869
+ }));
1799
1870
  const newManifest = () => ({
1800
1871
  generatedAt: new Date().toISOString(),
1801
1872
  agentsRoot: absRoot,
1802
- files: buildNewManifestFiles(toWrite, toSkip)
1873
+ files: buildNewManifestFiles(toWrite, toSkip, stale.retained.map((r) => r.entry))
1803
1874
  });
1804
1875
  const tx = runWithRollback([
1805
- ...toWrite.map((x) => x.safePath),
1806
- ...staleOwned.map((x) => x.path),
1807
- path2.join(absRoot, MANIFEST_FILENAME)
1808
- ], [
1809
- ...toWrite.map(({ entry, safePath }) => () => atomicWriteString(safePath, entry.content ?? "")),
1810
- ...staleOwned.map(({ path: p, filename, hash }) => () => {
1811
- if (fs3.existsSync(p)) {
1812
- assertHashMatchesOrThrow(p, hash, filename, "remove stale file");
1813
- fs3.unlinkSync(p);
1814
- }
1815
- }),
1816
- () => writeManifest(absRoot, newManifest())
1876
+ ...toWrite.map(({ entry, safePath }) => ({
1877
+ path: safePath,
1878
+ run: () => atomicWriteString(safePath, entry.content ?? "")
1879
+ })),
1880
+ ...staleOwned.map((target) => ({
1881
+ path: target.path,
1882
+ run: () => unlinkStaleOwned(target)
1883
+ })),
1884
+ {
1885
+ path: path2.join(absRoot, MANIFEST_FILENAME),
1886
+ run: () => writeManifest(absRoot, newManifest())
1887
+ }
1817
1888
  ]);
1818
1889
  if (!tx.ok)
1819
1890
  return {
@@ -1821,19 +1892,31 @@ function exportPersonas(agentsRoot, configOptions) {
1821
1892
  written: 0,
1822
1893
  skipped: toSkip.length,
1823
1894
  refused,
1895
+ retained,
1824
1896
  error: tx.error
1825
1897
  };
1826
1898
  return {
1827
1899
  status: "ok",
1828
1900
  written: toWrite.length,
1829
1901
  skipped: toSkip.length,
1830
- refused
1902
+ refused,
1903
+ retained
1831
1904
  };
1832
1905
  });
1833
1906
  if (!lockResult.locked)
1834
1907
  return makeExportError(lockResult.error);
1835
1908
  return lockResult.result;
1836
1909
  }
1910
+ function makeRefreshError(error, skippedUnowned = 0) {
1911
+ return {
1912
+ status: "error",
1913
+ updated: 0,
1914
+ removed: [],
1915
+ retained: [],
1916
+ skippedUnowned,
1917
+ error
1918
+ };
1919
+ }
1837
1920
  function classifyOneRefreshEntry(absRoot, entry, owned) {
1838
1921
  const safePath = safeFilePath(absRoot, entry.filename);
1839
1922
  if (safePath === null)
@@ -1844,8 +1927,7 @@ function classifyOneRefreshEntry(absRoot, entry, owned) {
1844
1927
  if (!exists && !owned.has(entry.filename))
1845
1928
  return { kind: "skip-unexported" };
1846
1929
  if (exists) {
1847
- const diskHash = crypto2.createHash("sha256").update(fs3.readFileSync(safePath, "utf-8")).digest("hex");
1848
- if (diskHash === entry.hash)
1930
+ if (hashOfFile(safePath) === entry.hash)
1849
1931
  return { kind: "keep", safePath };
1850
1932
  }
1851
1933
  return { kind: "update", safePath };
@@ -1855,7 +1937,7 @@ function classifyRefreshEntries(absRoot, entries, owned) {
1855
1937
  const toKeep = [];
1856
1938
  let skippedUnowned = 0;
1857
1939
  for (const entry of entries) {
1858
- if (entry.status === "excluded-critical" || !entry.content)
1940
+ if (!isWrittenEntry(entry))
1859
1941
  continue;
1860
1942
  const result = classifyOneRefreshEntry(absRoot, entry, owned);
1861
1943
  if (result.kind === "skip-unowned") {
@@ -1874,54 +1956,30 @@ function classifyRefreshEntries(absRoot, entries, owned) {
1874
1956
  function validateRefreshRoot(agentsRoot) {
1875
1957
  const absRoot = path2.resolve(agentsRoot);
1876
1958
  if (!fs3.existsSync(absRoot))
1877
- return {
1878
- status: "error",
1879
- updated: 0,
1880
- skippedUnowned: 0,
1881
- error: `Agents root does not exist: ${absRoot}. Run export first.`
1882
- };
1959
+ return makeRefreshError(`Agents root does not exist: ${absRoot}. Run export first.`);
1883
1960
  try {
1884
1961
  const stat = fs3.lstatSync(absRoot);
1885
1962
  if (stat.isSymbolicLink())
1886
- return {
1887
- status: "error",
1888
- updated: 0,
1889
- skippedUnowned: 0,
1890
- error: `Refusing to write under ${absRoot}: not a real directory (symlink)`
1891
- };
1963
+ return makeRefreshError(`Refusing to write under ${absRoot}: not a real directory (symlink)`);
1892
1964
  } catch (err) {
1893
- return {
1894
- status: "error",
1895
- updated: 0,
1896
- skippedUnowned: 0,
1897
- error: err instanceof Error ? err.message : String(err)
1898
- };
1965
+ return makeRefreshError(err instanceof Error ? err.message : String(err));
1899
1966
  }
1900
1967
  return absRoot;
1901
1968
  }
1902
1969
  function refresh(agentsRoot, configOptions) {
1903
- let entries;
1970
+ let generated;
1904
1971
  try {
1905
- entries = generateEntries(findPackageRoot(), configOptions);
1972
+ generated = generateEntries(findPackageRoot(), configOptions);
1906
1973
  } catch (err) {
1907
- return {
1908
- status: "error",
1909
- updated: 0,
1910
- skippedUnowned: 0,
1911
- error: `Failed to generate personas: ${err instanceof Error ? err.message : String(err)}`
1912
- };
1974
+ return makeRefreshError(`Failed to generate personas: ${err instanceof Error ? err.message : String(err)}`);
1913
1975
  }
1976
+ const { entries, disabledFilenames } = generated;
1914
1977
  const absRootCandidate = path2.resolve(agentsRoot);
1915
1978
  const anchor = anchorForScope(configOptions, absRootCandidate);
1916
1979
  try {
1917
1980
  assertAnchoredPathSafe(anchor, absRootCandidate);
1918
1981
  } catch (err) {
1919
- return {
1920
- status: "error",
1921
- updated: 0,
1922
- skippedUnowned: 0,
1923
- error: err instanceof Error ? err.message : String(err)
1924
- };
1982
+ return makeRefreshError(err instanceof Error ? err.message : String(err));
1925
1983
  }
1926
1984
  const rootOrErr = validateRefreshRoot(agentsRoot);
1927
1985
  if (typeof rootOrErr !== "string")
@@ -1930,48 +1988,61 @@ function refresh(agentsRoot, configOptions) {
1930
1988
  try {
1931
1989
  absRoot = assertCanonicalRootWithinAnchor(anchor, rootOrErr);
1932
1990
  } catch (err) {
1933
- return {
1934
- status: "error",
1935
- updated: 0,
1936
- skippedUnowned: 0,
1937
- error: err instanceof Error ? err.message : String(err)
1938
- };
1991
+ return makeRefreshError(err instanceof Error ? err.message : String(err));
1939
1992
  }
1940
1993
  const lockResult = withLock(absRoot, () => {
1941
1994
  const manifestResult = readManifestStrict(absRoot);
1942
1995
  if (manifestResult.kind === "malformed")
1943
- return {
1944
- status: "error",
1945
- updated: 0,
1946
- skippedUnowned: 0,
1947
- error: `Malformed manifest \u2014 refusing to refresh: ${manifestResult.error}`
1948
- };
1996
+ return makeRefreshError(`Malformed manifest \u2014 refusing to refresh: ${manifestResult.error}`);
1949
1997
  const manifest = manifestResult.kind === "ok" ? manifestResult.manifest : null;
1950
1998
  const { toUpdate, toKeep, skippedUnowned } = classifyRefreshEntries(absRoot, entries, ownedFilenames(manifest));
1999
+ const currentFilenames = wantedFilenames(entries);
2000
+ let stale;
2001
+ try {
2002
+ stale = findStalePaths(absRoot, manifest, currentFilenames, disabledFilenames);
2003
+ } catch (err) {
2004
+ return makeRefreshError(err instanceof Error ? err.message : String(err), skippedUnowned);
2005
+ }
1951
2006
  const needsManifest = manifest !== null || toUpdate.length + toKeep.length > 0;
1952
2007
  const newManifest = () => ({
1953
2008
  generatedAt: new Date().toISOString(),
1954
2009
  agentsRoot: absRoot,
1955
- files: buildNewManifestFiles(toUpdate, toKeep)
2010
+ files: buildNewManifestFiles(toUpdate, toKeep, stale.retained.map((r) => r.entry))
1956
2011
  });
1957
2012
  const tx = runWithRollback([
1958
- ...toUpdate.map((x) => x.safePath),
1959
- path2.join(absRoot, MANIFEST_FILENAME)
1960
- ], [
1961
- ...toUpdate.map(({ entry, safePath }) => () => atomicWriteString(safePath, entry.content ?? "")),
1962
- ...needsManifest ? [() => writeManifest(absRoot, newManifest())] : []
2013
+ ...toUpdate.map(({ entry, safePath }) => ({
2014
+ path: safePath,
2015
+ run: () => atomicWriteString(safePath, entry.content ?? "")
2016
+ })),
2017
+ ...stale.remove.map((target) => ({
2018
+ path: target.path,
2019
+ run: () => unlinkStaleOwned(target)
2020
+ })),
2021
+ ...needsManifest ? [
2022
+ {
2023
+ path: path2.join(absRoot, MANIFEST_FILENAME),
2024
+ run: () => writeManifest(absRoot, newManifest())
2025
+ }
2026
+ ] : []
1963
2027
  ]);
1964
2028
  if (!tx.ok)
1965
- return { status: "error", updated: 0, skippedUnowned, error: tx.error };
1966
- return { status: "ok", updated: toUpdate.length, skippedUnowned };
1967
- });
1968
- if (!lockResult.locked)
2029
+ return makeRefreshError(tx.error ?? "refresh failed", skippedUnowned);
1969
2030
  return {
1970
- status: "error",
1971
- updated: 0,
1972
- skippedUnowned: 0,
1973
- error: lockResult.error
2031
+ status: "ok",
2032
+ updated: toUpdate.length,
2033
+ removed: stale.remove.map(({ filename, reason }) => ({
2034
+ filename,
2035
+ reason
2036
+ })),
2037
+ retained: stale.retained.map(({ filename, reason }) => ({
2038
+ filename,
2039
+ reason
2040
+ })),
2041
+ skippedUnowned
1974
2042
  };
2043
+ });
2044
+ if (!lockResult.locked)
2045
+ return makeRefreshError(lockResult.error);
1975
2046
  return lockResult.result;
1976
2047
  }
1977
2048
  function collectCleanupPaths(absRoot, manifest) {
@@ -2007,21 +2078,23 @@ function cleanup(agentsRoot, configOptions) {
2007
2078
  throw new Error(`Malformed manifest \u2014 refusing to cleanup: ${manifestResult.error}`);
2008
2079
  const manifest = manifestResult.manifest;
2009
2080
  const { targets, manifestPath } = collectCleanupPaths(absRoot, manifest);
2010
- const pathsToWatch = [
2011
- ...targets.map((t) => t.path),
2012
- ...manifestPath ? [manifestPath] : []
2013
- ];
2014
- const tx = runWithRollback(pathsToWatch, [
2015
- ...targets.map(({ path: p, filename, hash }) => () => {
2016
- if (fs3.existsSync(p)) {
2017
- assertHashMatchesOrThrow(p, hash, filename, "delete");
2018
- fs3.unlinkSync(p);
2081
+ const tx = runWithRollback([
2082
+ ...targets.map(({ path: p, filename, hash }) => ({
2083
+ path: p,
2084
+ run: () => {
2085
+ if (fs3.existsSync(p)) {
2086
+ assertHashMatchesOrThrow(p, hash, filename, "delete");
2087
+ fs3.unlinkSync(p);
2088
+ }
2019
2089
  }
2020
- }),
2090
+ })),
2021
2091
  ...manifestPath ? [
2022
- () => {
2023
- if (fs3.existsSync(manifestPath))
2024
- fs3.unlinkSync(manifestPath);
2092
+ {
2093
+ path: manifestPath,
2094
+ run: () => {
2095
+ if (fs3.existsSync(manifestPath))
2096
+ fs3.unlinkSync(manifestPath);
2097
+ }
2025
2098
  }
2026
2099
  ] : []
2027
2100
  ]);
@@ -3154,7 +3227,9 @@ var PI_SUBAGENTS_USAGE = `Usage: systematic pi-subagents <subcommand> [--scope p
3154
3227
  Subcommands:
3155
3228
  preview Show what export would do (no writes)
3156
3229
  export Write persona files to agents dir
3157
- refresh Replace stale owned files from current source
3230
+ refresh Replace stale owned files from current source, and remove unchanged
3231
+ owned files for personas that are no longer exported (edited files
3232
+ stay and are listed as still active)
3158
3233
  cleanup Remove all generated files and manifest
3159
3234
 
3160
3235
  Scope:
@@ -3629,16 +3704,58 @@ function parsePiSubagentsArgs(rest) {
3629
3704
  return { subcommand, scope };
3630
3705
  }
3631
3706
  function printActionLine(a) {
3632
- if (a.action === "create")
3633
- console.log(` + ${a.filename} (create)`);
3634
- else if (a.action === "update")
3635
- console.log(` ~ ${a.filename} (update)`);
3636
- else if (a.action === "refuse")
3637
- console.log(` ! ${a.filename} (refuse: ${a.reason})`);
3638
- else if (a.action === "remove")
3639
- console.log(` - ${a.filename} (remove stale)`);
3640
- else
3641
- console.log(` = ${a.filename} (up to date)`);
3707
+ switch (a.action) {
3708
+ case "create":
3709
+ console.log(` + ${a.filename} (create)`);
3710
+ break;
3711
+ case "update":
3712
+ console.log(` ~ ${a.filename} (update)`);
3713
+ break;
3714
+ case "refuse":
3715
+ console.log(` ! ${a.filename} (refuse: ${a.reason})`);
3716
+ break;
3717
+ case "remove":
3718
+ console.log(` - ${a.filename} (remove stale)`);
3719
+ break;
3720
+ case "skip":
3721
+ console.log(` = ${a.filename} (up to date)`);
3722
+ break;
3723
+ case "retain":
3724
+ break;
3725
+ default: {
3726
+ const unreachable = a;
3727
+ throw new Error(`Unhandled plan action: ${JSON.stringify(unreachable)}`);
3728
+ }
3729
+ }
3730
+ }
3731
+ function printStillActive(retained) {
3732
+ if (retained.length === 0)
3733
+ return;
3734
+ console.log(`
3735
+ Still active in pi-subagents (edited since export, left in place):`);
3736
+ for (const r of retained) {
3737
+ console.log(` ! ${r.filename}: ${r.reason}`);
3738
+ }
3739
+ console.log(" Revert each file to its exported content or delete it, then run this command again to finish.");
3740
+ }
3741
+ function retainedFromPlan(plan) {
3742
+ return plan.actions.flatMap((a) => a.action === "retain" ? [{ filename: a.filename, reason: a.reason }] : []);
3743
+ }
3744
+ function summarizePlan(plan) {
3745
+ const counts = {
3746
+ create: 0,
3747
+ update: 0,
3748
+ refuse: 0,
3749
+ remove: 0,
3750
+ skip: 0,
3751
+ retain: 0
3752
+ };
3753
+ for (const a of plan.actions) {
3754
+ counts[a.action]++;
3755
+ printActionLine(a);
3756
+ }
3757
+ console.log("");
3758
+ console.log(`Summary: ${counts.create} create, ${counts.update} update, ` + `${counts.skip} skip, ${counts.refuse} refuse, ${counts.remove} remove, ` + `${counts.retain} still active`);
3642
3759
  }
3643
3760
  function runPreview(agentsRoot, scope) {
3644
3761
  const plan = preview(agentsRoot, { scope, cwd: process.cwd() });
@@ -3652,13 +3769,8 @@ function runPreview(agentsRoot, scope) {
3652
3769
  console.log("No actions needed (nothing to export).");
3653
3770
  return;
3654
3771
  }
3655
- const counts = { create: 0, update: 0, refuse: 0, remove: 0, skip: 0 };
3656
- for (const a of plan.actions) {
3657
- counts[a.action]++;
3658
- printActionLine(a);
3659
- }
3660
- console.log("");
3661
- console.log(`Summary: ${counts.create} create, ${counts.update} update, ` + `${counts.skip} skip, ${counts.refuse} refuse, ${counts.remove} remove`);
3772
+ summarizePlan(plan);
3773
+ printStillActive(retainedFromPlan(plan));
3662
3774
  }
3663
3775
  function runExport(agentsRoot, scope) {
3664
3776
  const configOptions = { scope, cwd: process.cwd() };
@@ -3671,16 +3783,14 @@ function runExport(agentsRoot, scope) {
3671
3783
  const hasWork = plan.actions.some((a) => a.action === "create" || a.action === "update" || a.action === "refuse" || a.action === "remove");
3672
3784
  if (plan.actions.length > 0) {
3673
3785
  console.log("");
3674
- const counts = { create: 0, update: 0, refuse: 0, remove: 0, skip: 0 };
3675
- for (const a of plan.actions) {
3676
- counts[a.action]++;
3677
- printActionLine(a);
3678
- }
3679
- console.log("");
3680
- console.log(`Summary: ${counts.create} create, ${counts.update} update, ` + `${counts.skip} skip, ${counts.refuse} refuse, ${counts.remove} remove`);
3786
+ summarizePlan(plan);
3681
3787
  }
3682
3788
  if (!hasWork) {
3683
- console.log("All persona files are already up to date. No changes.");
3789
+ const stillActive = retainedFromPlan(plan);
3790
+ if (stillActive.length === 0) {
3791
+ console.log("All persona files are already up to date. No changes.");
3792
+ }
3793
+ printStillActive(stillActive);
3684
3794
  return;
3685
3795
  }
3686
3796
  const result = exportPersonas(agentsRoot, configOptions);
@@ -3689,7 +3799,7 @@ function runExport(agentsRoot, scope) {
3689
3799
  process.exit(1);
3690
3800
  }
3691
3801
  const hadRemovals = plan.actions.some((a) => a.action === "remove");
3692
- if (result.written === 0 && result.refused.length === 0 && !hadRemovals) {
3802
+ if (result.written === 0 && result.refused.length === 0 && result.retained.length === 0 && !hadRemovals) {
3693
3803
  console.log("All persona files are already up to date. No changes.");
3694
3804
  } else {
3695
3805
  console.log(`Exported ${result.written} file(s) to ${agentsRoot}/ (${result.skipped} already up to date).`);
@@ -3700,6 +3810,7 @@ Refused (pre-existing unowned files not overwritten):`);
3700
3810
  for (const r of result.refused)
3701
3811
  console.log(` ! ${r.filename}: ${r.reason}`);
3702
3812
  }
3813
+ printStillActive(result.retained);
3703
3814
  }
3704
3815
  function runRefresh(agentsRoot, scope) {
3705
3816
  const result = refresh(agentsRoot, { scope, cwd: process.cwd() });
@@ -3707,13 +3818,21 @@ function runRefresh(agentsRoot, scope) {
3707
3818
  console.error(`Refresh failed: ${result.error ?? "unknown error"}`);
3708
3819
  process.exit(1);
3709
3820
  }
3710
- if (result.updated === 0) {
3821
+ const changed = result.updated + result.removed.length + result.retained.length > 0;
3822
+ if (!changed) {
3711
3823
  console.log("All owned persona files are up to date. No changes.");
3712
- } else {
3824
+ }
3825
+ if (result.updated > 0) {
3713
3826
  console.log(`Refreshed: updated ${result.updated} file(s) in ${agentsRoot}/.`);
3714
3827
  }
3828
+ if (result.removed.length > 0) {
3829
+ console.log(`Removed ${result.removed.length} file(s) from ${agentsRoot}/ (persona disabled or no longer exported):`);
3830
+ for (const r of result.removed)
3831
+ console.log(` - ${r.filename}`);
3832
+ }
3715
3833
  if (result.skippedUnowned > 0)
3716
3834
  console.log(` Skipped ${result.skippedUnowned} unowned file(s) (not touched).`);
3835
+ printStillActive(result.retained);
3717
3836
  }
3718
3837
  function runCleanup(agentsRoot, scope) {
3719
3838
  let result;