@fernado03/zoo-flow 0.5.2 → 0.7.0

package/examples/fix-flow.md

@@ -0,0 +1,139 @@
+# Example: `/fix` flow
+
+A worked example of the multi-phase `/fix` chain: orchestrator delegates
+to the architect, architect diagnoses, architect switches to the tweaker
+to implement, tweaker switches back, architect runs the post-mortem,
+tweaker prepares the commit. The whole flow has explicit HITL stops.
+
+## Setup
+
+- Active mode: `🪃 Custom Orchestrator`.
+- Workspace has a real bug to fix. For this example, assume:
+
+  > "The login button does nothing on the second click. First click
+  > works."
+
+## Phase 1 — orchestrator routes
+
+Type:
+
+```
+/fix The login button does nothing on the second click. First click works.
+```
+
+**Expected**
+
+Orchestrator looks up the routing matrix and delegates with `new_task`
+targeting `system-architect`. The delegated message includes the
+slash form, user context, proceed policy, command-protocol pointer,
+skills location, and the completion rule.
+
+## Phase 2 — architect diagnoses
+
+The new task window opens in `🏗️ System Architect`. The architect:
+
+1. Loads `/fix` per the command protocol.
+2. Runs the `diagnose` skill, phases 1–3.
+3. Produces a short list of hypotheses.
+4. **Halts** and asks you to pick one.
+
+**Expected message (paraphrased)**
+
+> Hypotheses:
+> 1. Click handler is wired once and never re-bound after a state change.
+> 2. The button enters a disabled state on first click and never resets.
+> 3. A queued network request is canceling the second click's handler.
+>
+> Which would you like to instrument? (1 / 2 / 3)
+
+You answer:
+
+```
+2
+```
+
+## Phase 3 — architect instruments
+
+The architect runs phase 4 of the `diagnose` skill on hypothesis 2.
+This phase may involve reading state-management code, adding a
+console-log or instrumentation suggestion (Markdown only — the architect
+cannot edit source), and producing a confirmed root cause.
+
+**Expected**
+
+> Root cause confirmed: `LoginButton` sets `disabled` on the first
+> click and the `onSuccess` handler does not reset it. The second
+> click is being absorbed by the disabled state.
+
+The architect summarizes the proposed fix and prepares to hand off.
+
+## Phase 4 — architect switches to tweaker
+
+The architect calls `switch_mode` to `code-tweaker` **inside the same
+task window** with a summary of:
+
+- The root cause.
+- The proposed fix (`onSuccess` resets `disabled`).
+- The files involved.
+- The tests to add or extend.
+
+The tweaker takes over without losing context.
+
+## Phase 5 — tweaker implements
+
+The tweaker:
+
+1. Edits the `LoginButton` component to reset `disabled` on success
+   and on error.
+2. Adds or extends tests covering the second-click case.
+3. Runs the test suite.
+4. Reports back.
+
+**HITL stop**: the tweaker does not commit. Per the git rule, it waits
+for your approval.
+
+## Phase 6 — back to architect for post-mortem
+
+The tweaker calls `switch_mode` back to `system-architect`. The
+architect runs phase 6 of `diagnose` (post-mortem):
+
+- What was the original assumption that masked the bug?
+- Is this an isolated mistake or a pattern?
+- If a pattern, would `/refactor` help?
+
+The architect produces a short post-mortem note in `docs/` or
+`.scratch/` (Markdown only) and either drops the matter there or
+suggests `/refactor`.
+
+## Phase 7 — tweaker prepares the commit
+
+The architect switches back to the tweaker. The tweaker suggests
+`/commit-and-document`. **The orchestrator does not auto-launch it.**
+That command runs only when you type it.
+
+## Phase 8 — return to orchestrator
+
+When the chain is complete (or blocked), the active mode calls
+`attempt_completion`. The orchestrator summarizes for you and halts.
+
+## Pass criteria
+
+- [ ] Orchestrator delegated to `system-architect`, not the tweaker.
+- [ ] Architect halted after phase 3 hypotheses, did not instrument
+      until you picked one.
+- [ ] Architect did not edit source code at any point.
+- [ ] Architect used `switch_mode` (same window) to hand off, not
+      `new_task`.
+- [ ] Tweaker did not run `git commit` or `git push` without your
+      explicit approval.
+- [ ] After return, orchestrator halted instead of auto-launching
+      `/commit-and-document`.
+
+## Common slips
+
+- Architect tries to edit source: see
+  [`docs/troubleshooting.md`](../docs/troubleshooting.md#architect-trying-to-edit-source).
+- Tweaker commits without approval: tighten the git rule in the
+  tweaker's `customInstructions`.
+- Orchestrator launches `/commit-and-document` automatically: see
+  [`docs/troubleshooting.md`](../docs/troubleshooting.md#slash-command-leakage-from-subtask-summaries).

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "@fernado03/zoo-flow",
   "description": "Workflow control plane for Zoo Code.",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "type": "module",
   "bin": {
     "zoo-flow": "bin/zoo-flow.js"
   },
   "files": [
     "bin",
+    "scripts",
     "templates",
+    "tests",
+    "docs",
+    "examples",
+    "quality",
     "README.md",
     "LICENSE"
-  ],
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -32,9 +37,15 @@
     "agent-workflows"
   ],
   "scripts": {
-    "check": "node bin/zoo-flow.js doctor --template-only",
-    "pack:check": "npm pack --dry-run"
-  },
+    "check": "node scripts/test-doctor.js && node bin/zoo-flow.js doctor --template-only && node scripts/eval-routing.js && node scripts/check-package-links.js",
+    "pack:check": "npm pack --dry-run",
+    "token-budget": "node scripts/token-budget.js",
+    "package-manifest": "node scripts/check-package-manifest.js",
+    "golden-transcripts": "node scripts/check-golden-transcripts.js",
+    "project-shapes": "node scripts/test-project-shapes.js",
+    "score-quality": "node scripts/score-quality.js",
+    "release:check": "npm run check && npm run token-budget && npm run package-manifest && npm run golden-transcripts && npm run project-shapes && npm run score-quality && npm run pack:check"
+  },
   "engines": {
     "node": ">=18"
   },

