forgetrail 0.4.13 → 0.4.15

package/content/cursor-rules/url-host-matching.mdc

@@ -1,31 +1,30 @@
 ---
-description: Prefer hostMatchesDomain over hostname.includes for board/ATS URL checks
+description: Prefer exact domain/suffix matching over substring includes for URL checks and SSRF hygiene
 globs:
   - src/**/*.{ts,js}
-  - outpost/**/*.{js,mjs}
   - scripts/**/*.{js,mjs,ts}
 alwaysApply: false
 ---
 
-# URL host matching
+# URL host matching and SSRF hygiene
 
-## Prefer shared helpers
+## Domain and host checks
 
-- For board / ATS / “is this LinkedIn / Indeed / Greenhouse?” decisions, use **`hostMatchesDomain` / `urlMatchesHostDomain`** from `$lib/urlHost` (Outpost: `outpost/src/urlHost.js`, keep in sync).
-- **Do not** write `hostname.includes('linkedin.com')` or `url.includes('indeed.com')` for host allow/deny. Substring checks match lookalikes (`evil-linkedin.com`, `linkedin.com.attacker.example`) and trip CodeQL `js/incomplete-url-substring-sanitization`.
+- For external integration and host allow/deny decisions, use exact domain or suffix matching (`endsWith('.example.com')` or a shared helper like `hostMatchesDomain`).
+- **Do not** write `hostname.includes('example.com')` or `url.includes('example.com')` for host allow/deny. Substring checks match attacker lookalikes (`evil-example.com`, `example.com.attacker.net`) and trip CodeQL `js/incomplete-url-substring-sanitization`.
 
 ## Parse first
 
-- Prefer `new URL(...)` then match on **`hostname`**. Keep path checks on **`pathname`** (e.g. `/jobs/view`), not on the full href string when tightening.
+- Prefer `new URL(...)` then match on **`hostname`**. Keep path checks on **`pathname`** (e.g. `/api/v1`), not on the full href string.
 
-## Outgoing fetch
+## Outgoing fetch (SSRF hygiene)
 
-- App: `assertSafeUrl` at the boundary; follow redirects with re-check (`safeFetch`).
-- Outpost: `assertPublicHttpUrl` before slot acquisition / `goto`. Align blocked hosts (localhost, private IPs, `.local` / `.internal`, credentialed URLs).
+- Validate external URLs before slot acquisition or server-side fetch.
+- Disallow access to local and private network ranges: `localhost`, `127.0.0.1`, `::1`, RFC 1918 private IPs (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), `.local`, `.internal`, and credentials in URLs (`user:pass@host`).
+- Follow redirects with re-validation of each redirect target.
 
 ## Schemes and sanitization
 
 - Scheme checks: **allowlist** `http:` / `https:`; do not only deny `javascript:`.
-- Tag stripping / entity decode: use shared helpers (`stripMarkupTags`, amp-last entity decode) or a parser. If a regex is extraction-only, say so in a one-line comment.
-- GitHub Actions: always set top-level `permissions:` (least privilege).
-- Never return `err.stack` or raw exception text to HTTP clients; log server-side and return stable error codes.
+- Tag stripping / entity decode: use shared parser utilities. If a regex is extraction-only, annotate it in a comment.
+- Never return `err.stack` or raw exception text to external HTTP clients; log server-side and return stable error codes.

package/content/cursor-rules/user-facing-content.mdc

@@ -19,8 +19,8 @@ alwaysApply: true
 
 When describing what **the product does**, use direct verbs — not hedging **can**:
 
-- **Do:** “Resume Forge **strengthens** your file.” / “The Prospect Engine **suggests** matching roles.” / “Foreman **proposes** a run plan.”
-- **Don't:** “…**can strengthen**…” / “…**can suggest**…” when stating a shipped capability.
+- **Do:** “The pipeline **validates** each record.” / “The analyzer **identifies** bottlenecks.” / “The engine **generates** clean exports.”
+- **Don't:** “…**can validate**…” / “…**can identify**…” when stating a shipped capability.
 
 **Keep *can* when it means:**
 

package/content/cursor-rules/writing-voice.mdc

