forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/setup.js

@@ -1,5 +1,6 @@
 const fs = require('node:fs');
 const path = require('node:path');
+const { cleanupDeprecatedSyncFiles } = require('./deprecated-sync-cleanup');
 
 /**
  * Save setup state to .forge/setup-state.json
@@ -110,76 +111,36 @@ async function markStepComplete(projectPath, stepName) {
 }
 
 /**
- * Scaffold GitHub-Beads sync files into a target project.
- * Copies workflow, config, and mapping template — never overwrites existing files.
+ * Remove generated GitHub-Beads sync scaffold from existing installs.
+ *
+ * @param {string} projectPath - Target project root
+ * @returns {Promise<{removed: string[], skipped: string[]}>}
+ */
+async function cleanupDeprecatedGithubBeadsSync(projectPath, options = {}) {
+  return cleanupDeprecatedSyncFiles(projectPath, options);
+}
+
+/**
+ * Deprecated compatibility shim for the removed GitHub-Beads sync scaffold.
+ *
+ * Performs cleanup of generated legacy sync artifacts only. User-owned files
+ * at matching paths are preserved unless their content matches known generated
+ * templates.
  *
  * @param {string} projectPath - Target project root
  * @param {string} pkgDir - Forge package directory (source of template files)
- * @returns {Promise<{created: string[], skipped: string[]}>}
+ * @returns {Promise<{created: string[], skipped: string[], removed: string[], deprecated: boolean, message: string}>}
  */
 async function scaffoldGithubBeadsSync(projectPath, pkgDir) {
-  const created = [];
-  const skipped = [];
-
-  // Sync script modules that workflows depend on at runtime
-  const syncScripts = [
-    'config.mjs', 'mapping.mjs', 'comment.mjs', 'github-api.mjs',
-    'sanitize.mjs', 'run-bd.mjs', 'label-mapper.mjs', 'index.mjs',
-    'reverse-sync.mjs', 'reverse-sync-cli.mjs',
-  ];
-
-  const files = [
-    // Phase 1: GitHub → Beads
-    {
-      src: path.join(pkgDir, '.github', 'workflows', 'github-to-beads.yml'),
-      dest: path.join('.github', 'workflows', 'github-to-beads.yml'),
-    },
-    // Phase 2: Beads → GitHub
-    {
-      src: path.join(pkgDir, '.github', 'workflows', 'beads-to-github.yml'),
-      dest: path.join('.github', 'workflows', 'beads-to-github.yml'),
-    },
-    {
-      src: path.join(pkgDir, 'scripts', 'github-beads-sync.config.json'),
-      dest: path.join('scripts', 'github-beads-sync.config.json'),
-    },
-    {
-      src: null, // generated in-place (empty mapping template)
-      dest: path.join('.github', 'beads-mapping.json'),
-      content: '{}',
-    },
-    // Sync script modules
-    ...syncScripts.map((name) => ({
-      src: path.join(pkgDir, 'scripts', 'github-beads-sync', name),
-      dest: path.join('scripts', 'github-beads-sync', name),
-    })),
-  ];
-
-  for (const file of files) {
-    const destPath = path.join(projectPath, file.dest);
-
-    // Never overwrite existing files — preserve user customizations
-    if (fs.existsSync(destPath)) {
-      skipped.push(file.dest);
-      continue;
-    }
-
-    // Ensure parent directory exists
-    const destDir = path.dirname(destPath);
-    await fs.promises.mkdir(destDir, { recursive: true });
-
-    if (file.src) {
-      // Copy from template
-      await fs.promises.copyFile(file.src, destPath);
-    } else {
-      // Write generated content
-      await fs.promises.writeFile(destPath, file.content, 'utf-8');
-    }
-
-    created.push(file.dest);
-  }
-
-  return { created, skipped };
+  const cleanup = await cleanupDeprecatedGithubBeadsSync(projectPath, { packageDir: pkgDir });
+
+  return {
+    created: [],
+    skipped: [],
+    removed: cleanup.removed,
+    deprecated: true,
+    message: 'GitHub-Beads sync scaffolding is deprecated; future GitHub issue sync must use Forge Kernel/server authority.'
+  };
 }
 
 module.exports = {
@@ -188,5 +149,6 @@ module.exports = {
   isSetupComplete,
   getNextStep,
   markStepComplete,
+  cleanupDeprecatedGithubBeadsSync,
   scaffoldGithubBeadsSync
 };

package/lib/shell-utils.js

@@ -5,10 +5,62 @@
  */
 
 const { execFileSync, spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+// Extensions Windows can spawn directly via CreateProcess. Anything else that
+// `where.exe` returns — the extensionless POSIX shim (`npm`) or the batch shim
+// (`npm.cmd`) — cannot be handed to execFileSync: the former is a bash script
+// (spawnSync ENOENT, kernel issue 9997d516) and patched Node refuses .cmd/.bat
+// without shell:true (CVE-2024-27980).
+const WINDOWS_DIRECT_SPAWN_EXTS = new Set(['.exe', '.com']);
+
+// Conservative allowlist for tokens executed through cmd.exe. Blocks every cmd
+// metacharacter (& | < > ^ % ! " ' ` ( ) ; and whitespace) so shell execution
+// cannot be turned into injection even if a caller ever passes dynamic input.
+const SAFE_SHELL_TOKEN = /^[A-Za-z0-9@_+=:,./\\-]+$/;
+
+/**
+ * Throw when any token is unsafe to pass through cmd.exe.
+ * @param {string} command - The command name
+ * @param {string[]} args - Command arguments
+ */
+function assertShellSafeTokens(command, args) {
+  for (const token of [command, ...args]) {
+    if (typeof token !== 'string' || !SAFE_SHELL_TOKEN.test(token)) {
+      throw new Error(
+        `Refusing to run "${command}" via shell: unsafe token ${JSON.stringify(token)}`
+      );
+    }
+  }
+}
+
+/**
+ * Decide how to spawn a command on Windows from `where.exe` candidates.
+ * Prefers a directly spawnable .exe/.com — including when the caller already
+ * passed an absolute .exe/.com path (which `where.exe` may not re-enumerate);
+ * otherwise runs the BARE command name through cmd.exe (shell:true), which
+ * resolves npm.cmd/npx.cmd/lefthook.cmd via PATH/PATHEXT — so paths with spaces
+ * never hit shell parsing or the shell-safe token allowlist.
+ *
+ * @param {string} command - Original command name or absolute path
+ * @param {string[]} candidates - Resolved paths from `where.exe`, best first
+ * @returns {{ file: string, shell: boolean }}
+ */
+function resolveWindowsSpawnSpec(command, candidates) {
+  const direct = [command, ...candidates].find(
+    (candidate) => WINDOWS_DIRECT_SPAWN_EXTS.has(path.extname(candidate).toLowerCase())
+  );
+  if (direct) {
+    return { file: direct, shell: false };
+  }
+  return { file: command, shell: true };
+}
 
 /**
  * Securely execute a command with PATH validation.
  * Mitigates SonarCloud S4036: Ensures executables are from trusted locations.
+ * On Windows, handles npm/npx/lefthook-style cmd shims that cannot be spawned
+ * directly (see resolveWindowsSpawnSpec).
  * @param {string} command - The command to execute
  * @param {string[]} [args=[]] - Command arguments
  * @param {object} [options={}] - execFileSync options
@@ -18,16 +70,16 @@ function secureExecFileSync(command, args = [], options = {}) {
   const {
     _execFileSync = execFileSync,
     _spawnSync = spawnSync,
+    _platform = process.platform,
     ...execOptions
   } = options;
 
-  let resolvedPath = null;
+  const isWindows = _platform === 'win32';
+  const pathResolver = isWindows ? 'where.exe' : 'which';
 
+  let candidates = [];
   try {
     // Resolve command's full path to validate it's in a trusted location
-    const isWindows = process.platform === 'win32';
-    const pathResolver = isWindows ? 'where.exe' : 'which';
-
     const result = _spawnSync(pathResolver, [command], {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore']
@@ -35,14 +87,32 @@ function secureExecFileSync(command, args = [], options = {}) {
 
     if (result.status === 0 && result.stdout) {
       // Handle both CRLF (Windows) and LF (Unix) line endings
-      resolvedPath = result.stdout.trim().split(/\r?\n/)[0].trim();
+      candidates = result.stdout
+        .trim()
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
     }
   } catch (_err) { // NOSONAR - S2486: Intentionally ignored; falls back to direct command execution below
   }
 
+  if (isWindows) {
+    const spec = resolveWindowsSpawnSpec(command, candidates);
+    if (spec.shell) {
+      assertShellSafeTokens(command, args);
+      // Node 22 (DEP0190) deprecates passing an args array together with shell:true.
+      // assertShellSafeTokens has already guaranteed every token is free of shell
+      // metacharacters, so fold them into a single command line and pass no args array —
+      // identical execution through cmd.exe (npm.cmd/npx.cmd shims), no deprecation warning.
+      const commandLine = [command, ...args].join(' ');
+      return _execFileSync(commandLine, [], { ...execOptions, shell: true });
+    }
+    return _execFileSync(spec.file, args, execOptions);
+  }
+
   // Fall back only when resolution failed. If execution of the resolved binary
   // throws, propagate that error instead of retrying with the unresolved name.
-  return _execFileSync(resolvedPath || command, args, execOptions);
+  return _execFileSync(candidates[0] || command, args, execOptions);
 }
 
 module.exports = {

package/lib/skills-sync.js

@@ -0,0 +1,330 @@
+/**
+ * @module skills-sync
+ *
+ * Skills-only surface population + drift detection for Forge.
+ *
+ * Canonical source of truth is the committed root `skills/` directory — each
+ * `skills/<name>/SKILL.md` (plus any sibling files) is an auto-surfacing skill.
+ * Agent harness skill directories (`.agents/skills/`, `.claude/skills/`,
+ * `.codex/skills/`, `.cursor/skills/`, `.hermes/skills/`) are GENERATED from that
+ * canonical source. `.agents/skills` is Codex's documented repo-local discovery
+ * path (scanned from cwd up to the repo root) and is the ONE mirror committed to
+ * the repo (kept byte-identical by a pre-commit sync hook + the drift gate), so a
+ * teammate who clones the repo WITHOUT running `forge setup` still gets the Forge
+ * skills/stages auto-discovered. The other mirrors (including `.codex/skills`) are
+ * gitignored and populated at setup only.
+ *
+ * This module is the Forge-internal port of the `@forge/skills` CLI sync step.
+ * Forge cannot depend on `@forge/skills` at runtime (the `packages/` workspace is
+ * excluded from the published npm package), so the minimal population + check
+ * logic lives here. It mirrors the CLI's whole-directory copy semantics so that
+ * `skills sync --check` and this module agree on what "in sync" means.
+ *
+ * Design constraints (locked in kernel-skill-surface-design.md §6):
+ *  - Registry-independent: never requires `.skills/.registry.json` (the registry
+ *    is gitignored and absent on a fresh checkout).
+ *  - AGENTS.md-safe: never writes AGENTS.md (it is the protected workflow contract).
+ *  - Existing-mirror scoped: `checkSkillsSync` only validates agent skill dirs
+ *    that already exist on disk. The gitignored, setup-populated mirrors
+ *    (`.claude/skills`, `.codex/skills`, `.cursor/skills`, `.hermes/skills`) are
+ *    absent on a clean checkout and are correctly skipped; `.agents/skills` is the
+ *    committed mirror that is always present and thus always enforced against the
+ *    canonical source, which is what the gate guarantees.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** Canonical skills live under this directory at the repo/package root. */
+const CANONICAL_SKILLS_DIR = 'skills';
+
+/**
+ * Standard agent harness skill directories, relative to a project root.
+ * Order is stable for deterministic reporting.
+ */
+const AGENT_SKILL_DIRS = [
+  '.agents/skills',
+  '.claude/skills',
+  '.codex/skills',
+  '.cursor/skills',
+  '.hermes/skills',
+];
+
+/** Skill name must be a safe single path segment (no traversal). */
+function isValidSkillName(name) {
+  return (
+    typeof name === 'string' &&
+    name.length > 0 &&
+    name !== '.' &&
+    name !== '..' &&
+    !name.includes('/') &&
+    !name.includes('\\') &&
+    !name.includes('\0')
+  );
+}
+
+/**
+ * List canonical skills under `<sourceRoot>/skills`.
+ *
+ * A skill is any direct subdirectory that contains a `SKILL.md` file.
+ *
+ * @param {string} sourceRoot - Directory containing the canonical `skills/` dir.
+ * @param {object} [options]
+ * @param {Set<string>|string[]} [options.only] - Restrict to these skill names.
+ * @returns {{name: string, sourcePath: string}[]} Sorted list of skills.
+ */
+function listCanonicalSkills(sourceRoot, options = {}) {
+  const skillsDir = path.join(sourceRoot, CANONICAL_SKILLS_DIR);
+  if (!fs.existsSync(skillsDir)) {
+    return [];
+  }
+
+  const only = options.only ? new Set(options.only) : null;
+  const skills = [];
+
+  for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (!isValidSkillName(entry.name)) continue;
+    if (only && !only.has(entry.name)) continue;
+
+    const sourcePath = path.join(skillsDir, entry.name);
+    if (!fs.existsSync(path.join(sourcePath, 'SKILL.md'))) continue;
+
+    skills.push({ name: entry.name, sourcePath });
+  }
+
+  skills.sort((a, b) => a.name.localeCompare(b.name));
+  return skills;
+}
+
+/**
+ * List all files under a directory as paths relative to that directory,
+ * using forward slashes for stable cross-platform comparison.
+ *
+ * @param {string} dir - Directory to walk.
+ * @returns {string[]} Sorted relative file paths.
+ */
+function listFilesRecursive(dir) {
+  const out = [];
+
+  function walk(current, prefix) {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const abs = path.join(current, entry.name);
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(abs, rel);
+      } else if (entry.isFile()) {
+        out.push(rel);
+      }
+    }
+  }
+
+  if (fs.existsSync(dir)) {
+    walk(dir, '');
+  }
+  out.sort((a, b) => a.localeCompare(b));
+  return out;
+}
+
+/** Normalize line endings so Windows CRLF working-tree state is not false drift. */
+function normalizeContent(buffer) {
+  return buffer.toString('utf8').replace(/\r\n/g, '\n');
+}
+
+/**
+ * Remove a symlink sitting at a target path so a real directory can be written
+ * in its place. Only ever removes the link entry itself — never a real
+ * directory (with content) and never the symlink's target.
+ *
+ * Guards against the exact cruft that broke local skill-sync: a pre-existing
+ * DANGLING symlink at a skill dir path, which makes `mkdirSync`/copy fail.
+ *
+ * @param {string} targetPath - Path that may hold a (possibly dangling) symlink.
+ * @returns {boolean} True if a symlink was cleared, false otherwise.
+ */
+function clearSymlinkAtPath(targetPath) {
+  let linkStat;
+  try {
+    // lstat does NOT follow the link, so a dangling symlink is still detected.
+    linkStat = fs.lstatSync(targetPath);
+  } catch {
+    return false; // nothing at this path
+  }
+
+  if (!linkStat.isSymbolicLink()) {
+    return false; // a real file/dir — leave it for the normal copy path
+  }
+
+  // Remove ONLY the link. Neither unlink nor rm follow a symlink's target, so
+  // the (possibly dangling) target's contents are never touched.
+  try {
+    fs.unlinkSync(targetPath);
+  } catch {
+    // Windows directory symlinks/junctions can reject unlink; rmSync removes the
+    // link entry itself without recursing into the target.
+    fs.rmSync(targetPath, { recursive: true, force: true });
+  }
+  return true;
+}
+
+/**
+ * Copy a single skill directory (recursively) from source to target,
+ * overwriting existing files. Byte-for-byte copy (matches CLI cpSync).
+ *
+ * @param {string} sourcePath - Source skill directory.
+ * @param {string} targetPath - Target skill directory.
+ */
+function copySkillDir(sourcePath, targetPath) {
+  fs.mkdirSync(targetPath, { recursive: true });
+  for (const entry of fs.readdirSync(sourcePath, { withFileTypes: true })) {
+    const src = path.join(sourcePath, entry.name);
+    const dest = path.join(targetPath, entry.name);
+    if (entry.isDirectory()) {
+      copySkillDir(src, dest);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(src, dest);
+    }
+  }
+}
+
+/**
+ * Populate an agent harness skills directory from the canonical source.
+ *
+ * Writes `<targetSkillsDir>/<name>/...` for every canonical skill. Existing
+ * skills are overwritten; pre-existing unrelated skill dirs are left untouched
+ * unless `clean` is set.
+ *
+ * @param {object} params
+ * @param {string} params.sourceRoot - Root containing the canonical `skills/` dir.
+ * @param {string} params.targetSkillsDir - Absolute path to the agent skills dir.
+ * @param {Set<string>|string[]} [params.only] - Restrict to these skill names.
+ * @param {boolean} [params.clean=false] - Remove canonical-managed stale dirs first.
+ * @returns {{written: string[]}} Names of skills written.
+ */
+function populateAgentSkills({ sourceRoot, targetSkillsDir, only, clean = false }) {
+  const skills = listCanonicalSkills(sourceRoot, { only });
+  fs.mkdirSync(targetSkillsDir, { recursive: true });
+
+  if (clean) {
+    // Keep-set is the FULL canonical set, not the `only`-filtered subset, so a
+    // partial sync (only: [...]) never deletes other canonical skills' dirs.
+    const canonicalNames = new Set(listCanonicalSkills(sourceRoot).map((s) => s.name));
+    for (const entry of fs.readdirSync(targetSkillsDir, { withFileTypes: true })) {
+      if (entry.isDirectory() && !canonicalNames.has(entry.name)) {
+        fs.rmSync(path.join(targetSkillsDir, entry.name), { recursive: true, force: true });
+      }
+    }
+  }
+
+  const written = [];
+  for (const skill of skills) {
+    const targetPath = path.join(targetSkillsDir, skill.name);
+    // Defensive: clear a pre-existing (possibly dangling) symlink so the copy
+    // doesn't fail. Only symlinks are removed — real dirs are overwritten in place.
+    clearSymlinkAtPath(targetPath);
+    copySkillDir(skill.sourcePath, targetPath);
+    written.push(skill.name);
+  }
+  return { written };
+}
+
+/**
+ * Compare a canonical skill directory against a target copy.
+ *
+ * @param {string} sourcePath - Canonical skill dir.
+ * @param {string} targetPath - Target (generated) skill dir.
+ * @returns {{file: string, status: 'missing'|'changed'|'extra'}[]} Drift entries.
+ */
+function diffSkillDir(sourcePath, targetPath) {
+  const drift = [];
+  const sourceFiles = new Set(listFilesRecursive(sourcePath));
+  const targetFiles = new Set(listFilesRecursive(targetPath));
+
+  for (const rel of sourceFiles) {
+    if (!targetFiles.has(rel)) {
+      drift.push({ file: rel, status: 'missing' });
+      continue;
+    }
+    const a = normalizeContent(fs.readFileSync(path.join(sourcePath, rel)));
+    const b = normalizeContent(fs.readFileSync(path.join(targetPath, rel)));
+    if (a !== b) {
+      drift.push({ file: rel, status: 'changed' });
+    }
+  }
+
+  for (const rel of targetFiles) {
+    if (!sourceFiles.has(rel)) {
+      drift.push({ file: rel, status: 'extra' });
+    }
+  }
+
+  return drift;
+}
+
+/**
+ * Check that existing agent skill mirrors match the canonical source.
+ *
+ * Only agent skill dirs that already EXIST under `repoRoot` are validated. The
+ * gitignored, setup-populated mirrors (`.claude/skills`, `.codex/skills`, etc.)
+ * are absent on a clean checkout and correctly skipped; the committed
+ * `.agents/skills` mirror is always present and always enforced against the
+ * canonical source. Any mirror present locally must match canonical.
+ *
+ * @param {object} params
+ * @param {string} params.repoRoot - Repo root (contains `skills/` + agent dirs).
+ * @param {Set<string>|string[]} [params.only] - Restrict canonical set.
+ * @param {string[]} [params.agentSkillDirs] - Override the agent dirs to scan.
+ * @returns {{inSync: boolean, checkedAgents: string[], drift: object[]}}
+ */
+function checkSkillsSync({ repoRoot, only, agentSkillDirs = AGENT_SKILL_DIRS }) {
+  const skills = listCanonicalSkills(repoRoot, { only });
+  const canonicalByName = new Map(skills.map((s) => [s.name, s]));
+  const drift = [];
+  const checkedAgents = [];
+
+  for (const rel of agentSkillDirs) {
+    const agentDir = path.join(repoRoot, rel);
+    if (!fs.existsSync(agentDir)) continue; // populated at setup time; absence ≠ drift
+    checkedAgents.push(rel);
+
+    const targetNames = fs
+      .readdirSync(agentDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+
+    // Skills present canonically but missing/changed in the mirror.
+    for (const skill of skills) {
+      const targetPath = path.join(agentDir, skill.name);
+      // A regular file at the skill path is corruption, not a valid mirror:
+      // treat it as drift instead of letting diffSkillDir() throw ENOTDIR.
+      if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
+        drift.push({ agent: rel, skill: skill.name, file: 'SKILL.md', status: 'missing' });
+        continue;
+      }
+      for (const entry of diffSkillDir(skill.sourcePath, targetPath)) {
+        drift.push({ agent: rel, skill: skill.name, ...entry });
+      }
+    }
+
+    // Skill dirs in the mirror with no canonical source = stale.
+    for (const name of targetNames) {
+      if (!canonicalByName.has(name)) {
+        drift.push({ agent: rel, skill: name, file: '*', status: 'stale' });
+      }
+    }
+  }
+
+  return { inSync: drift.length === 0, checkedAgents, drift };
+}
+
+module.exports = {
+  CANONICAL_SKILLS_DIR,
+  AGENT_SKILL_DIRS,
+  isValidSkillName,
+  listCanonicalSkills,
+  listFilesRecursive,
+  clearSymlinkAtPath,
+  populateAgentSkills,
+  diffSkillDir,
+  checkSkillsSync,
+};