package/quality/scorecard.json

@@ -0,0 +1,88 @@
+{
+  "version": 1,
+  "minimum_score": 9.5,
+  "categories": {
+    "command_integrity": {
+      "weight": 0.20,
+      "checks": [
+        "All documented commands have mode declarations",
+        "All mode declarations match command-policy map",
+        "Global rules cover paths, protocol, failure, reply, context-economy",
+        "Mode rule folders exist for all three custom modes",
+        "Routing table matches command-policy map"
+      ],
+      "max_score": 10.0
+    },
+    "skill_quality": {
+      "weight": 0.20,
+      "checks": [
+        "Every command referencing a skill uses canonical Skill: marker",
+        "Referenced skills exist on disk",
+        "Skills describe purpose, steps, and output format",
+        "No thin non-canonical skill wrappers exist",
+        "Skills follow bucket layout under .roo/skills/"
+      ],
+      "max_score": 10.0
+    },
+    "validation_depth": {
+      "weight": 0.20,
+      "checks": [
+        "Doctor validates all required files exist",
+        "Doctor checks skill-reference integrity",
+        "Doctor checks mode slugs against allowed set",
+        "Doctor detects built-in delegation targets",
+        "Doctor checks .roomodes permits documented commands",
+        "Doctor validates routing table rows",
+        "Doctor detects old doc-name leakage",
+        "Doctor validates ADR path consistency"
+      ],
+      "max_score": 10.0
+    },
+    "token_economy": {
+      "weight": 0.10,
+      "checks": [
+        "Context-economy rule exists and is referenced",
+        "Domain-doc read gate defers broad reads",
+        "Completion rules specify evidence output format",
+        "Orchestrator routes by risk level to lightest safe workflow"
+      ],
+      "max_score": 10.0
+    },
+    "verification": {
+      "weight": 0.10,
+      "checks": [
+        "Verify command exists and references verify skill",
+        "Verify skill specifies evidence output format",
+        "Verify skill hard-codes no-claim-unless-run rule",
+        "Doctor fixture tests exist and pass",
+        "Routing eval cases exist and validate",
+        "Package-link integrity check exists"
+      ],
+      "max_score": 10.0
+    },
+    "review_process": {
+      "weight": 0.10,
+      "checks": [
+        "Review command exists and references review skill",
+        "Review skill covers standards and spec axes",
+        "Review skill has Security/Risk axis",
+        "Review findings ordered by severity",
+        "Review result ends with one of four canonical results"
+      ],
+      "max_score": 10.0
+    },
+    "release_readiness": {
+      "weight": 0.10,
+      "checks": [
+        "release:check script exists in package.json",
+        "release:check runs doctor, eval-routing, package-links",
+        "release:check runs package-manifest check",
+        "release:check runs token-budget check",
+        "release:check runs score-quality check",
+        "quality/scorecard.json defines minimum thresholds",
+        "npm pack --dry-run succeeds"
+      ],
+      "max_score": 10.0
+    }
+  }
+}