@@ -28,6 +28,12 @@ Fill the bracketed placeholders once brand voice crystallizes (usually after sev
 - **Ban vague nouns** in marketing and narrative copy: "something," "stuff," "things" (fine in error strings). Name the thing.
 - **Ban squish intensifiers:** "strongly," "deeply," "easily," "incredibly," "very." If the sentence needs the intensifier, rewrite the sentence.
 
+## Language and locale
+
+- Default to **US English** conventions unless context indicates otherwise.
+- **Adapt to the audience:** Adapt spelling and phrasing to what is discovered about the user, team, or target audience (e.g. Commonwealth/UK English when operating in those markets).
+- **No em dashes (—) in user-facing copy:** Use a colon, comma, period, or parentheses instead.
+
 ## Named-person constraints (narratives)
 
 If real people appear in origin/brand narratives, record their hard constraints here (employer safety, public roles, verb restrictions like "no founder verbs for X") and audit after every pass. Keep narrative locks in a constraints file next to the long-form (LOCKED FRAMING / ARC / VOICE pattern).

package/content/forgetrail-workspace-README.md

@@ -12,9 +12,9 @@ Used for **both** ForgeTrail Lite file bootstrap and **MCP greenfield** kickoff.
 | `FORGETRAIL_LITE.md` | Full Lite kickoff protocol (Lite file bootstrap only) |
 | `FORGETRAIL_LITE_UPDATES.md` | Optional local feedback log (§1.6) — merge accepted items upstream |
 | `AGENTS.md` | Agent instructions — cite or symlink for your IDE |
-| `CLAUDE.md` | Claude Code trailer override |
+| `CLAUDE.md` | Claude Code instructions |
 | `IDEAS.md` | Backlog parking lot |
-| `cursor/rules/*.mdc` | Cursor rule snippets (no-trailer, updates-log, …) |
+| `cursor/rules/*.mdc` | Cursor rule snippets (updates-log, …) |
 
 ## Wire up Cursor (one-time)
 
@@ -24,7 +24,6 @@ From the **repo root**:
 
 ```bash
 mkdir -p .cursor/rules
-ln -sf ../../.forgetrail/cursor/rules/forgetrail-no-trailer.mdc .cursor/rules/
 ln -sf ../../.forgetrail/cursor/rules/forgetrail-updates-log.mdc .cursor/rules/
 ```
 
@@ -32,7 +31,6 @@ ln -sf ../../.forgetrail/cursor/rules/forgetrail-updates-log.mdc .cursor/rules/
 
 ```bat
 mkdir .cursor\rules 2>nul
-mklink .cursor\rules\forgetrail-no-trailer.mdc ..\.forgetrail\cursor\rules\forgetrail-no-trailer.mdc
 mklink .cursor\rules\forgetrail-updates-log.mdc ..\.forgetrail\cursor\rules\forgetrail-updates-log.mdc
 ```
 

package/content/hooks/README.md

@@ -0,0 +1,36 @@
+# ForgeTrail Hooks
+
+Enforces ForgeTrail rules and guards at the host tool level, rather than relying only on prompt requests.
+
+## What is in this directory
+
+- `guard-shell.mjs`: runs pre-commit verification (`pnpm run verify`), prevents npm/yarn when `pnpm-lock.yaml` is present, gates `git push` to upstream remotes (pushing to IngotVault or local backup mirrors is allowed automatically), and prompts on destructive git or filesystem operations.
+- `guard-edit.mjs`: guards `.env*` secrets files and `specs/completed/**` or `specs/canonical/**` records against accidental mutation.
+- `session-start.mjs`: on session start, reads `.forgetrail/workflow_tracking.json` and injects live phase status, open exit criteria, and last session notes into agent context.
+- `validate-tracking.mjs`: after editing `workflow_tracking.json`, runs structural validation and returns any issues as context.
+- `validate-tracking-core.mjs`: standalone zero-dependency tracking validator.
+- `session-stop.mjs`: on session stop, checks that session notes were added to tracking.
+- `cursor-hooks.json`: standard Cursor hooks configuration.
+- `claude-settings-hooks.json`: standard Claude Code configuration fragment.
+
+## Host setup
+
+### Cursor
+
+Copy or link `cursor-hooks.json` to `.cursor/hooks.json` in your repository root. The hook scripts reside in `.forgetrail/hooks/`.
+
+### Claude Code
+
+Add the contents of `claude-settings-hooks.json` to `.claude/settings.json` in your project root or user configuration.
+
+## Verification
+
+Run any script with test input via stdin:
+
+```bash
+echo '{"command": "npm install lodash"}' | node .forgetrail/hooks/guard-shell.mjs
+# Output: {"permission":"deny", ...} (when pnpm-lock.yaml is present)
+
+echo '{"command": "git push"}' | node .forgetrail/hooks/guard-shell.mjs
+# Output: {"permission":"ask", ...}
+```

package/content/hooks/claude-settings-hooks.json

@@ -0,0 +1,20 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|shell",
+        "command": "node .forgetrail/hooks/guard-shell.mjs"
+      },
+      {
+        "matcher": "Write|Edit|StrReplace",
+        "command": "node .forgetrail/hooks/guard-edit.mjs"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|StrReplace",
+        "command": "node .forgetrail/hooks/validate-tracking.mjs"
+      }
+    ]
+  }
+}