package/lib/smart-status/scoring.js

@@ -104,7 +104,12 @@ function buildDependentsMap(issues) {
 
 	for (const issue of issues) {
 		for (const dependency of issue.dependencies ?? []) {
-			const dependencyId = dependency?.depends_on_id;
+			// The Kernel emits `dependencies` as bare id strings; the legacy shape
+			// used `{ depends_on_id }` objects. Accept both so the reverse-graph is
+			// reconstructable even when an issue arrives without a `dependents` array.
+			const dependencyId = typeof dependency === 'string'
+				? dependency
+				: dependency?.depends_on_id;
 			if (!dependencyId) {
 				continue;
 			}
@@ -139,13 +144,22 @@ function scoreIssues(issues, options = {}) {
 	return [...issues]
 		.map((issue) => {
 			const priorityWeight = getPriorityWeight(issue.priority);
-			const directDependents = issue.dependent_count ?? dependentsMap.get(issue.id)?.length ?? 0;
+			// Prefer an explicit count, then the Kernel's authoritative `dependents`
+			// reverse-graph array, then the locally-reconstructed map (legacy shape).
+			const directDependents = issue.dependent_count
+				?? (Array.isArray(issue.dependents) ? issue.dependents.length : undefined)
+				?? dependentsMap.get(issue.id)?.length
+				?? 0;
 			const unblockChain = Math.max(directDependents + 1, 1);
 			const typeWeight = getTypeWeight(issue.type);
 			const statusBoost = getStatusBoost(issue.status);
 			const epicProximity = getEpicProximity(issue, epicStats);
 			const stalenessBoost = getStalenessBoost(issue.updated_at, now);
-			const dependents = dependentsMap.get(issue.id) ?? [];
+			// The Kernel supplies `dependents` directly (reverse graph); fall back to
+			// the reconstructed map only for the legacy { depends_on_id } shape.
+			const dependents = Array.isArray(issue.dependents)
+				? issue.dependents
+				: (dependentsMap.get(issue.id) ?? []);
 			const score = priorityWeight
 				* unblockChain
 				* typeWeight

package/lib/status/beads-snapshot.js

@@ -67,6 +67,8 @@ function isAssignedToDeveloper(issue, developer) {
 	return developer.name !== '' && issue.created_by === developer.name;
 }
 
+const DEFAULT_STALE_AFTER_DAYS = 14;
+
 function parseTimestampOrZero(value) {
 	if (!value) {
 		return 0;
@@ -82,16 +84,55 @@ function sortByUpdatedAtDesc(left, right) {
 	return rightTime - leftTime;
 }
 
-function readBeadsSnapshot(projectRoot) {
+function hasUnresolvedDependencies(issue) {
+	return Number(issue.dependency_count || 0) > 0;
+}
+
+function isOpenIssue(issue) {
+	return issue.status === 'open' || issue.status === 'in_progress';
+}
+
+function isStale(issue, now, staleAfterDays) {
+	if (!isOpenIssue(issue)) {
+		return false;
+	}
+
+	const updatedAt = parseTimestampOrZero(issue.updated_at);
+	if (updatedAt === 0) {
+		return false;
+	}
+
+	const staleMs = staleAfterDays * 24 * 60 * 60 * 1000;
+	return now.getTime() - updatedAt >= staleMs;
+}
+
+function readBeadsSnapshot(projectRoot, options = {}) {
 	const developer = getDeveloperIdentity(projectRoot);
 	const issues = readIssues(projectRoot);
+	const parsedNow = options.now instanceof Date
+		? options.now
+		: (typeof options.now === 'string' ? new Date(options.now) : null);
+	const now = parsedNow instanceof Date && !Number.isNaN(parsedNow.getTime())
+		? parsedNow
+		: new Date();
+	const parsedStaleAfterDays = Number(options.staleAfterDays);
+	const staleAfterDays = Number.isFinite(parsedStaleAfterDays)
+		? parsedStaleAfterDays
+		: DEFAULT_STALE_AFTER_DAYS;
 
 	return {
 		developer,
 		issues,
+		active: issues.filter(issue => issue.status === 'in_progress').sort(sortByUpdatedAtDesc),
 		activeAssigned: issues.filter(issue => issue.status === 'in_progress' && isAssignedToDeveloper(issue, developer)),
-		ready: issues.filter(issue => issue.status === 'open' && Number(issue.dependency_count || 0) === 0),
+		ready: issues.filter(issue => issue.status === 'open' && !hasUnresolvedDependencies(issue)),
+		blocked: issues.filter(issue => isOpenIssue(issue) && hasUnresolvedDependencies(issue)).sort(sortByUpdatedAtDesc),
+		stale: issues.filter(issue => isStale(issue, now, staleAfterDays)).sort(sortByUpdatedAtDesc),
 		recentCompleted: issues.filter(issue => issue.status === 'closed').sort(sortByUpdatedAtDesc),
+		limits: [
+			'Uses local Beads issues.jsonl only.',
+			'Does not read GitHub review, CI, project, or sync freshness state.',
+		],
 	};
 }
 
@@ -99,4 +140,6 @@ module.exports = {
 	getDeveloperIdentity,
 	isAssignedToDeveloper,
 	readBeadsSnapshot,
+	hasUnresolvedDependencies,
+	isStale,
 };