package/quality/token-budget.exceptions.json

@@ -0,0 +1,13 @@
+{
+  "_comment": "Token budget exceptions. Keys are relative file paths from project root. Values are reason + override size.",
+  "overrides": {
+    "compiled.md": {
+      "reason": "Single-file bundle doc, expected to be large",
+      "max_bytes": 819200
+    },
+    "ZOO-FLOW-BUNDLE.md": {
+      "reason": "Single-file bundle doc, expected to be large",
+      "max_bytes": 819200
+    }
+  }
+}

package/scripts/bundle.ps1

@@ -0,0 +1,135 @@
+<#
+.SYNOPSIS
+  Compile every git-tracked file in the repo into a single Markdown snapshot.
+
+.DESCRIPTION
+  Walks `git ls-files`, embeds each file under a heading with its repo-relative
+  path, and writes the result to ZOO-FLOW-BUNDLE.md at the repo root.
+
+  Binary files and files larger than -MaxBytes are skipped with a placeholder.
+  Files containing triple backticks get four-backtick fences automatically so
+  nested code blocks render correctly.
+
+  The output is local-only and gitignored.
+
+.PARAMETER OutFile
+  Output path. Defaults to ZOO-FLOW-BUNDLE.md at the repo root.
+
+.PARAMETER MaxBytes
+  Files larger than this are skipped with a placeholder. Default 200000.
+
+.EXAMPLE
+  pwsh ./scripts/bundle.ps1
+  pwsh ./scripts/bundle.ps1 -OutFile bundle.md -MaxBytes 500000
+#>
+
+[CmdletBinding()]
+param(
+  [string] $OutFile,
+  [int]    $MaxBytes = 200000
+)
+
+$ErrorActionPreference = "Stop"
+
+$repoRoot = (& git rev-parse --show-toplevel).Trim()
+if (-not $repoRoot) { throw "Not inside a git repository." }
+
+if (-not $OutFile) {
+  $OutFile = Join-Path $repoRoot "ZOO-FLOW-BUNDLE.md"
+}
+
+$files  = & git -C $repoRoot ls-files
+$commit = (& git -C $repoRoot rev-parse --short HEAD).Trim()
+$branch = (& git -C $repoRoot branch --show-current).Trim()
+
+$extLang = @{
+  ".md"        = "markdown"
+  ".js"        = "javascript"
+  ".mjs"       = "javascript"
+  ".cjs"       = "javascript"
+  ".ts"        = "typescript"
+  ".json"      = "json"
+  ".sh"        = "bash"
+  ".ps1"       = "powershell"
+  ".yml"       = "yaml"
+  ".yaml"      = "yaml"
+  ".toml"      = "toml"
+  ".html"      = "html"
+  ".css"       = "css"
+  ".gitignore" = "gitignore"
+  ".roomodes"  = "json"
+}
+
+function Test-IsBinary {
+  param([string] $Path)
+  try {
+    $bytes  = [IO.File]::ReadAllBytes($Path)
+    $sample = [Math]::Min($bytes.Length, 8000)
+    for ($i = 0; $i -lt $sample; $i++) {
+      if ($bytes[$i] -eq 0) { return $true }
+    }
+    return $false
+  } catch {
+    return $true
+  }
+}
+
+$sb = [System.Text.StringBuilder]::new()
+[void]$sb.AppendLine("# Zoo Flow Bundle")
+[void]$sb.AppendLine("")
+[void]$sb.AppendLine("Generated: $(Get-Date -Format 'yyyy-MM-dd HH:mm') from commit $commit on branch $branch.")
+[void]$sb.AppendLine("")
+[void]$sb.AppendLine("This is a flat snapshot of every tracked file in the repo. Each file is shown under its repo-relative path.")
+[void]$sb.AppendLine("")
+[void]$sb.AppendLine("---")
+[void]$sb.AppendLine("")
+
+$included = 0
+$skipped  = 0
+
+foreach ($rel in $files) {
+  $abs = Join-Path $repoRoot $rel
+  if (-not (Test-Path $abs -PathType Leaf)) { continue }
+
+  $size = (Get-Item $abs).Length
+  $ext  = [IO.Path]::GetExtension($rel)
+  if (-not $ext) { $ext = [IO.Path]::GetFileName($rel) }
+
+  $lang = $extLang[$ext.ToLower()]
+  if (-not $lang) { $lang = "text" }
+
+  [void]$sb.AppendLine("## ``$rel``")
+  [void]$sb.AppendLine("")
+
+  if ($size -gt $MaxBytes) {
+    [void]$sb.AppendLine("_Skipped: $size bytes (exceeds MaxBytes)._")
+    [void]$sb.AppendLine("")
+    $skipped++
+    continue
+  }
+
+  if (Test-IsBinary -Path $abs) {
+    [void]$sb.AppendLine("_Skipped: binary file ($size bytes)._")
+    [void]$sb.AppendLine("")
+    $skipped++
+    continue
+  }
+
+  $content = [IO.File]::ReadAllText($abs)
+  $fence   = '```'
+  if ($content -match '```') { $fence = '````' }
+
+  [void]$sb.AppendLine("$fence$lang")
+  [void]$sb.AppendLine($content.TrimEnd())
+  [void]$sb.AppendLine("$fence")
+  [void]$sb.AppendLine("")
+
+  $included++
+}
+
+[IO.File]::WriteAllText($OutFile, $sb.ToString())
+
+$bundleSize = (Get-Item $OutFile).Length
+Write-Host "wrote: $OutFile"
+Write-Host "size:  $bundleSize bytes"
+Write-Host "files: $($files.Count) total, $included included, $skipped skipped"

