@alexandrealvaro/agentic 0.9.3-beta.1 → 0.9.4-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexandrealvaro/agentic",
-  "version": "0.9.3-beta.1",
+  "version": "0.9.4-beta.1",
   "description": "Bootstrap and audit AGENTS.md, ARCHITECTURE.md, ADRs, skills, and subagents for engineering production code with LLMs",
   "type": "module",
   "bin": {

package/src/commands/init.js

@@ -48,6 +48,7 @@ const ROOT_DOC_LABEL = {
   updated: '~ ',
   unchanged: '· ',
   skipped: '! ',
+  'kept-stale': '! ',
   absent: '',
 };
 

package/src/commands/update.js

@@ -47,6 +47,7 @@ const ACTION_SYMBOL = {
   kept: '·',
   skipped: '!',
   removed: '-',
+  'removed-missing': '?',
   'orphan-kept': '?',
 };
 
@@ -55,6 +56,7 @@ const ROOT_DOC_LABEL = {
   updated: '~ ',
   unchanged: '· ',
   skipped: '! ',
+  'kept-stale': '! ',
   absent: '',
 };
 
@@ -86,13 +88,24 @@ function skillsForAgent(agent, profileName, optedSkills) {
   return [...universal, ...conditional];
 }
 
-function previousAgentsFromStates(cwd) {
-  const out = [];
+/**
+ * Load every per-agent state file once. Returns `{ statesByAgent, agents }`
+ * where `agents` lists the agents whose state files exist on disk. Avoids
+ * the prior pattern of calling `loadState` twice per agent (once for
+ * presence detection, once for content); also surfaces malformed-state
+ * errors with the loader's own context, in a single pass.
+ */
+function loadStatesOnce(cwd) {
+  const statesByAgent = {};
+  const agents = [];
   for (const agent of VALID_AGENTS) {
     const state = loadState(cwd, agent);
-    if (state) out.push(agent);
+    if (state) {
+      statesByAgent[agent] = state;
+      agents.push(agent);
+    }
   }
-  return out;
+  return { statesByAgent, agents };
 }
 
 function previouslyOptedConditional(previousStates, currentAgents, profileName) {
@@ -140,18 +153,23 @@ export async function updateCommand(opts) {
   }
 
   const cwd = process.cwd();
-  const interactive = process.stdout.isTTY && !opts.yes && !opts.agent;
+  // `--agent` is purely a narrowing flag and does not imply non-interactive
+  // intent. Only `--yes` or a non-TTY shell suppress the TUI per ADR-0009.
+  const interactive = process.stdout.isTTY && !opts.yes;
   const dryRun = Boolean(opts.dryRun);
   const force = Boolean(opts.force);
 
   const detectedAgents = detectAgents(cwd);
   const features = detectFeatures(cwd);
-  const previousAgents = previousAgentsFromStates(cwd);
+  const { statesByAgent, agents: previousAgents } = loadStatesOnce(cwd);
 
   const agents = resolveAgents(opts.agent, detectedAgents, previousAgents);
+  // previousStates is the per-agent slice of statesByAgent restricted to the
+  // agents the current invocation targets. Agents outside the slice keep
+  // their state file untouched on disk.
   const previousStates = {};
   for (const agent of agents) {
-    previousStates[agent] = loadState(cwd, agent);
+    previousStates[agent] = statesByAgent[agent] ?? null;
   }
 
   const profileName = profileFromStates(previousStates, agents);
@@ -282,13 +300,24 @@ export async function updateCommand(opts) {
       }
     : async () => true;
 
-  const rootDocAction = !dryRun
-    ? await updateRootDoc({
-        cwd,
-        skills: skillDisplayOrder,
-        confirmAppend,
-      })
-    : { type: 'absent', path: null };
+  const confirmRootDocReplace = interactive
+    ? async (path) => {
+        const answer = await p.confirm({
+          message: `${path}: managed section diverged on disk. Regenerate it? (any edits between the agentic-managed-skills markers will be lost)`,
+          initialValue: false,
+        });
+        if (p.isCancel(answer)) return false;
+        return answer;
+      }
+    : async () => Boolean(force);
+
+  const rootDocAction = await updateRootDoc({
+    cwd,
+    skills: skillDisplayOrder,
+    confirmAppend,
+    confirmReplace: confirmRootDocReplace,
+    dryRun,
+  });
 
   const lines = allActions.map((a) => {
     const sym = ACTION_SYMBOL[a.type] ?? '?';

package/src/lib/install.js

@@ -356,7 +356,16 @@ export async function removeOrphanSkills({
 
     for (const f of entry.files) {
       const abs = join(cwd, f.path);
-      if (existsSync(abs) && !dryRun) {
+      if (!existsSync(abs)) {
+        // State recorded the file at install time but it is gone on disk
+        // now (manually deleted, moved, or never written). Surface as a
+        // distinct action so the user sees the state-vs-reality mismatch
+        // instead of a silent "removed" line for a file that was never
+        // there.
+        actions.push({ type: 'removed-missing', path: f.path, agent });
+        continue;
+      }
+      if (!dryRun) {
         unlinkSync(abs);
       }
       actions.push({ type: 'removed', path: f.path, agent });

package/src/lib/rootdoc.js

@@ -93,18 +93,23 @@ function replaceSection(body, newSection, bounds) {
  * Behaviour:
  *   - No root doc → returns { type: 'absent', path: null }. Skill bootstraps create the file later.
  *   - Section already present and matches → { type: 'unchanged', path }.
- *   - Section already present and stale → updated in place → { type: 'updated', path }.
+ *   - Section already present and stale → confirmReplace(path) is called; on true → updated → { type: 'updated', path }; on false → { type: 'kept-stale', path } (managed-section diverged on disk and the user chose to keep it).
  *   - Section absent → confirmAppend(path) is called; on true → appended → { type: 'appended', path }; on false → { type: 'skipped', path }.
+ *   - dryRun true → no writes; returned `type` reflects what *would* happen.
  *
  * @param {object} opts
  * @param {string} opts.cwd  Target project root.
  * @param {string[]} opts.skills  Skill names actually installed (in display order).
  * @param {(path: string) => Promise<boolean>} [opts.confirmAppend]  Async confirmation callback for the append-to-existing-file case. Default: skip.
+ * @param {(path: string) => Promise<boolean>} [opts.confirmReplace]  Async confirmation callback for the replace-existing-section case (managed section present on disk but stale). Default: replace (preserves the v0.5 behaviour where update silently regenerates the managed block on every kit / skill change). Wire to a prompt to honor user edits between markers.
+ * @param {boolean} [opts.dryRun]  When true, computes the action without writing.
  */
 export async function updateRootDoc({
   cwd,
   skills,
   confirmAppend = async () => false,
+  confirmReplace = async () => true,
+  dryRun = false,
 }) {
   const found = findRootDoc(cwd);
   if (!found) return { type: 'absent', path: null };
@@ -116,7 +121,9 @@ export async function updateRootDoc({
   if (bounds) {
     const updated = replaceSection(body, section, bounds);
     if (updated === body) return { type: 'unchanged', path: found.name };
-    writeFileSync(found.path, updated);
+    const ok = await confirmReplace(found.name);
+    if (!ok) return { type: 'kept-stale', path: found.name };
+    if (!dryRun) writeFileSync(found.path, updated);
     return { type: 'updated', path: found.name };
   }
 
@@ -124,6 +131,6 @@ export async function updateRootDoc({
   if (!ok) return { type: 'skipped', path: found.name };
 
   const sep = body.endsWith('\n') ? '\n' : '\n\n';
-  writeFileSync(found.path, body + sep + section + '\n');
+  if (!dryRun) writeFileSync(found.path, body + sep + section + '\n');
   return { type: 'appended', path: found.name };
 }

package/src/lib/state.js

@@ -77,9 +77,22 @@ export function saveState(cwd, agent, state) {
 }
 
 function orderState(state) {
+  if (!state || typeof state !== 'object') {
+    throw new Error('orderState: state must be an object');
+  }
+  if (!state.skills || typeof state.skills !== 'object') {
+    throw new Error(
+      'orderState: state.skills must be an object (got ' + typeof state.skills + ')'
+    );
+  }
   const skills = {};
   for (const skillName of Object.keys(state.skills).sort()) {
     const entry = state.skills[skillName];
+    if (!entry || !Array.isArray(entry.files)) {
+      throw new Error(
+        `orderState: state.skills["${skillName}"].files must be an array`
+      );
+    }
     const files = [...entry.files].sort((a, b) => a.path.localeCompare(b.path));
     skills[skillName] = {
       version: entry.version,