all-hands-cli 0.1.4 → 0.1.6

package/.allhands/harness/src/commands/specs.ts

@@ -7,6 +7,7 @@
  * - ah specs list              - List all specs grouped by domain_name
  * - ah specs complete <name>   - Mark spec completed, move spec out of roadmap
  * - ah specs create <path>     - Create spec: validate, assign branch, commit and push
+ * - ah specs graph             - Render dependency graph with availability markers
  */
 
 import { Command } from 'commander';
@@ -349,6 +350,195 @@ export function register(program: Command): void {
       }
     });
 
+  // ah specs graph
+  specs
+    .command('graph')
+    .description('Render dependency graph showing spec relationships and availability')
+    .option('--json', 'Output as JSON')
+    .option('--roadmap', 'Only show roadmap/in-progress specs')
+    .action((options: { json?: boolean; roadmap?: boolean }) => {
+      const allSpecs = loadAllSpecGroups().flatMap((g) => g.specs);
+
+      if (allSpecs.length === 0) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: true, count: 0, available: [], tree: [], summary: { completed: 0, in_progress: 0, roadmap: 0, available: 0 } }, null, 2));
+        } else {
+          console.log('No specs found.');
+        }
+        return;
+      }
+
+      // Index all specs by id for lookups
+      const specById = new Map<string, typeof allSpecs[0]>();
+      for (const spec of allSpecs) {
+        specById.set(spec.id, spec);
+      }
+
+      // Compute availability: roadmap + all deps completed (against full unfiltered set)
+      // Dangling deps (unknown spec ids) are treated as satisfied
+      function isAvailable(spec: typeof allSpecs[0]): boolean {
+        if (spec.status !== 'roadmap') return false;
+        return spec.dependencies.every((depId) => {
+          const dep = specById.get(depId);
+          return !dep || dep.status === 'completed';
+        });
+      }
+
+      const availableIds = allSpecs.filter(isAvailable).map((s) => s.id).sort();
+
+      // Build display set (filtered or full)
+      let displaySpecs = allSpecs;
+      if (options.roadmap) {
+        displaySpecs = allSpecs.filter((s) => s.status !== 'completed');
+        if (displaySpecs.length === 0) {
+          if (options.json) {
+            console.log(JSON.stringify({ success: true, count: 0, available: availableIds, tree: [], summary: { completed: allSpecs.filter((s) => s.status === 'completed').length, in_progress: 0, roadmap: 0, available: availableIds.length } }, null, 2));
+          } else {
+            console.log('No roadmap specs found.');
+          }
+          return;
+        }
+      }
+
+      const displayIds = new Set(displaySpecs.map((s) => s.id));
+
+      // Build parent→children edges and find roots in one pass
+      const childrenOf = new Map<string, string[]>();
+      const roots: string[] = [];
+      for (const spec of displaySpecs) {
+        const visibleDeps = spec.dependencies.filter((depId) => depId !== spec.id && displayIds.has(depId));
+        if (visibleDeps.length === 0) {
+          roots.push(spec.id);
+        }
+        for (const depId of visibleDeps) {
+          if (!childrenOf.has(depId)) childrenOf.set(depId, []);
+          childrenOf.get(depId)!.push(spec.id);
+        }
+      }
+
+      // Detect orphaned cycles: specs not reachable from roots
+      const reachable = new Set<string>();
+      function markReachable(id: string): void {
+        if (reachable.has(id)) return;
+        reachable.add(id);
+        for (const childId of childrenOf.get(id) || []) {
+          markReachable(childId);
+        }
+      }
+      for (const rootId of roots) {
+        markReachable(rootId);
+      }
+      for (const spec of displaySpecs) {
+        if (!reachable.has(spec.id)) {
+          roots.push(spec.id);
+          markReachable(spec.id);
+        }
+      }
+
+      // Sort roots alphabetically
+      roots.sort();
+
+      // Summary counts
+      const summary = {
+        completed: displaySpecs.filter((s) => s.status === 'completed').length,
+        in_progress: displaySpecs.filter((s) => s.status === 'in_progress').length,
+        roadmap: displaySpecs.filter((s) => s.status === 'roadmap').length,
+        available: availableIds.length,
+      };
+
+      // JSON output
+      if (options.json) {
+        interface TreeNode {
+          id: string;
+          domain_name: string;
+          status: string;
+          available: boolean;
+          children: TreeNode[];
+        }
+
+        function buildJsonTree(id: string, path: Set<string>): TreeNode | null {
+          const spec = specById.get(id);
+          if (!spec) return null;
+          const node: TreeNode = {
+            id: spec.id,
+            domain_name: spec.domain_name,
+            status: spec.status,
+            available: availableIds.includes(spec.id),
+            children: [],
+          };
+          if (path.has(id)) return node; // cycle: return node without children
+          path.add(id);
+          const children = (childrenOf.get(id) || []).slice().sort();
+          for (const childId of children) {
+            const child = buildJsonTree(childId, path);
+            if (child) node.children.push(child);
+          }
+          path.delete(id);
+          return node;
+        }
+
+        const tree: TreeNode[] = [];
+        for (const rootId of roots) {
+          const node = buildJsonTree(rootId, new Set());
+          if (node) tree.push(node);
+        }
+
+        console.log(JSON.stringify({
+          success: true,
+          count: displaySpecs.length,
+          available: availableIds,
+          tree,
+          summary,
+        }, null, 2));
+        return;
+      }
+
+      // Human-readable tree output
+      const lines: string[] = [];
+      lines.push(`Dependency Tree (${displaySpecs.length} specs):\n`);
+
+      function statusIcon(status: string): string {
+        if (status === 'completed') return '[x]';
+        if (status === 'in_progress') return '[>]';
+        return '[ ]';
+      }
+
+      function renderNode(id: string, prefix: string, isLast: boolean, isRoot: boolean, pathSet: Set<string>): void {
+        const spec = specById.get(id);
+        if (!spec) return;
+
+        const connector = isRoot ? '' : isLast ? '└── ' : '├── ';
+        const icon = statusIcon(spec.status);
+        const avail = availableIds.includes(spec.id) ? ' ★' : '';
+
+        if (pathSet.has(id)) {
+          lines.push(`${prefix}${connector}${icon} ${spec.id} (${spec.domain_name}) [cycle]`);
+          return;
+        }
+
+        lines.push(`${prefix}${connector}${icon} ${spec.id} (${spec.domain_name})${avail}`);
+
+        const children = (childrenOf.get(id) || []).slice().sort();
+        if (children.length === 0) return;
+
+        pathSet.add(id);
+        const childPrefix = isRoot ? prefix : prefix + (isLast ? '    ' : '│   ');
+        for (let i = 0; i < children.length; i++) {
+          renderNode(children[i], childPrefix, i === children.length - 1, false, pathSet);
+        }
+        pathSet.delete(id);
+      }
+
+      for (const rootId of roots) {
+        renderNode(rootId, '', true, true, new Set());
+      }
+
+      lines.push('');
+      lines.push('Legend: [x] completed  [>] in_progress  [ ] roadmap  ★ available');
+
+      console.log(lines.join('\n'));
+    });
+
   // ah specs create <path>
   specs
     .command('create <path>')

