fix(#1058): cross-reference install manifest in validate agents to catch .md/.toml pair drift (#1079)

* fix(#1058): cross-reference install manifest in validate agents to catch pair drift

`validate agents` considered an agent installed if ANY supported file format was
present on disk. The Codex installer generates a per-agent PAIR (agents/gsd-*.md
AND agents/gsd-*.toml) and records both in gsd-file-manifest.json, so a partial
generated install — one side of the pair missing — was reported as healthy
(agents_found: true, missing: []), masking an incomplete Codex agent install.

checkAgentsInstalled now cross-references the install manifest beside the agents
dir (path.dirname(agentsDir)/gsd-file-manifest.json): for each expected agent, if
the manifest tracks files for it and any tracked file is absent on disk, the
agent is reported in a new `incomplete` list and agents_found becomes false. The
check no-ops when no manifest is present (preserves bundled/claude behavior) and
is scoped to expected agents so retired/stale manifest entries cannot false-flag.

Regression cases added to tests/agent-install-validation.test.cjs cover the
drift case, the complete-pair (no false positive), and the no-manifest no-op.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(#1058): add changeset for validate-agents manifest pair-drift fix

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

src/core.cts

@@ -211,6 +211,7 @@ interface AgentsInstalledResult {
   agents_installed: boolean;
   missing_agents: string[];
   installed_agents: string[];
+  incomplete_agents: string[];
   agents_dir: string;
   agent_runtime: string;
 }
@@ -232,6 +233,7 @@ function checkAgentsInstalled(runtime?: string): AgentsInstalledResult {
       agents_installed: false,
       missing_agents: expectedAgents,
       installed_agents: [],
+      incomplete_agents: [],
       agents_dir: agentsDir,
       agent_runtime: resolvedRuntime,
     };
@@ -259,10 +261,61 @@ function checkAgentsInstalled(runtime?: string): AgentsInstalledResult {
     }
   }
 
+  // ── Manifest-backed completeness check ──────────────────────────────────────
+  // If a gsd-file-manifest.json exists alongside the agents dir (parent dir),
+  // verify that every manifest-tracked file for each expected agent is present
+  // on disk. Missing manifest-tracked files indicate an incomplete install even
+  // when the plain presence check above passed (e.g. .md present, .toml absent).
+  // If no manifest is found the check is a no-op (graceful for claude/bundled).
+  const incomplete: string[] = [];
+  const manifestPath = path.join(path.dirname(agentsDir), 'gsd-file-manifest.json');
+  let manifestFiles: Record<string, unknown> = {};
+  try {
+    const raw = fs.readFileSync(manifestPath, 'utf8');
+    const parsed: unknown = JSON.parse(raw);
+    if (
+      parsed !== null &&
+      typeof parsed === 'object' &&
+      'files' in parsed &&
+      typeof (parsed as Record<string, unknown>)['files'] === 'object' &&
+      (parsed as Record<string, unknown>)['files'] !== null
+    ) {
+      manifestFiles = (parsed as Record<string, Record<string, unknown>>)['files'];
+    }
+  } catch {
+    // No manifest or unreadable — completeness check is skipped
+  }
+
+  if (Object.keys(manifestFiles).length > 0) {
+    for (const agent of expectedAgents) {
+      // Find all manifest keys that belong to this agent:
+      // key must be "agents/<agentName>.<ext>" with no further path segments.
+      const agentPrefix = `agents/${agent}.`;
+      const agentManifestKeys = Object.keys(manifestFiles).filter(key => {
+        if (!key.startsWith(agentPrefix)) return false;
+        const rest = key.slice(agentPrefix.length);
+        // rest must be a bare extension (no slashes, non-empty)
+        return rest.length > 0 && !rest.includes('/');
+      });
+      if (agentManifestKeys.length === 0) {
+        // Agent not tracked in manifest — skip completeness check for this agent
+        continue;
+      }
+      const allPresent = agentManifestKeys.every(key => {
+        const basename = key.slice('agents/'.length);
+        return fs.existsSync(path.join(agentsDir, basename));
+      });
+      if (!allPresent) {
+        incomplete.push(agent);
+      }
+    }
+  }
+
   return {
-    agents_installed: installed.length > 0 && missing.length === 0,
+    agents_installed: installed.length > 0 && missing.length === 0 && incomplete.length === 0,
     missing_agents: missing,
     installed_agents: installed,
+    incomplete_agents: incomplete,
     agents_dir: agentsDir,
     agent_runtime: resolvedRuntime,
   };

src/verify.cts

@@ -1107,6 +1107,20 @@ function cmdValidateHealth(
           `No GSD agents found in ${agentStatus.agents_dir} — Task(subagent_type="gsd-*") will fall back to general-purpose`,
           `Run the GSD installer: npx ${PACKAGE_NAME}@latest`,
         );
+      } else if ((agentStatus.incomplete_agents).length > 0 && (agentStatus.missing_agents).length === 0) {
+        addIssue(
+          'warning',
+          'W010',
+          `Incomplete agent installs (missing generated file): ${(agentStatus.incomplete_agents).join(', ')} — affected workflows may fall back to general-purpose`,
+          `Re-run the GSD installer to complete the install: npx ${PACKAGE_NAME}@latest`,
+        );
+      } else if ((agentStatus.incomplete_agents).length > 0) {
+        addIssue(
+          'warning',
+          'W010',
+          `Missing ${(agentStatus.missing_agents).length} GSD agents: ${(agentStatus.missing_agents).join(', ')}; incomplete agent installs (missing generated file): ${(agentStatus.incomplete_agents).join(', ')} — affected workflows will fall back to general-purpose`,
+          `Run the GSD installer: npx ${PACKAGE_NAME}@latest`,
+        );
       } else {
         addIssue(
           'warning',
@@ -1624,6 +1638,7 @@ function cmdValidateAgents(cwd: string, raw: boolean): void {
       agents_found: agentStatus.agents_installed,
       installed: agentStatus.installed_agents,
       missing: agentStatus.missing_agents,
+      incomplete: agentStatus.incomplete_agents,
       expected,
     },
     raw,