package/scripts/check-golden-transcripts.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+const transcriptDir = path.join(packageRoot, "tests", "golden-transcripts");
+
+const failures = [];
+
+if (!fs.existsSync(transcriptDir)) {
+  console.log("Golden transcript check skipped: no tests/golden-transcripts directory");
+  process.exit(0);
+}
+
+const entries = fs.readdirSync(transcriptDir);
+
+if (entries.length === 0) {
+  console.log("Golden transcript check skipped: empty tests/golden-transcripts directory");
+  process.exit(0);
+}
+
+for (const entry of entries) {
+  const fullPath = path.join(transcriptDir, entry);
+  if (fs.statSync(fullPath).isDirectory()) continue;
+  if (!entry.endsWith(".md") && !entry.endsWith(".jsonl")) continue;
+
+  const text = fs.readFileSync(fullPath, "utf8");
+
+  // Structural checks
+  if (!text.trim()) {
+    failures.push(`${entry}: empty transcript`);
+    continue;
+  }
+
+  if (entry.endsWith(".md")) {
+    if (!/^#\s/m.test(text)) {
+      failures.push(`${entry}: must have at least one heading`);
+    }
+  }
+
+  if (entry.endsWith(".jsonl")) {
+    const lines = text.split(/\r?\n/).filter(Boolean);
+    for (let idx = 0; idx < lines.length; idx += 1) {
+      try {
+        const parsed = JSON.parse(lines[idx]);
+        if (typeof parsed.name !== "string" || typeof parsed.user !== "string") {
+          failures.push(`${entry} line ${idx + 1}: missing name/user string fields`);
+        }
+      } catch (error) {
+        failures.push(`${entry} line ${idx + 1}: invalid JSON — ${error.message}`);
+      }
+    }
+  }
+}
+
+if (failures.length > 0) {
+  console.error("\nGolden transcript validation failed:\n");
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  console.error("");
+  process.exit(1);
+}
+
+console.log(`Golden transcript check passed: ${entries.length} files`);