package/.allhands/skills/harness-maintenance/references/validation-tooling.md

@@ -42,10 +42,19 @@ Per **Frontier Models are Capable** and **Context is Precious**:
 - **`--help` as prerequisite**: Suites MUST instruct agents to pull `<tool> --help` before any exploration — command vocabulary shapes exploration quality. The suite MUST NOT replicate full command docs.
 - **Inline command examples**: Weave brief examples into use-case motivations as calibration anchors — not exhaustive catalogs, not separated command reference sections.
 - **Motivation framing**: Frame around harness value: reducing human-in-loop supervision, verifying code quality, confirming implementation matches expectations.
-- **Exploration categories**: Describe with enough command specificity to orient, not prescriptive sequences that constrain.
+- **Exploration categories**: Describe with enough command specificity to orient. For untested territory, prefer motivations over prescriptive sequences — the agent extrapolates better from goals than rigid steps. For patterns verified through testing, state them authoritatively (see below).
 
 Formula: **motivations backed by inline command examples + `--help` as prerequisite and progressive disclosure**. Commands woven into use cases give direction; `--help` reveals depth.
 
+### Proven vs Untested Guidance
+
+Validation suites should be grounded in hands-on testing against the actual repo, not theoretical instructions. The level of authority in how guidance is written depends on whether it has been verified:
+
+- **Proven patterns** (verified via the Tool Validation Phase): State authoritatively within use-case motivations — the pattern is established fact, not a suggestion. These override generic tool documentation when they conflict. Example: "`xctrace` requires `--device '<UDID>'` for simulator" is a hard requirement discovered through testing, stated directly alongside the motivation (why: `xctrace` can't find simulator processes without it). The motivation formula still applies — proven patterns are *authoritative examples within motivations*, not raw command catalogs.
+- **Untested edge cases** (not yet exercised in this repo): Define the **motivation** (what the agent should achieve and why) and reference **analogous solved examples** from proven patterns. Do NOT write prescriptive step-by-step instructions for scenarios that haven't been verified — unverified prescriptions can mislead the agent into rigid sequences that don't match reality. Instead, trust that a frontier model given clear motivation and a reference example of how a similar problem was solved will extrapolate the correct approach through stochastic exploration.
+
+**Why this matters**: Frontier models produce emergent, adaptive behavior when given goals and reference points. Unverified prescriptive instructions constrain this emergence and risk encoding incorrect assumptions. Motivation + examples activate the model's reasoning about the problem space; rigid untested instructions bypass it. The Tool Validation Phase exists to convert untested guidance into proven patterns over time — the crystallization lifecycle in action.
+
 ### Evidence Capture
 
 Per **Quality Engineering**, two audiences require different artifacts:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "all-hands-cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Agentic harness for model-first software development",
   "type": "module",
   "bin": {