godpowers 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -7,6 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-06-08
+
+### Added
+- Added command-family UX metadata for start, continue, build, verify,
+  operate, maintain, capture, recover, extend, collaborate, and configure
+  while keeping every shipped leaf command available.
+- Added capture, work-size, verification, status-view, and trigger-precedence
+  helpers in `lib/command-families.js`.
+- Added typed route outcome metadata for contextual, verdict-based,
+  steady-state, session-end, and selection-based route exits.
+- Added workflow helper groups with serialized plan expansion so closeout
+  helpers can be consolidated without hiding local runtime work.
+
+### Changed
+- Updated `/god`, `/god-help`, `/god-next`, `/god-status`, README,
+  reference docs, recipes, architecture docs, command-flow docs, and
+  auto-invoke visibility docs to present the consolidated UX paths.
+- Updated all shipped command routes with command family metadata.
+- Updated repeated workflow closeout helper lists to named helper groups while
+  preserving explicit expanded helpers in generated plans.
+- Updated extension recipe copy to describe current extension-pack-required
+  flows instead of old release annotations.
+
+### Fixed
+- Route-quality sync now requires typed outcomes for flexible route exits
+  instead of accepting unexplained placeholder next routes.
+- The full-arc e2e smoke test now verifies both helper groups and expanded
+  local helper visibility.
+
+## [2.3.1] - 2026-06-08
+
+### Added
+- Added `/god-extension-scaffold` as the slash-command entry point for
+  extension pack authoring, with routing metadata, installer profile coverage,
+  package payload checks, and front-door recipe coverage.
+- Added code-intelligence host capability detection for optional `ast-grep`,
+  `sg`, and LSP tooling without downgrading baseline host guarantees when those
+  tools are absent.
+- Added public starter-path regression checks that verify README and Quick
+  Proof goal labels resolve through shipped `/god` recipes and routes.
+
+### Changed
+- Updated public surface counts to 112 slash commands and 42 intent recipes
+  across release notes, reference docs, architecture maps, package metadata,
+  and project Pillars.
+- Tightened public front-door recipe matching for starter phrases including
+  "start a product", "add a feature", "fix production", "maintain health",
+  "audit an existing repo", "ship a release", and extension authoring.
+- Aligned the brownfield onboarding recipe to audit reconstructed artifacts
+  before tech-debt prioritization.
+
+### Fixed
+- Prevented maintainer-repository documentation drift from leaking into normal
+  user project dashboards.
+- Corrected Quick Proof output so fixture-backed checks render
+  `--project=.` for the user project path.
+- Hardened extension install, planning-system detection, and agent-cache cleanup
+  around symlinked directories that point outside the trusted source tree.
+- Removed phantom `god-*` examples from the extension scaffold skill prose so
+  agent-reference validation stays clean.
+
 ## [2.3.0] - 2026-05-30
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/aihxp/godpowers/actions/workflows/ci.yml/badge.svg)](https://github.com/aihxp/godpowers/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-2.3.0-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.4.0-blue)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/godpowers.svg)](https://www.npmjs.com/package/godpowers)
 
 **Ship fast. Ship right. Ship everything. Ship accountably.**
@@ -21,15 +21,13 @@ Godpowers makes AI coding accountable: every serious run should leave disk
 state, artifacts, validation gates, host guarantees, and a next action. Code is
 only one output. The project memory and proof trail matter too.
 
-Version 2.3.0 keeps the proof loop executable and adds accountability
-hardening. Build plans can now be checked against real repository files and
-symbols before execution, package-backed stack choices can be screened for
-legitimacy, core ledger writes use atomic persistence, installer profiles let
-teams choose a smaller command surface, and failed executor attempts leave a
-clear repair classification.
+Version 2.4.0 keeps every leaf command available while making the command
+surface easier to navigate. `/god`, `/god-help`, `/god-next`, and route
+metadata now share command families, decision ladders, typed route outcomes,
+and workflow helper groups so users see clearer paths without losing power.
 
-Maintainer hardening continues on the 2.x line without expanding the public
-command surface. The 2.1.0 patch closes a command-injection vector in the
+Maintainer hardening continues on the 2.x line with small, audited public
+surface updates when they close real workflow gaps. The 2.1.0 patch closes a command-injection vector in the
 agent-browser driver, guards runtime file parsing against corrupt state,
 makes data-directory installs a clean replace, and reconciles documentation
 drift. The 2.0.3 patch range-checks workflow agent references,
@@ -109,6 +107,16 @@ preserves the complete command surface, while the smaller profiles install the
 commands most relevant to the role. `--minimal` is an alias for
 `--profile=core`.
 
+Use profiles as journeys:
+
+| Journey | Profile |
+|---|---|
+| I want the basics | `core` |
+| I build products | `builder` |
+| I maintain Godpowers or mature repos | `maintainer` |
+| I coordinate suites | `suite` |
+| I want everything | `full` |
+
 Agent spawning is host-native. Claude uses its native agent/task interface,
 Codex uses installed `agents/*.toml` metadata backed by the same Markdown agent
 contracts, and the other runtimes use their supported agent or subagent
@@ -185,15 +193,19 @@ hook does the same thing when you open a new session in a Godpowers project.
 If the full command surface feels large, begin with one of these paths and only
 learn the next command when Godpowers recommends it.
 
+`/god-help` presents command families first: start, continue, build, verify,
+operate, maintain, capture, recover, extend, collaborate, and configure. Leaf
+commands remain direct shortcuts.
+
 | Goal | Starter path |
 |---|---|
-| Start a product | `/god-init`, `/god-prd`, `/god-design`, `/god-arch`, `/god-roadmap`, `/god-stack`, `/god-build` |
-| Add a feature | `/god-feature`, `/god-reconcile`, `/god-build`, `/god-review`, `/god-sync` |
-| Fix production | `/god-hotfix`, `/god-debug`, `/god-harden`, `/god-postmortem` |
-| Audit an existing repo | `/god-preflight`, `/god-audit`, `/god-archaeology`, `/god-tech-debt` |
-| Ship a release | `/god-status`, `/god-harden`, `/god-launch`, `npm run release:check` |
+| Start a product | `/god-init`, `/god-prd`, `/god-design`, `/god-arch`, `/god-roadmap`, `/god-stack`, `/god-repo`, `/god-build` |
+| Add a feature | `/god-reconcile`, `/god-feature`, `/god-sync`, `/god-review` |
+| Fix production | `/god-hotfix`, `/god-postmortem`, `/god-status` |
+| Audit an existing repo | `/god-preflight`, `/god-archaeology`, `/god-reconstruct`, `/god-audit`, `/god-tech-debt` |
+| Ship a release | `/god-sync`, `/god-docs`, `/god-version`, `/god-automation-setup`, `npm run release:check` |
 | Maintain project health | `/god-hygiene`, `/god-update-deps`, `/god-docs`, `/god-check-todos` |
-| Extend Godpowers | `/god-extension-add`, `/god-extension-list`, `npx godpowers extension-scaffold --name=@godpowers/my-pack --output=.` |
+| Extend Godpowers | `/god-extension-scaffold --name=@godpowers/my-pack --output=.`, `/god-test-extension`, `/god-extension-add`, `/god-extension-list` |
 
 The same status engine is available from the installer CLI for humans, CI,
 Codex, Claude, Cursor, Gemini, OpenCode, Windsurf, Antigravity, and any host
@@ -498,7 +510,7 @@ Pi. T3 Code inherits from the underlying agent (Codex / Claude / OpenCode).
 - [Getting Started](docs/getting-started.md)
 - [Quick Proof](docs/quick-proof.md)
 - [Concepts](docs/concepts.md)
-- [Command reference (all 111 skills + 40 agents)](docs/reference.md)
+- [Command reference (all 112 skills + 40 agents)](docs/reference.md)
 - [Feature awareness](docs/feature-awareness.md)
 - [Adoption Canary](docs/adoption-canary.md)
 - [Repository documentation sync](docs/repo-doc-sync.md)

package/RELEASE.md

@@ -1,51 +1,59 @@
-# Godpowers 2.3.0 Release
+# Godpowers 2.4.0 Release
 
-> Status: Ready for release
-> Date: 2026-05-30
+> Status: Ready for package verification
+> Date: 2026-06-08
 
-Godpowers 2.3.0 is an accountability-hardening release for the 2.x line. It
-keeps the public slash-command surface stable while strengthening planning
-grounding, package legitimacy, install profiles, atomic persistence, and
-executor recovery.
+Godpowers 2.4.0 is a UX flow consolidation release for the 2.x line. It keeps
+the complete 112-command surface intact while making the primary paths easier
+to understand through command families, decision ladders, typed route outcomes,
+and auditable workflow helper groups.
 
 ## What's in this release
 
-- 111 slash commands
+- 112 slash commands
 - 40 specialist agents
 - 13 executable workflows
-- 41 intent recipes
+- 42 intent recipes
 
 ## Highlights
 
-- Source-grounded planning records existing files, existing symbols, planned new
-  artifacts, and unchecked references before build execution.
-- Package legitimacy checks give stack and dependency decisions a concrete npm
-  evidence gate before recommending package-backed choices.
-- Installer profiles let users install a smaller role-based command surface
-  with `--profile=<name>` or `--minimal`.
-- Atomic write helpers now protect core state and ledger writes from partial
-  file updates.
-- Executor repair classification names whether a failed attempt should retry,
-  decompose, prune, or escalate.
-- Public migration language now uses neutral legacy-planning terminology so
-  Godpowers is not confused with external workflow products.
+- `/god-help` now presents command families first, then ladders and the full
+  catalog.
+- `/god` and `/god-next` now share command-family helpers for capture, work
+  sizing, verification, and overlapping trigger phrases.
+- `/god-status` is documented as the continue-family hub, with `/god-progress`,
+  `/god-lifecycle`, `/god-locate`, and `/god-next` as direct views.
+- Every shipped route now carries command family metadata.
+- Flexible route exits now carry typed `success-path.outcome` metadata so
+  contextual, verdict-based, steady-state, session-end, and selection outcomes
+  can be explained to users.
+- Workflow YAML can now use named helper groups, while generated plans still
+  expand the exact local helper list for visibility.
+- Recipes now split simple existing-repo onboarding from deeper inheritance
+  flows, and clarify workstream versus suite collaboration paths.
+- Extension journey docs now describe current extension-pack-required flows
+  instead of old release annotations.
+- Release guardrails now require the command-family runtime files, helper group
+  runtime files, and command-family regression test.
 
 ## Validation
 
 - `npm test` green across the full suite
-- `npm run lint` clean
-- `npm run release:check` green (tests, audit, package contents)
+- `npm run test:audit` green
+- `npm run pack:check` green
+- `npm pack` creates a local `godpowers-2.4.0.tgz` tarball for package
+  inspection
 
 ## Upgrade
 
-- `npm install -g godpowers@2.3.0` or `npx godpowers@2.3.0`
+- `npm install -g godpowers@2.4.0` or `npx godpowers@2.4.0`
 - Re-run `/god-context` in each project to refresh installed runtime metadata
 - No breaking changes; existing `.godpowers/` state is compatible. Users who
   want a compact install can run `npx godpowers --profile=core`.
 
 ## Notes
 
-- GitHub release creation for `v2.3.0`
+- GitHub release creation for `v2.4.0`
 - The tag should match the npm package version
-- The `v2.3.0` tag should point to the release commit that matches the npm
-  `godpowers@2.3.0` package.
+- The `v2.4.0` tag should point to the release commit that matches the npm
+  `godpowers@2.4.0` package.

package/SKILL.md

@@ -198,7 +198,30 @@ When the command only recommends work, keep the same dashboard but set
 command pauses, set `State: blocked` or `State: paused` and make `Next` the
 one exact user decision needed to continue.
 
-### 11. User-Facing Vocabulary
+### 11. Command Family UX
+Godpowers has many leaf commands, but user-facing routing should start from
+families. Keep the full command surface available while presenting these
+families first:
+
+- Start: start or import a project.
+- Continue: understand state and choose the next move.
+- Build: plan, implement, test, and ship product work.
+- Verify: check artifacts, code, runtime behavior, and release readiness.
+- Operate: deploy, observe, harden, launch, and respond in production.
+- Maintain: keep artifacts, docs, dependencies, context, and repo surfaces current.
+- Capture: save thoughts, tasks, backlog items, seeds, and learnings.
+- Recover: undo, repair, restore, skip, or diagnose broken state.
+- Extend: install, inspect, test, remove, or author extension packs.
+- Collaborate: coordinate people, workstreams, suites, sprints, and pull requests.
+- Configure: tune settings, budgets, cache, profiles, help, and version info.
+
+When choosing between similar commands, use the ladders from
+`lib/command-families.js`: capture ladder, work size ladder, verification
+ladder, status views, and trigger precedence. `/god-help` should render
+families before leaf commands, and `/god` should use the family helpers before
+asking the user to choose from a long list.
+
+### 12. User-Facing Vocabulary
 Godpowers may use internal words such as "arc" in routing, recipes, and agent
 implementation notes. Do not require the user to decode that word in visible
 output.
@@ -218,7 +241,7 @@ and roadmap visibility when those files exist or are expected. Show whether
 the PRD is done, whether the roadmap exists, which milestone or tier is active,
 how close the tracked workflow is to completion, and the next concrete move.
 
-### 12. Auto-Invoke Visibility
+### 13. Auto-Invoke Visibility
 When Godpowers automatically runs another command, agent, or local runtime
 helper, show the user what happened. Do not describe these as "background"
 unless they are truly detached from the current run. Most Godpowers sync work
@@ -271,7 +294,7 @@ Automatic steps that especially need visible reporting:
 - dogfood runner execution during `/god-dogfood`, release checks, or explicit
   dogfood requests
 
-### 13. Proactive Auto-Invoke Policy
+### 14. Proactive Auto-Invoke Policy
 Godpowers should be proactive from disk evidence, not from guesswork. Before
 auto-invoking anything, classify the action by risk and apply the safest
 allowed behavior.

package/agents/god-debugger.md

@@ -1,8 +1,9 @@
 ---
 name: god-debugger
 description: |
-  Systematic 4-phase debugger: Observe, Hypothesize, Test, Conclude. No
-  guess-and-check. Evidence-driven root cause analysis with regression tests.
+  Systematic debugger: Observe, Minimize, Instrument, Hypothesize, Test,
+  Conclude. No guess-and-check. Evidence-driven root cause analysis with
+  regression tests.
 
   Spawned by: /god-debug, when build encounters failures
 tools: Read, Edit, Bash, Grep, Glob, WebSearch
@@ -22,10 +23,44 @@ Gather evidence before forming any hypothesis:
 - Can you reproduce it RELIABLY? (if not, find a reliable repro first)
 - All error messages, stack traces, logs (full text, not paraphrased)
 - What is NOT happening that should be? (sometimes the silence is the clue)
+- When available, use `ast-grep`, `sg`, or LSP diagnostics/references to
+  narrow impacted symbols before forming a hypothesis.
 
 Output an observation document. Don't proceed until observations are complete.
 
-## Phase 2: Hypothesize
+## Phase 2: Minimize
+
+Reduce the failure to the smallest reliable reproduction before proposing a
+root cause:
+
+- Remove unrelated inputs, branches, services, files, data, and timing from the
+  reproduction while keeping the failure present.
+- Identify the smallest command, test, request, or user flow that still fails.
+- Record the exact boundary where removing one more thing makes the failure
+  disappear.
+- If minimization is impossible, record why and name the remaining broad
+  dependency that keeps the repro large.
+
+Do not proceed until the minimized reproduction is clear enough that another
+agent could rerun it without guessing.
+
+## Phase 3: Instrument
+
+Add or use focused evidence probes before forming a hypothesis:
+
+- Prefer existing logs, traces, diagnostics, failing assertions, and debugger
+  output when they already expose the state transition.
+- Add temporary probes only when they answer a specific question, then remove
+  them before the final fix unless they become a useful permanent test or log.
+- Instrument the boundary between expected and actual behavior, not every
+  nearby function.
+- Capture the observed values and the point where reality diverges from the
+  expected path.
+
+Do not proceed until the instrumentation either narrows the failure boundary or
+proves that more observation is needed.
+
+## Phase 4: Hypothesize
 
 Based on observations, list 2-3 most likely root causes:
 
@@ -35,7 +70,7 @@ For each hypothesis:
 - What evidence would REFUTE this hypothesis?
 - Rank by probability (1-10) with rationale
 
-## Phase 3: Test
+## Phase 5: Test
 
 Take the highest-probability hypothesis. Design a SPECIFIC test:
 - The test should produce different evidence depending on which hypothesis is true
@@ -43,11 +78,12 @@ Take the highest-probability hypothesis. Design a SPECIFIC test:
 - Record the evidence
 - Compare to predicted outcomes
 
-If hypothesis confirmed: proceed to Phase 4.
+If hypothesis confirmed: proceed to Phase 6.
 If hypothesis refuted: cross it off, move to next hypothesis.
-If all hypotheses refuted: return to Phase 1, expand observation scope.
+If all hypotheses refuted: return to Phase 1, then revisit minimization and
+instrumentation with the new evidence.
 
-## Phase 4: Conclude (Fix and Verify)
+## Phase 6: Conclude (Fix and Verify)
 
 1. **Write the regression test FIRST**
    - The test should reproduce the bug
@@ -74,4 +110,4 @@ If all hypotheses refuted: return to Phase 1, expand observation scope.
 - **Never apply multiple fixes at once** (can't tell which one worked)
 - **Always write the regression test first** (locks in the contract)
 - **If the bug is in a dependency**: document the workaround, file upstream, link in commit
-- **Time-boxing**: if Phase 1-3 takes >2 hours with no progress, ask for help (the observations are likely incomplete)
+- **Time-boxing**: if Phase 1-5 takes >2 hours with no progress, ask for help (the observations are likely incomplete)

package/agents/god-executor.md

@@ -96,6 +96,34 @@ Every changed line must trace back to that contract, the failing test, or a
 cleanup created by your own change. If you cannot explain the trace, revert
 that line before returning control to the orchestrator.
 
+## Optional Style Profile
+
+If `CODEDNA.md` exists at the project root or appears in the provided context
+loadout, read it before editing:
+- Match the repo's naming, file organization, comment density, extraction
+  threshold, error handling style, and test idioms when they do not conflict
+  with the slice plan.
+- Treat formatter, linter, tests, and explicit project conventions as
+  higher-priority evidence when they conflict with the profile.
+- Do not invent or generate a `CODEDNA.md` profile in executor scope.
+- If no profile exists, continue by matching the surrounding code directly.
+- Preserve required `// Implements: P-...` annotations even when the profile
+  prefers fewer comments.
+
+## Optional Code Intelligence
+
+When host capabilities or local probing report `ast-grep`, `sg`, or LSP tools:
+- Use `ast-grep` or `sg` for structural search before broad text rewrites.
+- Use LSP diagnostics, definitions, references, or rename support when the
+  host exposes them for the touched language.
+- Treat these tools as evidence helpers, not authority. Tests, source
+  grounding, and request trace still decide whether the slice is complete.
+- Record the tool only when it shaped file selection, rewrite scope, or a
+  repair decision.
+
+If optional code intelligence is unavailable, continue with Grep, Glob, and
+Bash evidence. Absence of these tools is not a blocker.
+
 ## After All Behaviors Complete
 
 1. Run the full test suite. All tests must pass.

package/agents/god-quality-reviewer.md

@@ -63,6 +63,26 @@ Your job: would you ship this code in production?
 - Flag missing or inaccurate annotations: the deliverable ledger derives
   requirement status from them, so a gap here understates delivered work
 
+### 8. Comment Quality and Style Fidelity
+- Required traceability comments such as `// Implements: P-...` remain present
+  and accurate.
+- Comments explain non-obvious why, constraints, hazards, or tradeoffs. Flag
+  comments that narrate obvious code, duplicate names, go stale, or use generic
+  AI-assistant prose.
+- Avoid decorative section banners or chatty explanation unless the surrounding
+  codebase already uses that convention.
+- If `CODEDNA.md` exists, compare naming, comment voice, extraction threshold,
+  error style, test style, and common idioms against the profile.
+- Absence of `CODEDNA.md` is not a failure. When no profile exists, judge style
+  against nearby code and repository conventions.
+
+### 9. Optional Code Intelligence
+- When `ast-grep`, `sg`, or LSP tools are available, use them to support
+  maintainability review for structural matches, impacted references, or
+  diagnostics that plain grep can miss.
+- Absence of these tools is not a failure. Treat them as extra evidence when
+  present.
+
 ## Output
 
 Return verdict to orchestrator:
@@ -78,6 +98,8 @@ Return verdict to orchestrator:
 - [PASS/FAIL] Maintainability: [evidence]
 - [PASS/FAIL] Simplicity and surgicality: [evidence]
 - [PASS/FAIL] Requirement traceability: [evidence]
+- [PASS/FAIL] Comment quality and style fidelity: [evidence]
+- [PASS/FAIL] Optional code intelligence: [evidence or not applicable]
 
 ### Verdict: PASS / FAIL
 
@@ -86,7 +108,7 @@ Return verdict to orchestrator:
 
 ## Pass Criteria
 
-ALL seven dimensions must PASS. Any FAIL blocks the commit.
+ALL nine dimensions must PASS. Any FAIL blocks the commit.
 
 If FAIL: orchestrator returns the slice to god-executor.
 If PASS: orchestrator commits the slice atomically.

package/agents/god-spec-reviewer.md

@@ -65,6 +65,12 @@ Answer each with EVIDENCE from the code:
    - If the slice added a dependency, is there package legitimacy evidence or
      an explicit accepted-risk note?
 
+8. **Did available code intelligence support the review?**
+   - If `ast-grep`, `sg`, or LSP tools are available, use them to verify
+     impacted references, structural matches, or diagnostics for the touched
+     language when relevant.
+   - If unavailable or irrelevant, do not fail the slice for absence alone.
+
 ## Output
 
 Return verdict to orchestrator:

package/bin/install.js

@@ -18,6 +18,7 @@ const {
   countInstalledSurface
 } = require('../lib/installer-core');
 const { describeProfiles } = require('../lib/install-profiles');
+const commandFamilies = require('../lib/command-families');
 const identity = require('../lib/package-identity');
 
 const VERSION = identity.PACKAGE_VERSION;
@@ -55,6 +56,11 @@ function showHelp() {
   log('  dogfood              Run built-in messy-repo dogfood scenarios');
   log('  extension-scaffold   Create a publishable extension pack skeleton');
   log('');
+  log('Command families:');
+  for (const family of commandFamilies.COMMAND_FAMILIES) {
+    log(`  ${family.id.padEnd(12)} ${family.purpose}`);
+  }
+  log('');
   log('Options:');
   log('  --project=<path>     Project root for status, next, proof, or automation commands');
   log('  --json               Emit JSON for status, next, proof, or automation commands');

package/lib/README.md

@@ -13,10 +13,11 @@ package-level integrations.
 | `intent.js` | Read and validate `intent.yaml` from project roots or `.godpowers/`. |
 | `checkpoint.js` | Create and inspect resumable checkpoint artifacts. |
 | `feature-awareness.js` | Detect and refresh existing-project awareness after runtime upgrades. |
-| `host-capabilities.js` | Detect host guarantees for shell, git, npm, agent spawning, extension authoring, and suite dry-runs. |
+| `code-intelligence.js` | Detect optional `ast-grep`, `sg`, and LSP tooling for structural search, rewrite, and diagnostics guidance. |
+| `host-capabilities.js` | Detect host guarantees for shell, git, npm, agent spawning, optional code intelligence, extension authoring, and suite dry-runs. |
 | `repo-doc-sync.js` | Detect and refresh mechanical repository documentation surfaces. |
 | `repo-surface-sync.js` | Detect structural drift across commands, routes, packages, agents, workflows, recipes, extensions, and release policy. |
-| `route-quality-sync.js` | Detect symbolic route spawns, unresolved agent targets, and unapproved contextual route exits. |
+| `route-quality-sync.js` | Detect symbolic route spawns, unresolved agent targets, and untyped contextual route exits. |
 | `recipe-coverage-sync.js` | Detect missing high-frequency intent recipe coverage. |
 | `release-surface-sync.js` | Detect release-facing drift across badges, release notes, changelog, package checks, and release checklist policy. |
 | `dogfood-runner.js` | Run deterministic messy-repo scenarios against migration, host, extension, and suite release behavior. |
@@ -40,9 +41,11 @@ package-level integrations.
 | Module | Purpose |
 |--------|---------|
 | `router.js` | Resolve user intent to skills, agents, recipes, and workflows. |
+| `command-families.js` | Define UX command families, status views, decision ladders, and trigger precedence helpers. |
 | `recipes.js` | Load and validate routing recipes. |
 | `workflow-parser.js` | Parse workflow YAML into executable steps. |
 | `workflow-runner.js` | Execute workflow steps with validation hooks. |
+| `workflow-helper-groups.js` | Expand named workflow helper groups into explicit local helper names for plan visibility. |
 | `agent-cache.js` | Cache agent metadata for faster routing. |
 | `agent-validator.js` | Validate agent frontmatter and contracts. |
 | `agent-refs.js` | Validate workflow agent references and scan skill/agent prose for phantom references. |

package/lib/agent-cache.js

@@ -134,9 +134,29 @@ function clear(projectRoot, opts = {}) {
   const now = Date.now();
   for (const shard of fs.readdirSync(dir)) {
     const shardPath = path.join(dir, shard);
-    if (!fs.statSync(shardPath).isDirectory()) continue;
+    const shardStat = fs.lstatSync(shardPath);
+    if (shardStat.isSymbolicLink()) {
+      if (opts.all) {
+        fs.unlinkSync(shardPath);
+        removed++;
+      } else {
+        kept++;
+      }
+      continue;
+    }
+    if (!shardStat.isDirectory()) continue;
     for (const fname of fs.readdirSync(shardPath)) {
       const fpath = path.join(shardPath, fname);
+      const fileStat = fs.lstatSync(fpath);
+      if (fileStat.isSymbolicLink()) {
+        if (opts.all) { fs.unlinkSync(fpath); removed++; }
+        else { kept++; }
+        continue;
+      }
+      if (!fileStat.isFile()) {
+        kept++;
+        continue;
+      }
       let entry;
       try { entry = JSON.parse(fs.readFileSync(fpath, 'utf8')); }
       catch (e) {
@@ -173,10 +193,12 @@ function stats(projectRoot) {
   let oldestTs = null;
   for (const shard of fs.readdirSync(dir)) {
     const shardPath = path.join(dir, shard);
-    if (!fs.statSync(shardPath).isDirectory()) continue;
+    const shardStat = fs.lstatSync(shardPath);
+    if (shardStat.isSymbolicLink() || !shardStat.isDirectory()) continue;
     for (const fname of fs.readdirSync(shardPath)) {
       const fpath = path.join(shardPath, fname);
-      const stat = fs.statSync(fpath);
+      const stat = fs.lstatSync(fpath);
+      if (stat.isSymbolicLink() || !stat.isFile()) continue;
       totalBytes += stat.size;
       count += 1;
       try {