package/scripts/check-package-links.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+const readmePath = path.join(packageRoot, "README.md");
+const packageJsonPath = path.join(packageRoot, "package.json");
+
+const failures = [];
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+const files = Array.isArray(packageJson.files) ? packageJson.files : [];
+const forbidden = [".git", "node_modules", ".scratch", ".zoo-flow-backup", "*.tgz"];
+
+for (const entry of files) {
+  if (forbidden.some((pattern) => pattern === entry || (pattern === "*.tgz" && entry.endsWith(".tgz")))) {
+    failures.push(`package.json files must not include ${entry}`);
+  }
+}
+
+function isExternalLink(target) {
+  return /^(https?:|mailto:|#)/i.test(target);
+}
+
+function isIncludedInPackage(targetPath) {
+  const normalized = targetPath.replace(/\\/g, "/").replace(/^\.\//, "");
+  const top = normalized.split("/")[0];
+  return files.includes(normalized) || files.includes(top);
+}
+
+const readme = fs.readFileSync(readmePath, "utf8");
+const linkRegex = /!??\[[^\]]*\]\(([^)]+)\)/g;
+let match;
+
+while ((match = linkRegex.exec(readme)) !== null) {
+  const rawTarget = match[1].trim();
+  const target = rawTarget.split(/\s+/)[0].replace(/^<|>$/g, "");
+  if (!target || isExternalLink(target)) continue;
+
+  const withoutAnchor = target.split("#")[0];
+  if (!withoutAnchor) continue;
+
+  const absolute = path.resolve(packageRoot, withoutAnchor);
+  if (!absolute.startsWith(packageRoot)) {
+    failures.push(`README link escapes package root: ${target}`);
+    continue;
+  }
+
+  if (!fs.existsSync(absolute)) {
+    failures.push(`README link target does not exist: ${target}`);
+    continue;
+  }
+
+  const relative = path.relative(packageRoot, absolute);
+  if (!isIncludedInPackage(relative)) {
+    failures.push(`README link target is excluded from package files: ${target}`);
+  }
+}
+
+if (failures.length > 0) {
+  console.error("\nPackage link validation failed:\n");
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  console.error("");
+  process.exit(1);
+}
+
+console.log("Package link validation passed: README local links are packaged");

package/scripts/check-package-manifest.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+
+const failures = [];
+const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+
+const expectedFiles = Array.isArray(pkg.files) ? pkg.files : [];
+const requiredEntries = [
+  "bin/zoo-flow.js",
+  "package.json",
+  "README.md",
+  "LICENSE"
+];
+
+// Run npm pack --dry-run and capture output
+const result = spawnSync("npm", ["pack", "--dry-run"], {
+  cwd: packageRoot,
+  encoding: "utf8",
+  shell: true
+});
+
+let packOutput = "";
+if (result.status !== 0) {
+  failures.push(`npm pack --dry-run failed: ${result.stderr}`);
+} else {
+  packOutput = `${result.stdout}\n${result.stderr}`;
+
+  // Check that required entries appear in the tarball listing
+  for (const entry of requiredEntries) {
+    if (!packOutput.includes(entry)) {
+      failures.push(`Required entry missing from npm pack: ${entry}`);
+    }
+  }
+
+  // Check that all declared files entries produce content
+  for (const entry of expectedFiles) {
+    const absPath = path.join(packageRoot, entry);
+    if (!fs.existsSync(absPath)) {
+      failures.push(`Declared file entry does not exist: ${entry}`);
+      continue;
+    }
+    const stat = fs.statSync(absPath);
+    if (stat.isDirectory()) {
+      // Check dir is non-empty
+      const contents = fs.readdirSync(absPath);
+      if (contents.length === 0) {
+        failures.push(`Declared file directory is empty: ${entry}`);
+      }
+    }
+  }
+}
+
+if (failures.length > 0) {
+  console.error("\nPackage manifest integrity check failed:\n");
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  console.error("");
+  process.exit(1);
+}
+
+console.log("Package manifest integrity check passed");