package/content/hooks/cursor-hooks.json

@@ -0,0 +1,30 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": "node .forgetrail/hooks/guard-shell.mjs"
+      }
+    ],
+    "preToolUse": [
+      {
+        "command": "node .forgetrail/hooks/guard-edit.mjs"
+      }
+    ],
+    "sessionStart": [
+      {
+        "command": "node .forgetrail/hooks/session-start.mjs"
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "command": "node .forgetrail/hooks/validate-tracking.mjs"
+      }
+    ],
+    "stop": [
+      {
+        "command": "node .forgetrail/hooks/session-stop.mjs"
+      }
+    ]
+  }
+}

package/content/hooks/guard-edit.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+/**
+ * ForgeTrail Edit Guard
+ * Hook event: preToolUse (Cursor) / PreToolUse (Claude Code)
+ * Guards against accidental mutation of secrets (.env*) and completed/canonical specs.
+ */
+
+import { readFileSync } from "node:fs";
+
+function readStdin() {
+  try {
+    const raw = readFileSync(0, "utf-8");
+    if (raw.trim()) return JSON.parse(raw);
+  } catch {}
+  return {};
+}
+
+function extractTargetPaths(tool, input) {
+  if (!input) return [];
+  const paths = [];
+  if (typeof input.path === "string") paths.push(input.path);
+  if (typeof input.file_path === "string") paths.push(input.file_path);
+  if (typeof input.target_file === "string") paths.push(input.target_file);
+  return paths;
+}
+
+function main() {
+  const payload = readStdin();
+  const tool = payload.tool || payload.tool_name || "";
+  const input = payload.input || payload.tool_input || {};
+
+  // Only check write/edit tools
+  const isEditTool =
+    /^(Write|Edit|StrReplace|WriteFile|file_editor|edit_file)$/i.test(tool);
+
+  if (!isEditTool) {
+    console.log(JSON.stringify({ permission: "allow" }));
+    return;
+  }
+
+  const paths = extractTargetPaths(tool, input);
+
+  for (const path of paths) {
+    const normalized = path.replace(/\\/g, "/");
+
+    // 1. Guard environment secrets (.env, .env.local, etc. but allow .env.example)
+    if (/(^|\/)\.env(\.[a-zA-Z0-9_-]+)?$/.test(normalized)) {
+      if (!normalized.endsWith(".env.example")) {
+        console.log(
+          JSON.stringify({
+            permission: "ask",
+            user_message:
+              "ForgeTrail Safety: Modifying environment secrets file (" +
+              path +
+              "). Please confirm before proceeding.",
+            agent_message:
+              "Editing environment secrets file requires user confirmation.",
+          })
+        );
+        return;
+      }
+    }
+
+    // 2. Guard completed and canonical delivery specs
+    if (/(^|\/)specs\/(completed|canonical)\//.test(normalized)) {
+      console.log(
+        JSON.stringify({
+          permission: "ask",
+          user_message:
+            "ForgeTrail Safety: Completed delivery specs (" +
+            path +
+            ") are historical records. Modify only if intentionally updating links or summaries.",
+          agent_message:
+            "Editing completed/canonical spec requires user confirmation.",
+        })
+      );
+      return;
+    }
+  }
+
+  console.log(JSON.stringify({ permission: "allow" }));
+}
+
+main();

