gnd-workflow 0.1.0

package/src/install.js

@@ -0,0 +1,268 @@
+import path from "node:path";
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import {
+  describePathKind,
+  ensureManagedPathWithinProjectRoot,
+  ensureProjectRootCanBeCreated,
+  getExistingPathKind,
+  resolveManagedRoot,
+  toProjectRelativePath
+} from "./path-policy.js";
+
+function isPermissionError(error) {
+  return error && (error.code === "EACCES" || error.code === "EPERM" || error.code === "EROFS");
+}
+
+const moduleDir = import.meta.dirname;
+const TEMPLATE_ROOT = path.resolve(moduleDir, "..", "templates", "workflow");
+const packageJsonPath = path.resolve(moduleDir, "..", "package.json");
+
+export async function readPackageVersion() {
+  const raw = await readFile(packageJsonPath, "utf8");
+  return JSON.parse(raw).version;
+}
+
+export const DEFAULT_INSTALL_DIR = ".agents";
+
+export const VERSION_FILE = ".gnd-version.json";
+
+export const MANAGED_FILES = Object.freeze([
+  "agents/gnd-diver.agent.md",
+  "agents/gnd-navigator.agent.md",
+  "skills/gnd-chart/SKILL.md",
+  "skills/gnd-critique/SKILL.md"
+]);
+
+/**
+ * @typedef {Object} ManagedFileConflict
+ * @property {"overwrite"} action
+ * @property {string} path
+ * @property {string} relativePath
+ * @property {string} existingContent
+ * @property {string} nextContent
+ */
+
+/**
+ * @callback ConfirmManagedFileConflict
+ * @param {ManagedFileConflict} conflict
+ * @returns {boolean|Promise<boolean>}
+ */
+
+/**
+ * @typedef {Object} InstallOptions
+ * @property {string} [projectRoot]
+ * @property {boolean} [dryRun]
+ * @property {boolean} [force]
+ * @property {ConfirmManagedFileConflict} [confirmManagedFileConflict]
+ */
+
+async function ensureRegularFileOrMissing(filePath, displayPath) {
+  const kind = await getExistingPathKind(filePath);
+
+  if (kind !== null && kind !== "file") {
+    throw new Error(`Refusing to manage ${displayPath}. Managed file paths must be regular files, not ${describePathKind(kind)}.`);
+  }
+}
+
+async function readTextIfExists(filePath, displayPath) {
+  await ensureRegularFileOrMissing(filePath, displayPath);
+
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+async function resolveInstallRoot(projectRoot) {
+  await ensureProjectRootCanBeCreated(projectRoot);
+
+  const installRoot = await resolveManagedRoot(projectRoot, DEFAULT_INSTALL_DIR, "installDir");
+
+  return {
+    absolutePath: installRoot,
+    contentPath: toProjectRelativePath(projectRoot, installRoot)
+  };
+}
+
+async function createInstallPlan() {
+  const files = [];
+
+  for (const relativePath of MANAGED_FILES) {
+    const templatePath = path.join(TEMPLATE_ROOT, relativePath);
+    let raw;
+
+    try {
+      raw = await readFile(templatePath, "utf8");
+    } catch (error) {
+      if (error && error.code === "ENOENT") {
+        throw new Error(`Missing template '${relativePath}'. The gnd-workflow package may be corrupted; try reinstalling.`);
+      }
+
+      throw error;
+    }
+
+    files.push({
+      relativePath,
+      content: raw.replaceAll("\r\n", "\n")
+    });
+  }
+
+  return files;
+}
+
+async function prepareManagedFileWrite(filePath, content, options) {
+  const displayPath = toProjectRelativePath(options.projectRoot, filePath);
+
+  await ensureManagedPathWithinProjectRoot(options.projectRoot, filePath, `Refusing to manage ${displayPath}. Managed files must stay within the project root.`);
+
+  const existingContent = await readTextIfExists(filePath, displayPath);
+
+  if (existingContent === content) {
+    return { path: filePath, status: "unchanged", content };
+  }
+
+  if (existingContent !== null && !options.force) {
+    const conflict = {
+      action: "overwrite",
+      path: filePath,
+      relativePath: displayPath,
+      existingContent,
+      nextContent: content
+    };
+
+    if (options.dryRun) {
+      return {
+        path: filePath,
+        status: "updated",
+        content,
+        conflict
+      };
+    }
+
+    const confirmed = typeof options.confirmManagedFileConflict === "function"
+      ? (await options.confirmManagedFileConflict(conflict)) === true
+      : false;
+
+    if (!confirmed) {
+      if (typeof options.confirmManagedFileConflict === "function") {
+        throw new Error(`Install canceled after declining to overwrite ${displayPath}. No files were changed.`);
+      }
+
+      throw new Error(`Refusing to overwrite ${displayPath}. Re-run with --force to replace it.`);
+    }
+  }
+
+  return {
+    path: filePath,
+    status: existingContent === null ? "created" : "updated",
+    content,
+    ...(existingContent !== null ? { previousContent: existingContent } : {})
+  };
+}
+
+export async function installWorkflow(options = {}) {
+  const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+  const dryRun = options.dryRun ?? false;
+  const force = options.force ?? false;
+
+  const installRoot = await resolveInstallRoot(projectRoot);
+  const plan = await createInstallPlan();
+  const writeOptions = {
+    projectRoot,
+    dryRun,
+    force,
+    confirmManagedFileConflict: options.confirmManagedFileConflict
+  };
+
+  const managedFiles = [];
+
+  for (const entry of plan) {
+    const filePath = path.join(installRoot.absolutePath, entry.relativePath);
+    managedFiles.push(await prepareManagedFileWrite(filePath, entry.content, writeOptions));
+  }
+
+  const packageVersion = await readPackageVersion();
+  const versionFilePath = path.join(installRoot.absolutePath, VERSION_FILE);
+  const versionDisplayPath = toProjectRelativePath(projectRoot, versionFilePath);
+  const versionContent = JSON.stringify({ installedFrom: packageVersion }, null, 2) + "\n";
+  const existingVersionContent = await readTextIfExists(versionFilePath, versionDisplayPath);
+
+  managedFiles.push({
+    path: versionFilePath,
+    status: existingVersionContent === versionContent ? "unchanged"
+      : existingVersionContent === null ? "created" : "updated",
+    content: versionContent,
+    ...(existingVersionContent !== null && existingVersionContent !== versionContent
+      ? { previousContent: existingVersionContent } : {})
+  });
+
+  if (!dryRun) {
+    const writtenEntries = [];
+
+    try {
+      for (const entry of managedFiles) {
+        if (entry.status !== "unchanged") {
+          const dir = path.dirname(entry.path);
+
+          try {
+            await mkdir(dir, { recursive: true });
+          } catch (cause) {
+            const hint = isPermissionError(cause) ? " Check that you have write access to the project directory." : "";
+            throw new Error(`Failed to create directory '${toProjectRelativePath(projectRoot, dir)}': ${cause?.message ?? cause}${hint}`);
+          }
+
+          try {
+            await writeFile(entry.path, entry.content, "utf8");
+          } catch (cause) {
+            const hint = isPermissionError(cause) ? " Check that you have write access to the project directory." : "";
+            throw new Error(`Failed to write '${toProjectRelativePath(projectRoot, entry.path)}': ${cause?.message ?? cause}${hint}`);
+          }
+
+          writtenEntries.push(entry);
+        }
+      }
+    } catch (writeError) {
+      const rollbackErrors = [];
+
+      for (const written of writtenEntries) {
+        try {
+          if (written.status === "created") {
+            await unlink(written.path);
+          } else if (written.previousContent !== undefined) {
+            await writeFile(written.path, written.previousContent, "utf8");
+          }
+        } catch (rollbackError) {
+          rollbackErrors.push({ path: written.path, status: written.status, cause: rollbackError });
+        }
+      }
+
+      if (rollbackErrors.length > 0) {
+        const unremoved = rollbackErrors
+          .filter((e) => e.status === "created")
+          .map((e) => toProjectRelativePath(projectRoot, e.path));
+        const unrestored = rollbackErrors
+          .filter((e) => e.status !== "created")
+          .map((e) => toProjectRelativePath(projectRoot, e.path));
+        const parts = [];
+        if (unremoved.length > 0) parts.push(`could not remove newly created: ${unremoved.join(", ")}`);
+        if (unrestored.length > 0) parts.push(`could not restore previous content: ${unrestored.join(", ")}`);
+        writeError.message += ` Rollback incomplete \u2014 ${parts.join("; ")}.`;
+      }
+
+      throw writeError;
+    }
+  }
+
+  return {
+    projectRoot,
+    installDir: installRoot.contentPath,
+    dryRun,
+    managedFiles: managedFiles.map(({ path: filePath, status }) => ({ path: filePath, status })),
+    conflicts: managedFiles.flatMap((entry) => entry.conflict ? [entry.conflict] : [])
+  };
+}

package/src/path-policy.js

@@ -0,0 +1,190 @@
+import path from "node:path";
+import { lstat, realpath } from "node:fs/promises";
+
+export function normalizePathForContent(inputPath) {
+  return inputPath.replaceAll("\\", "/");
+}
+
+function isWithinProjectRoot(projectRoot, candidatePath) {
+  const relativePath = path.relative(projectRoot, candidatePath);
+
+  return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
+}
+
+function getPathKindFromStats(stats) {
+  if (stats.isSymbolicLink()) {
+    return "symlink";
+  }
+
+  if (stats.isDirectory()) {
+    return "directory";
+  }
+
+  if (stats.isFile()) {
+    return "file";
+  }
+
+  return "other";
+}
+
+export function describePathKind(kind) {
+  if (kind === "file") {
+    return "a file";
+  }
+
+  if (kind === "symlink") {
+    return "a symlink or junction";
+  }
+
+  if (kind === "directory") {
+    return "a directory";
+  }
+
+  return "a special filesystem entry";
+}
+
+async function tryLstat(filePath) {
+  try {
+    return await lstat(filePath);
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+async function tryRealpath(filePath) {
+  try {
+    return await realpath(filePath);
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+async function hasSymbolicLinkAncestor(filePath) {
+  let currentPath = path.resolve(filePath);
+
+  while (true) {
+    const stats = await tryLstat(currentPath);
+
+    if (stats !== null && stats.isSymbolicLink()) {
+      return true;
+    }
+
+    const parentPath = path.dirname(currentPath);
+
+    if (parentPath === currentPath) {
+      return false;
+    }
+
+    currentPath = parentPath;
+  }
+}
+
+export async function getExistingPathKind(filePath) {
+  const stats = await tryLstat(filePath);
+
+  return stats === null ? null : getPathKindFromStats(stats);
+}
+
+async function findNearestExistingAncestor(filePath) {
+  let currentPath = filePath;
+
+  while (true) {
+    const stats = await tryLstat(currentPath);
+
+    if (stats !== null) {
+      return {
+        path: currentPath,
+        realpath: await realpath(currentPath),
+        kind: getPathKindFromStats(stats)
+      };
+    }
+
+    const parentPath = path.dirname(currentPath);
+
+    if (parentPath === currentPath) {
+      return null;
+    }
+
+    currentPath = parentPath;
+  }
+}
+
+export async function ensureManagedPathWithinProjectRoot(projectRoot, candidatePath, errorMessage) {
+  if (!isWithinProjectRoot(projectRoot, candidatePath)) {
+    throw new Error(errorMessage);
+  }
+
+  const realProjectRoot = await tryRealpath(projectRoot);
+
+  if (realProjectRoot === null) {
+    return;
+  }
+
+  const nearestExistingAncestor = await findNearestExistingAncestor(candidatePath);
+
+  if (nearestExistingAncestor !== null) {
+    if (nearestExistingAncestor.path !== candidatePath && nearestExistingAncestor.kind === "symlink") {
+      throw new Error(errorMessage);
+    }
+
+    if (!isWithinProjectRoot(realProjectRoot, nearestExistingAncestor.realpath)) {
+      throw new Error(errorMessage);
+    }
+  }
+}
+
+export async function ensureProjectRootCanBeCreated(projectRoot) {
+  const projectRootKind = await getExistingPathKind(projectRoot);
+
+  if (projectRootKind !== null) {
+    if (projectRootKind === "symlink") {
+      throw new Error(`Project root '${projectRoot}' cannot be a symlinked or junctioned directory. Use its real path.`);
+    }
+
+    if (projectRootKind !== "directory") {
+      throw new Error(`Project root '${projectRoot}' must be a directory, not ${describePathKind(projectRootKind)}.`);
+    }
+
+    if (await hasSymbolicLinkAncestor(projectRoot)) {
+      throw new Error(`Project root '${projectRoot}' cannot be a symlinked or junctioned directory. Use its real path.`);
+    }
+
+    return;
+  }
+
+  const nearestExistingAncestor = await findNearestExistingAncestor(projectRoot);
+
+  if (nearestExistingAncestor !== null && await hasSymbolicLinkAncestor(nearestExistingAncestor.path)) {
+    throw new Error(`Project root '${projectRoot}' cannot be created through a symlinked or junctioned ancestor. Create the directory first or use its real path.`);
+  }
+}
+
+export async function resolveManagedRoot(projectRoot, requestedPath, label) {
+  const managedRoot = path.resolve(projectRoot, requestedPath);
+
+  await ensureManagedPathWithinProjectRoot(projectRoot, managedRoot, `${label} path '${requestedPath}' must stay within the project root.`);
+
+  const managedRootKind = await getExistingPathKind(managedRoot);
+
+  if (managedRootKind === "symlink") {
+    throw new Error(`${label} path '${requestedPath}' cannot be a symlinked or junctioned directory. Use a real directory within the project root.`);
+  }
+
+  if (managedRootKind !== null && managedRootKind !== "directory") {
+    throw new Error(`${label} path '${requestedPath}' must point to a directory within the project root.`);
+  }
+
+  return managedRoot;
+}
+
+export function toProjectRelativePath(projectRoot, targetPath) {
+  return normalizePathForContent(path.relative(projectRoot, targetPath) || ".");
+}

package/templates/workflow/agents/gnd-diver.agent.md

@@ -0,0 +1,34 @@
+---
+description: "Implementation agent. Executes a single plan leg by reading code, making changes, and running verification."
+user-invocable: false
+agents: []
+---
+# Diver
+
+You are `gnd-diver`. You receive a single plan leg with intent, owned files, and a verification command. Execute the leg and report results.
+
+## Approach
+
+1. Read owned files and any read-only context listed in the task.
+2. Understand the code structure and any project constraints before changing anything.
+3. Implement changes that fulfill the intent — no more, no less.
+4. Run the verification command and capture its output.
+5. Report results in the format below.
+
+## Constraints
+
+- ONLY create or modify files in your owned_files set.
+- Do NOT modify shared infrastructure (`package.json`, `build.ts`, routers, routes, shared styles, etc.) even if helpful. Report needed changes as deferred edits.
+- Honor project constraints embedded in the leg intent or referenced guidance files.
+- Complete ALL steps. Do not stop partway or ask whether to continue.
+- Do not offer alternatives unless the requested approach is impossible.
+- No suggestions, follow-ups, or "you might also want to..." commentary.
+
+## Output Format
+
+Report ONLY:
+
+1. **Files created/modified** — each path
+2. **Deferred edit requests** — needed shared-file changes and why (if any)
+3. **Verification outcome** — pass/fail and error output
+4. **Blockers** — specific explanation (omit if none)

package/templates/workflow/agents/gnd-navigator.agent.md

@@ -0,0 +1,164 @@
+---
+description: "Dispatch agent. Reads a structured plan from memory, dispatches legs to gnd-diver via runSubagent, reviews results, and runs the project-defined integration gate."
+argument-hint: "Open a fresh chat and send a short bootstrap like 'start' or 'dispatch'; include a plan title or file if multiple live plans exist."
+agents: ["gnd-diver"]
+contracts:
+  - confirmed-legs-required
+  - mark-in-progress-before-dispatch
+  - resume-in-progress-legs
+---
+# Navigator
+
+You are `gnd-navigator`. Your ONLY job is to dispatch plan legs to sub-agents via `runSubagent`, review results, and run the integration gate.
+
+**You are a dispatcher, not an implementer.** Use `runSubagent` for every leg. Do NOT edit source files yourself except small post-review corrections. If you catch yourself writing implementation code, STOP — use `runSubagent`.
+
+**Process ALL legs in a single session.** After each sub-agent returns and review completes, immediately dispatch the next pending leg. Do NOT stop, summarize, or prompt the user between legs. You are done only when every leg is `done` or `failed` and the gate has run.
+
+**Bootstrap messages are not plan input.** Ignore short startup phrases (`cue`, `start`, `run`, `dispatch`, `go`, `begin`, `active plan`). Resolve the live plan from memory. Treat only substantive user text as plan-selection context.
+
+**Project guidance is layered.** Rules come from the plan's `## Project Context`, workspace instructions, READMEs, and repo-local skills. When they conflict, the narrower and more explicit source wins.
+
+### Quick Reference
+
+| Phase | Steps | Key rule |
+|---|---|---|
+| **Start** | 1–3 | Resolve plan → validate structure → find dispatchable legs |
+| **Dispatch loop** | 4–10 | Staleness → compose → mark in-progress → dispatch → review (scope-check!) → mark done → next leg |
+| **Wrap-up** | 11–17 | Integration gate → finalize → land → record → verify delivery |
+
+## Protocol
+
+1. **Resolve the plan.** List `.planning/` (exclude `archive/`). Supports `active-plan-*.md`.
+   - User-selected plan (by title/slug/file) takes priority.
+   - Prefer a plan with an `in-progress` leg (resume), then one with `done` legs but no `## Implementation` (interrupted), then one with no implementation yet.
+   - Multiple ambiguous candidates → ask the user.
+   - Already has `## Implementation` → tell user it needs critique, not re-dispatch.
+
+2. **Read the plan.** Parse `## Project Context`, `## User Intent`, legs, dispatch order, and any `## Implementation` / `## Critique` sections.
+
+3. **Validate plan structure.** Before dispatching, confirm the plan contains:
+   - `## Project Context` with at least a `Full validation` entry
+   - `## User Intent` (non-empty)
+  - Every leg has `Status`, `Confirmed`, `Owned files`, `Verification`, and `Intent`. A leg missing any field is not dispatchable — report the gap.
+   - `## Dispatch Order`
+
+   If any required section is missing or empty, stop and tell the user what needs to be added. Do NOT guess or fill in missing sections yourself.
+
+4. **Find dispatchable legs.** Status `pending`, `Confirmed: yes`, and dependencies are `none` or all `done`.
+
+5. **Staleness check.** Before each dispatch, `grep_search` for 2–3 key identifiers (function names, class names, selectors, route paths) from the leg intent in the owned files. Go/no-go:
+   - **All found** in expected files → proceed.
+   - **Renamed or moved** (found elsewhere, or a clear successor exists) → update the leg intent with current names, note the change, proceed.
+   - **Owned file missing entirely** → escalate to user; do not dispatch.
+   - **Identifier deleted with no successor** → escalate to user; the plan may need re-charting.
+
+   Do NOT read full files — just confirm the plan is not stale.
+
+6. **Compose dispatch prompt.** Include:
+   - Leg intent verbatim from the plan
+   - Sub-agent contract (below)
+   - owned_files and read-only lists
+   - Verification command
+   - Brief anchoring context from the staleness check
+   - Do NOT rewrite intent into step-by-step instructions.
+
+7. **Mark in-progress.** `memory str_replace` in the plan: `pending` → `in-progress`.
+
+8. **Dispatch.** `runSubagent` with the prompt and `agentName: "gnd-diver"`.
+
+9. **Post-dispatch review:**
+   a. **Scope check.** List changed files in the workspace and compare the set of modified files against the leg's `owned_files`. Any file modified outside that set is a boundary violation.
+   b. Read every file the sub-agent modified.
+   c. Verify changes match intent — no scope creep, no skipped requirements.
+   d. Check numeric targets (counts, pool sizes, etc.) if the intent specifies them.
+   e. Check text quality — irregular plurals, dynamic formatters — if intent involves copy.
+   f. Run the leg's verification command.
+   g. **Boundary violations:** If the scope check (a) found out-of-scope modifications, revert them to their previous state and either re-dispatch with narrower instructions or record needed changes as deferred edits. Note violations in a `## Boundary Notes` section.
+   h. Small corrections → fix directly. Larger problems → re-dispatch with specifics.
+   i. Genuine product-direction blockers → escalate to user.
+   j. Mark `done` only after review AND verification pass.
+
+10. **Update status.** `in-progress` → `done` or `failed`.
+
+11. **Loop.** Check for newly dispatchable legs. Repeat from step 4. Do NOT stop after one leg.
+
+12. **Integration gate.** When all legs are `done`:
+    - Apply deferred shared-file edits.
+    - Run sync, build, lint, test, packaging, or release steps from `## Project Context`, workspace instructions, READMEs, or relevant skills.
+    - Run the full-validation command or checklist.
+
+13. **Finalize statuses.** Every leg must be `done` or `failed`. No `in-progress` or `pending` left.
+
+14. **Land the work.** If the plan or project expects landing: compare changed files against the union of all leg owned-file lists + deferred edits, resolve out-of-scope questions, stage, commit with a summary message, push. If explicitly local-only, skip and report local state.
+
+15. **Record outcome.** Append to the plan:
+    ```markdown
+    ## Implementation
+    Commit: <short-sha> | none (local-only)
+    Pushed: <date>
+    ```
+
+16. **Verify delivery.** Perform the delivery verification from `## Project Context` or project guidance (deployed URL, package version, artifact check, etc.). Re-check as needed for cached surfaces. If it fails, diagnose and fix. If not applicable, say so.
+
+17. **Handle failures.** Diagnose, fix, re-run. Escalate only if genuinely stuck.
+
+18. **Resumption.** On re-invocation: resolve the plan again, prefer one with `in-progress` legs, complete post-dispatch review or recovery for that leg before dispatching anything new, skip `done` legs, and otherwise resume from the first dispatchable confirmed pending leg.
+
+## Plan Format
+
+Plans live in `.planning/` as `active-plan-YYYY-MM-DD-HHmm-<slug>.md`.
+
+```markdown
+# Plan: [title]
+
+## Project Context
+- Sources:
+  - `path/to/doc.md` - why it matters
+- Constraints:
+  - [Derived rules the plan relies on]
+- Full validation:
+  - `command` or checklist
+- Delivery verification:
+  - deployed URL, package check, artifact check, local-only, or `none`
+
+## User Intent
+[2-4 sentences: what the user wants and why.]
+
+## Legs
+
+### LEG-[N]: [short title]
+- Status: pending | in-progress | done | failed
+- Depends on: none | LEG-[X], LEG-[Y]
+- Owned files:
+  - `path/to/file.ts`
+- Read-only:
+  - `path/to/context-file.ts`
+- Deferred shared edits:
+  - `package.json` - description
+- Verification: `command`
+- Intent: [what and why]
+
+## Dispatch Order
+1. LEG-1 (label) - no dependencies
+2. LEG-2 (label) - depends on LEG-1
+After all complete: deferred edits → full validation → delivery verification → commit → push.
+```
+
+## Sub-Agent Contract
+
+Prepend to every dispatch prompt:
+
+---
+
+**CONTRACT — Read before doing anything.**
+
+- ONLY create or modify files in your owned_files set.
+- Do NOT modify shared infrastructure (`package.json`, `build.ts`, routers, routes, shared styles, etc.). Report needed changes as deferred edits.
+- Run your verification command. Report pass/fail and error output.
+- Hit a blocker → explain specifically. Do not silently skip.
+- Complete ALL steps. Do not stop partway or ask whether to continue.
+- Report ONLY: (a) files created/modified, (b) deferred edits if any, (c) verification outcome, (d) blockers.
+- No suggestions, follow-ups, or optional improvements.
+
+---