package/content/hooks/guard-shell.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+/**
+ * ForgeTrail Shell Guard
+ * Hook event: beforeShellExecution (Cursor) / PreToolUse (Claude Code)
+ * Enforces Lite §0, git commit attribution rules, pnpm consistency, and git push guards.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { execSync } from "node:child_process";
+
+function readStdin() {
+  try {
+    const raw = readFileSync(0, "utf-8");
+    if (raw.trim()) return JSON.parse(raw);
+  } catch {}
+  return {};
+}
+
+function hasPnpmLock(cwd) {
+  let curr = resolve(cwd || process.cwd());
+  for (let i = 0; i < 6; i++) {
+    if (existsSync(join(curr, "pnpm-lock.yaml"))) return true;
+    const parent = resolve(curr, "..");
+    if (parent === curr) break;
+    curr = parent;
+  }
+  return false;
+}
+
+function hasVerifyScript(cwd) {
+  try {
+    const pkgPath = join(cwd || process.cwd(), "package.json");
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      return Boolean(pkg.scripts && pkg.scripts.verify);
+    }
+  } catch {}
+  return false;
+}
+
+function main() {
+  const input = readStdin();
+  const command = (input.command || input.tool_input?.command || "").trim();
+  const cwd = input.cwd || process.cwd();
+
+  if (!command) {
+    console.log(JSON.stringify({ permission: "allow" }));
+    return;
+  }
+
+  // 1. Verify-before-commit: run whenever package.json has a verify script (unless skipped via FORGETRAIL_SKIP_VERIFY=1 or --no-verify)
+  if (/\bgit\s+commit\b/.test(command)) {
+    if (
+      process.env.FORGETRAIL_SKIP_VERIFY !== "1" &&
+      !/\s+--no-verify\b/.test(command) &&
+      hasVerifyScript(cwd)
+    ) {
+      try {
+        execSync("pnpm run verify", { cwd, stdio: "pipe" });
+      } catch (err) {
+        console.log(
+          JSON.stringify({
+            permission: "deny",
+            user_message:
+              "ForgeTrail Verification: 'pnpm run verify' failed. Code checks must pass before committing.",
+            agent_message:
+              "Pre-commit verification failed. Run pnpm verify and fix errors before committing.",
+          })
+        );
+        return;
+      }
+    }
+  }
+
+  // 2. Check for git push (Do not push to upstream remote unless explicitly requested by user)
+  if (/\bgit\s+push\b/.test(command)) {
+    if (/\s+(-f|--force|--force-with-lease)\b/.test(command)) {
+      console.log(
+        JSON.stringify({
+          permission: "ask",
+          user_message:
+            "ForgeTrail Safety: Force-pushing to remote can overwrite git history. Please confirm if you wish to proceed.",
+          agent_message:
+            "Force-push requires explicit user confirmation.",
+        })
+      );
+      return;
+    }
+
+    // Pushing to IngotVault or local backup mirrors is automatic to preserve work
+    const isIngotVaultOrBackup =
+      /\bgit\s+push\b.*?\b(backup|ingotvault)\b/i.test(command) ||
+      /\bgit\s+push\b.*?(?:[a-zA-Z]:[\\/]|file:\/\/|\.\/|\.\.\/)/i.test(command);
+
+    if (isIngotVaultOrBackup) {
+      console.log(JSON.stringify({ permission: "allow" }));
+      return;
+    }
+
+    console.log(
+      JSON.stringify({
+        permission: "ask",
+        user_message:
+          "ForgeTrail Safety: git push to upstream remote requires explicit user approval per project rules. Would you like to push?",
+        agent_message:
+          "git push to upstream remote requires explicit user approval per project rules.",
+      })
+    );
+    return;
+  }
+
+  // 3. Check for npm/yarn when pnpm-lock exists (Lite §0 Rule 3)
+  if (/\b(npm\s+(i|install|add)|yarn(\s+add|\s+install)?)\b/.test(command)) {
+    if (hasPnpmLock(cwd)) {
+      console.log(
+        JSON.stringify({
+          permission: "deny",
+          user_message:
+            "ForgeTrail Lite §0: This repository uses pnpm (pnpm-lock.yaml detected). Do not run npm or yarn install.",
+          agent_message:
+            "Package manager is locked to pnpm. Run pnpm instead.",
+        })
+      );
+      return;
+    }
+  }
+
+  // 4. Check for destructive git operations
+  if (/\bgit\s+(reset\s+--hard|clean\s+-[a-zA-Z]*f)/.test(command)) {
+    console.log(
+      JSON.stringify({
+        permission: "ask",
+        user_message:
+          "ForgeTrail Safety: Destructive git operation (" +
+          command +
+          ") will permanently discard uncommitted changes. Confirm?",
+        agent_message: "Destructive git operation requires user approval.",
+      })
+    );
+    return;
+  }
+
+  // 5. Check for dangerous rm -rf outside build/temp
+  if (/\brm\s+-[a-zA-Z]*r[a-zA-Z]*f?\s+/.test(command)) {
+    const isSafe =
+      /\b(temp|build|\.svelte-kit|\.turbo|dist|\.wrangler|node_modules)[/\\]?/.test(
+        command
+      );
+    if (!isSafe) {
+      console.log(
+        JSON.stringify({
+          permission: "ask",
+          user_message:
+            "ForgeTrail Safety: Recursive file deletion outside temporary/build directories. Confirm?",
+          agent_message:
+            "Dangerous recursive deletion requires user approval.",
+        })
+      );
+      return;
+    }
+  }
+
+  console.log(JSON.stringify({ permission: "allow" }));
+}
+
+main();

package/content/hooks/session-start.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+/**
+ * ForgeTrail Session Start Context Injector
+ * Hook event: sessionStart (Cursor)
+ * Injects live ForgeTrail phase status and open exit criteria into session context.
+ * Retires static phase-status rules on hosts with hook support.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+function findTrackingFile(startDir) {
+  let curr = resolve(startDir || process.cwd());
+  for (let i = 0; i < 6; i++) {
+    const candidate1 = join(curr, ".forgetrail", "workflow_tracking.json");
+    if (existsSync(candidate1)) return candidate1;
+    const candidate2 = join(curr, "workflow_tracking.json");
+    if (existsSync(candidate2)) return candidate2;
+    const parent = resolve(curr, "..");
+    if (parent === curr) break;
+    curr = parent;
+  }
+  return null;
+}
+
+function main() {
+  const trackingPath = findTrackingFile(process.cwd());
+
+  if (!trackingPath) {
+    console.log(JSON.stringify({}));
+    return;
+  }
+
+  try {
+    const tracking = JSON.parse(readFileSync(trackingPath, "utf-8"));
+    const projectName = tracking.project?.name || "App";
+    const phase = tracking.currentPhase || "1";
+    const isLite = tracking.schemaVersion === "lite-1";
+
+    let remaining = [];
+    if (isLite) {
+      const phaseObj = tracking.phases?.[String(phase)];
+      if (phaseObj?.exitCriteria) {
+        remaining = Object.entries(phaseObj.exitCriteria)
+          .filter(([_, met]) => !met)
+          .map(([flag]) => flag);
+      }
+    } else {
+      const phaseObj = tracking.phases?.[phase];
+      if (Array.isArray(phaseObj?.exitCriteriaRemaining)) {
+        remaining = phaseObj.exitCriteriaRemaining;
+      }
+    }
+
+    let lastLeftOff = "";
+    if (Array.isArray(tracking.sessions) && tracking.sessions.length > 0) {
+      const lastSession = tracking.sessions[tracking.sessions.length - 1];
+      lastLeftOff = lastSession.leftOff || lastSession.notes || "";
+    }
+
+    const lines = [
+      `=== ForgeTrail Context (${projectName}) ===`,
+      `Current Phase: ${phase} (${isLite ? "Lite schema" : "MCP schema"})`,
+    ];
+
+    if (lastLeftOff) {
+      lines.push(`Last Session Left Off: ${lastLeftOff}`);
+    }
+
+    if (remaining.length > 0) {
+      lines.push("Open Exit Criteria for Current Phase:");
+      for (const item of remaining.slice(0, 5)) {
+        lines.push(`  - ${item}`);
+      }
+      if (remaining.length > 5) {
+        lines.push(`  ...and ${remaining.length - 5} more`);
+      }
+    }
+
+    lines.push("========================================");
+
+    console.log(
+      JSON.stringify({
+        additional_context: lines.join("\n"),
+      })
+    );
+  } catch {
+    console.log(JSON.stringify({}));
+  }
+}
+
+main();

package/content/hooks/session-stop.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+/**
+ * ForgeTrail Session Stop Check
+ * Hook event: stop (Cursor)
+ * Prompts a reminder if a session concluded without updating sessions[] in tracking.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+function findTrackingFile(startDir) {
+  let curr = resolve(startDir || process.cwd());
+  for (let i = 0; i < 6; i++) {
+    const candidate1 = join(curr, ".forgetrail", "workflow_tracking.json");
+    if (existsSync(candidate1)) return candidate1;
+    const candidate2 = join(curr, "workflow_tracking.json");
+    if (existsSync(candidate2)) return candidate2;
+    const parent = resolve(curr, "..");
+    if (parent === curr) break;
+    curr = parent;
+  }
+  return null;
+}
+
+function main() {
+  const trackingPath = findTrackingFile(process.cwd());
+  if (!trackingPath) {
+    console.log(JSON.stringify({}));
+    return;
+  }
+
+  try {
+    const tracking = JSON.parse(readFileSync(trackingPath, "utf-8"));
+    const sessions = tracking.sessions;
+
+    const today = new Date().toISOString().slice(0, 10);
+    const hasTodaySession =
+      Array.isArray(sessions) &&
+      sessions.some((s) => s.date === today || (s.timestamp && s.timestamp.startsWith(today)));
+
+    if (!hasTodaySession) {
+      console.log(
+        JSON.stringify({
+          followup_message:
+            "ForgeTrail Reminder: Update .forgetrail/workflow_tracking.json (sessions[], decisions[], gotchas[]) with what was accomplished before ending.",
+        })
+      );
+      return;
+    }
+  } catch {}
+
+  console.log(JSON.stringify({}));
+}
+
+main();