forgetrail 0.4.13 → 0.4.15

package/content/hooks/validate-tracking-core.mjs

@@ -0,0 +1,229 @@
+/**
+ * Structural validation for .forgetrail/workflow_tracking.json (MCP full + Lite shapes).
+ * Standalone zero-dependency module for ForgeTrail hooks and MCP.
+ */
+
+const VALID_MCP_PHASES = [
+  "1-architecture",
+  "2-scaffolding",
+  "3-stabilization",
+  "4-feature-iteration",
+  "5-refactoring",
+  "6-strategic-review",
+  "7-hardening",
+];
+
+const VALID_LITE_PHASES = ["1", "2", "3", "4", "5", "6", "7"];
+
+const VALID_GOTCHA_CATEGORIES = new Set([
+  "environment",
+  "integration",
+  "data-model",
+  "ui",
+  "performance",
+  "ai-output",
+  "security",
+  "tooling",
+  "other",
+]);
+
+const VALID_DECISION_STATUS = new Set(["active", "superseded", "revisit"]);
+
+const VALID_PHASE_STATUS = new Set([
+  "not_started",
+  "pending",
+  "in_progress",
+  "completed",
+  "revisiting",
+]);
+
+function isLiteSchema(data) {
+  return data && data.schemaVersion === "lite-1";
+}
+
+export function validateTrackingData(data) {
+  const issues = [];
+  const warnings = [];
+
+  if (!data || typeof data !== "object") {
+    issues.push("Tracking data is empty or not an object.");
+    return { issues, warnings };
+  }
+
+  const project = data.project;
+  if (!project || typeof project !== "object") {
+    issues.push("Missing top-level project object.");
+  } else if (!project.name || typeof project.name !== "string" || !project.name.trim()) {
+    issues.push("project.name is missing or empty.");
+  }
+
+  if (!data.currentPhase) {
+    issues.push("Missing currentPhase.");
+  }
+
+  const lite = isLiteSchema(data);
+  const currentPhase = data.currentPhase;
+
+  if (currentPhase) {
+    if (lite) {
+      const phaseStr = String(currentPhase);
+      if (!VALID_LITE_PHASES.includes(phaseStr)) {
+        issues.push(
+          `Lite schema currentPhase "${phaseStr}" is not a valid phase number (1–7).`
+        );
+      }
+    } else if (
+      typeof currentPhase === "string" &&
+      !VALID_MCP_PHASES.includes(currentPhase)
+    ) {
+      issues.push(
+        `currentPhase "${currentPhase}" is not a recognized MCP phase id (e.g. "1-architecture").`
+      );
+    }
+  }
+
+  const phases = data.phases;
+  if (!phases || typeof phases !== "object") {
+    issues.push("Missing phases object.");
+    return { issues, warnings };
+  }
+
+  const phaseKeys = Object.keys(phases);
+  if (phaseKeys.length === 0) {
+    issues.push("No phases defined in tracking.");
+  }
+
+  if (!lite && currentPhase && typeof currentPhase === "string" && !phaseKeys.includes(currentPhase)) {
+    issues.push(`currentPhase "${currentPhase}" is not a key in phases.`);
+  }
+
+  for (const [key, rawPhase] of Object.entries(phases)) {
+    if (!rawPhase || typeof rawPhase !== "object") {
+      issues.push(`phases["${key}"] is not an object.`);
+      continue;
+    }
+    const phase = rawPhase;
+
+    if (phase.status && !VALID_PHASE_STATUS.has(String(phase.status))) {
+      warnings.push(
+        `phases["${key}"].status "${phase.status}" is not a standard value (not_started | in_progress | completed | revisiting).`
+      );
+    }
+
+    if (lite) {
+      if (phase.exitCriteria !== undefined && (typeof phase.exitCriteria !== "object" || phase.exitCriteria === null)) {
+        issues.push(`phases["${key}"].exitCriteria should be an object of boolean flags (Lite schema).`);
+      }
+    } else {
+      if (phase.exitCriteriaMet !== undefined && !Array.isArray(phase.exitCriteriaMet)) {
+        issues.push(`phases["${key}"].exitCriteriaMet should be an array.`);
+      }
+      if (phase.exitCriteriaRemaining !== undefined && !Array.isArray(phase.exitCriteriaRemaining)) {
+        issues.push(`phases["${key}"].exitCriteriaRemaining should be an array.`);
+      }
+      const met = phase.exitCriteriaMet ?? [];
+      const remaining = phase.exitCriteriaRemaining ?? [];
+      if (Array.isArray(met) && Array.isArray(remaining)) {
+        const overlap = met.filter((item) => remaining.includes(item));
+        if (overlap.length > 0) {
+          warnings.push(
+            `phases["${key}"] has exit criteria in both Met and Remaining: ${overlap.slice(0, 3).join("; ")}${overlap.length > 3 ? "…" : ""}`
+          );
+        }
+      }
+    }
+
+    const subagentRuns = phase.subagentRuns;
+    if (subagentRuns !== undefined && !Array.isArray(subagentRuns)) {
+      issues.push(`phases["${key}"].subagentRuns should be an array when present.`);
+    }
+  }
+
+  const decisions = data.decisions;
+  if (decisions !== undefined) {
+    if (!Array.isArray(decisions)) {
+      issues.push("decisions should be an array.");
+    } else {
+      const seenIds = new Set();
+      for (let i = 0; i < decisions.length; i++) {
+        const d = decisions[i];
+        if (!d || typeof d !== "object") {
+          issues.push(`decisions[${i}] is not an object.`);
+          continue;
+        }
+        if (!d.decision || typeof d.decision !== "string") {
+          issues.push(`decisions[${i}] missing decision text.`);
+        }
+        if (!d.rationale || typeof d.rationale !== "string") {
+          warnings.push(`decisions[${i}] missing rationale (recommended for Phase 1 handoff).`);
+        }
+        if (d.id && typeof d.id === "string") {
+          if (seenIds.has(d.id)) {
+            issues.push(`Duplicate decisions id "${d.id}".`);
+          }
+          seenIds.add(d.id);
+        }
+        if (d.status && !VALID_DECISION_STATUS.has(String(d.status))) {
+          warnings.push(`decisions[${i}].status "${d.status}" is not standard (active | superseded | revisit).`);
+        }
+        if (
+          d.alternatives_considered !== undefined &&
+          !Array.isArray(d.alternatives_considered)
+        ) {
+          warnings.push(`decisions[${i}].alternatives_considered should be an array when present.`);
+        }
+      }
+    }
+  }
+
+  const gotchas = data.gotchas;
+  if (gotchas !== undefined) {
+    if (!Array.isArray(gotchas)) {
+      issues.push("gotchas should be an array.");
+    } else {
+      for (let i = 0; i < gotchas.length; i++) {
+        const g = gotchas[i];
+        if (!g || typeof g !== "object") {
+          issues.push(`gotchas[${i}] is not an object.`);
+          continue;
+        }
+        if (!g.issue || typeof g.issue !== "string") {
+          warnings.push(`gotchas[${i}] missing issue description.`);
+        }
+        if (!g.resolution || typeof g.resolution !== "string") {
+          warnings.push(`gotchas[${i}] missing resolution.`);
+        }
+        if (g.category && !VALID_GOTCHA_CATEGORIES.has(String(g.category))) {
+          warnings.push(
+            `gotchas[${i}].category "${g.category}" is not a standard category (environment, integration, …).`
+          );
+        }
+      }
+    }
+  }
+
+  const sessions = data.sessions;
+  if (sessions !== undefined && !Array.isArray(sessions)) {
+    issues.push("sessions should be an array when present.");
+  }
+
+  return { issues, warnings };
+}
+
+export function formatValidationResult(result) {
+  const { issues, warnings } = result;
+
+  if (issues.length === 0 && warnings.length === 0) {
+    return "Tracking file looks structurally healthy.";
+  }
+
+  const parts = [];
+  if (issues.length > 0) {
+    parts.push("Issues (fix these):\n" + issues.map((i) => `- ${i}`).join("\n"));
+  }
+  if (warnings.length > 0) {
+    parts.push("Warnings:\n" + warnings.map((w) => `- ${w}`).join("\n"));
+  }
+
+  return parts.join("\n\n");
+}

package/content/hooks/validate-tracking.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+/**
+ * ForgeTrail Tracking Validator Hook
+ * Hook event: afterFileEdit (Cursor) / PostToolUse (Claude Code)
+ * Automatically validates .forgetrail/workflow_tracking.json upon edit.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { validateTrackingData, formatValidationResult } from "./validate-tracking-core.mjs";
+
+function readStdin() {
+  try {
+    const raw = readFileSync(0, "utf-8");
+    if (raw.trim()) return JSON.parse(raw);
+  } catch {}
+  return {};
+}
+
+function main() {
+  const payload = readStdin();
+  const filePath =
+    payload.path ||
+    payload.file_path ||
+    payload.target_file ||
+    payload.input?.path ||
+    payload.tool_input?.path ||
+    "";
+
+  if (!filePath.endsWith("workflow_tracking.json")) {
+    console.log(JSON.stringify({}));
+    return;
+  }
+
+  if (!existsSync(filePath)) {
+    console.log(JSON.stringify({}));
+    return;
+  }
+
+  try {
+    const content = JSON.parse(readFileSync(filePath, "utf-8"));
+    const result = validateTrackingData(content);
+
+    if (result.issues.length > 0 || result.warnings.length > 0) {
+      const formatted = formatValidationResult(result);
+      console.log(
+        JSON.stringify({
+          additional_context: `=== ForgeTrail Tracking Validation Notice ===\n${formatted}\n=============================================`,
+        })
+      );
+      return;
+    }
+  } catch (err) {
+    console.log(
+      JSON.stringify({
+        additional_context: `ForgeTrail Tracking Syntax Error: Failed to parse ${filePath} as valid JSON: ${err.message}`,
+      })
+    );
+    return;
+  }
+
+  console.log(JSON.stringify({}));
+}
+
+main();

package/docs/SPEC_FEATURE_TEMPLATE.md

@@ -105,12 +105,20 @@ _Surfaces, empty/loading/error states, copy notes, a11y._
 
 ---
 
-## 8. Acceptance criteria
+## 8. Verifier and Acceptance Criteria
 
-_Testable. Prefer “Given / when / then” or checkbox style. The feature is not done until these pass._
+### 8.1 Verifier command
+_Exact automated command(s) that verify this feature (e.g. `pnpm run test:feature`, `pnpm run verify`, or dedicated test script). A delivery spec without a runnable verifier command fails spec review._
 
-1. Given …, when …, then …
-2. Given …, when …, then …
+```bash
+pnpm test
+```
+
+### 8.2 Acceptance criteria (boolean-checkable)
+_Testable binary pass/fail checks. Avoid vague qualifiers ("performant", "clean"). The feature is not done until each criterion evaluates to true._
+
+- [ ] Given ..., when ..., then ...
+- [ ] Given ..., when ..., then ...
 
 ---
 

package/docs/TECHNICAL_REFERENCE.md

@@ -97,7 +97,7 @@ Document **what actually happens** when users remove data — not only the happy
 
 **Pre-release target:** inline audit at **0 UI prose not in export**; sync audit passes for shipped features.
 
-**Cursor rules:** `.cursor/rules/user-facing-content.mdc` (no spec paths in UI), `.cursor/rules/us-english.mdc` (US English default).
+**Cursor rules:** `.cursor/rules/writing-voice.mdc` (voice, theme, and locale defaults), `.cursor/rules/user-facing-content.mdc` (no spec paths in UI).
 
 ## Feature Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgetrail",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "private": false,
   "description": "ForgeTrail: a persistent development system for building software with AI agents. CLI, Lite protocol, and methodology templates.",
   "license": "Apache-2.0",
@@ -23,6 +23,7 @@
     "LICENSE"
   ],
   "scripts": {
+    "workspace:index": "node scripts/workspace-index.mjs",
     "install:forgetrail": "node scripts/install-forgetrail.mjs",
     "install:lite": "node scripts/install-forgetrail-lite.mjs",
     "link:global": "node scripts/link-global.mjs",

package/prompts/microcopy-centralization.md

@@ -107,7 +107,7 @@ Split **prose** (paragraphs, intros, help bodies) from **terms** (labels, toolti
 
 **User-facing content rule:** Help, onboarding, tours, toasts, and empty states must **not** mention internal spec paths or engineering jargon (see `.cursor/rules/user-facing-content.mdc`).
 
-**Locale:** Default **US English** for product copy and LLM prompts that generate user-visible text (see `.cursor/rules/us-english.mdc`).
+**Locale:** Default **US English** for product copy and LLM prompts that generate user-visible text, adapting to target audience or locale (see `.cursor/rules/writing-voice.mdc`).
 
 ---
 

package/prompts/pre-launch-audit.md

@@ -136,6 +136,14 @@ and one-line fix suggestions. For each finding, include the checklist item numbe
 - [ ] Verify any template markers or placeholders are fully resolved in generated content.
 - [ ] Check that generated content sections don't repeat each other unnecessarily.
 
+### 12. Post-Deploy Smoke Verification
+
+- [ ] Fetch the live production URL (`curl -sI https://...`) and assert it returns HTTP 200 (or expected canonical redirect).
+- [ ] Confirm response HTML contains expected head tags and root elements (not an empty white screen or unhandled server crash).
+- [ ] Verify that static assets (CSS, JS bundles, favicon, logos) return HTTP 200 without CORS or MIME type errors.
+- [ ] Verify that public health check routes (e.g. `/api/health`) return HTTP 200 OK.
+- [ ] Verify live SSL certificate validity and TLS configuration.
+
 ---
 
 ## Severity Guide

package/prompts/propagate-to-forgetrail.md

@@ -96,7 +96,7 @@ Run after meaningful implementation work **and** after substantive **documentati
 | **Deploy scripts, systemd units, or process stop/restart behavior** | `TimeoutStopSec`, blue-green `systemctl stop`, and graceful-shutdown tradeoffs affect **wall-clock deploy time** as well as request safety — **DEPLOYMENT.md** (and **CONTEXT_PROMPT** if it changes operator expectations). |
 | **New scripts, hooks, or dev-tooling** | Journal/lint/build wrappers → **CONTEXT_PROMPT** (tooling) or **TECHNICAL_REFERENCE** (pipelines). |
 | **`.cursor/rules/` git / commit policy** | e.g. `git-user-commits.mdc`, `commit-messages.mdc` — keep **this repo’s** `.cursor/rules/` aligned with your app when you propagate workflow changes: **end of each request**, stage only paths from that request and **commit** with message from **`git diff --staged`** (multi-line body by default); push remains explicit-only. |
-| **Microcopy centralization completed or copy-module pattern adopted** | **`prompts/microcopy-centralization.md`**, **`docs/TECHNICAL_REFERENCE.md`** § User-facing copy, **`docs/CODE_QUALITY.md`** audit checklist, **`docs/BRAND_AND_PRODUCT.md`** duplication policy, **`docs/CONTEXT_PROMPT.md`**, **`.cursor/rules/user-facing-content.mdc`**, **`.cursor/rules/us-english.mdc`**, **`content/cursor-rules/`** mirrors — generalize patterns only, not app-specific strings. |
+| **Microcopy centralization completed or copy-module pattern adopted** | **`prompts/microcopy-centralization.md`**, **`docs/TECHNICAL_REFERENCE.md`** § User-facing copy, **`docs/CODE_QUALITY.md`** audit checklist, **`docs/BRAND_AND_PRODUCT.md`** duplication policy, **`docs/CONTEXT_PROMPT.md`**, **`content/cursor-rules/writing-voice.mdc`**, **`content/cursor-rules/user-facing-content.mdc`** — generalize patterns only, not app-specific strings. |
 | **Assertive product voice / hedging *can* removed from capability copy** | **`.cursor/rules/user-facing-content.mdc`** (Assertive capability copy), **`docs/BRAND_AND_PRODUCT.md`** (We say / We don't say table), **`docs/CONTEXT_PROMPT.md`**, **`docs/CODE_QUALITY.md`** pre-launch grep, **`docs/TEST_PLAN.md`** §4.5; MCP **`cursor-rules/`** mirror. |
 | **Brand theme / positioning spine crystallized** (voice rule file, banned framings, signature-line system, origin-narrative constraints) | **`docs/BRAND_AND_PRODUCT.md`** → *Positioning spine (theme lock)* + *Long-form origin narrative (constraints file)*; **`docs/CONTEXT_PROMPT.md`** pattern + anti-pattern; **`content/cursor-rules/writing-voice.mdc`** template. |
 | **Structured eligibility or requirement fit** (education, clearance, license, work auth — taxonomy + extraction + badges + filters + LLM context) | **`docs/TECHNICAL_REFERENCE.md`** → *[Structured eligibility / requirement fit]* stub; **`docs/TEST_PLAN.md`** §4.6; **`docs/BRAND_AND_PRODUCT.md`** one-line declare-once lesson; do **not** copy domain-specific enums/regex. |

package/prompts/rules-audit.md

@@ -0,0 +1,74 @@
+# Rules and Environment Audit
+
+Analyze the persistent rules, instructions, and hooks loaded into the agent's environment (`.cursor/rules/`, `CLAUDE.md`, `AGENTS.md`, or system prompts).
+
+The goal is to calculate the per-turn token tax, identify overlaps and obsolete instructions, and convert always-on text into deterministic hooks, scoped file globs, or on-demand skills.
+
+---
+
+## How to Use
+
+Provide this prompt to an AI agent with access to `.cursor/rules/`, `CLAUDE.md`, or `AGENTS.md`:
+
+```
+Perform a Rules and Environment Audit on this repository.
+Inspect all files in .cursor/rules/ (or CLAUDE.md / AGENTS.md).
+Analyze per-turn token consumption, alwaysApply status, overlaps, and hook migration opportunities.
+Deliver a ranked trimming and migration proposal.
+```
+
+---
+
+## Audit Checklist
+
+### 1. Inventory and Token Weight
+
+- [ ] Measure estimated token count per rule file (bytes ÷ 4 or tokenizer).
+- [ ] Classify each rule as:
+  - **Always-on** (`alwaysApply: true` or unscoped).
+  - **Scoped** (`globs: [...]`).
+  - **Manual / on-demand** (`alwaysApply: false` without globs).
+- [ ] Calculate the total per-turn baseline tax (sum of all always-on rules).
+
+### 2. Overlap and Redundancy
+
+- [ ] Do multiple rules restate the same constraint (e.g. git commit conventions, package manager rules, voice guidelines)?
+- [ ] Do rules duplicate instructions already provided by the host environment or CLI tooling?
+- [ ] Can companion rules (e.g. Smell Check and writing-voice) be consolidated into a single coherent guide?
+
+### 3. Hook Migration Candidates
+
+Can any prose rule be replaced by a deterministic hook that costs zero tokens on normal turns?
+
+- [ ] **Package manager locking:** Rules telling agents to use pnpm can be enforced by a shell guard hook when `pnpm-lock.yaml` is present.
+- [ ] **Git push restrictions:** Rules telling agents not to push can be enforced by `permission: "ask"` in a shell hook.
+- [ ] **Pre-commit verification:** Rules requiring typecheck/build before commit can be run automatically before `git commit` executes.
+- [ ] **Tracking maintenance:** Rules telling agents to read/update tracking can be replaced by `sessionStart` context injection and `afterFileEdit` tracking validation.
+
+### 4. Skill Conversion Candidates
+
+- [ ] Is the rule only needed during specific tasks (e.g. documentation propagation, release tagging, database migration)?
+- [ ] If so, should it be converted to an on-demand Skill (`SKILL.md`) loaded only when triggered, rather than consuming context on every code edit?
+
+---
+
+## Output Format
+
+Return the audit with:
+
+1. **Rule Inventory Table:**
+   | Rule | Lines | Est. Tokens | Mode (Always / Glob / Manual) | Purpose |
+   |------|-------|-------------|-------------------------------|---------|
+   | ...  | ...   | ...         | ...                           | ...     |
+
+2. **Per-Turn Token Tax:**
+   - Current always-on tokens per turn: `N` tokens.
+   - 40-turn chat impact: `40 × N` tokens.
+
+3. **Trimming & Migration Recommendations:**
+   - **Retire (replaced by hooks):** Rules that can be deleted because hooks now enforce them.
+   - **Scope (convert to globs):** Always-on rules that only apply to specific file extensions or directories.
+   - **Skillify (convert to on-demand):** Deep workflow rules that should load only when specifically invoked.
+   - **Consolidate:** Rules that overlap.
+
+4. **Projected Savings:** New always-on token count and percentage reduction.

package/prompts/second-family-critique.md

@@ -0,0 +1,43 @@
+# Second-Family Critique
+
+Feed a specification or architectural proposal to an opposing model family before executing substantial work.
+
+## Rationale
+
+Single-model workflows replicate the blind spots of their training. A Claude model excels at nuance and long-context synthesis but can drift into over-complicated abstractions. An OpenAI or Gemini model excels at concise logic and edge-case boundaries but can skip narrative continuity or over-simplify complex domain rules.
+
+Running a plan past a different model family surfaces assumptions that look reasonable inside a single conversation history.
+
+---
+
+## How to Use
+
+Copy the prompt block below, attach your spec or Phase 1 brief, and run it in a model from a different family (e.g. run a Claude-authored spec in GPT/Gemini, or vice versa):
+
+```markdown
+You are an adversarial technical reviewer evaluating an architecture and implementation specification.
+Your goal is to surface hidden assumptions, fragile dependencies, concurrency risks, and unearned optimism.
+
+Review the attached specification:
+[Paste or attach spec / brief content here]
+
+Answer these 5 questions directly without preamble:
+
+1. What is the single most fragile assumption in this design?
+2. What edge case will break first under real user behavior or network lag?
+3. Where does the specification use vague verbs or hand-waving instead of concrete interfaces?
+4. What verifier or test is missing that could let broken behavior slip into production?
+5. If you had to simplify this implementation by 30% without dropping core utility, what would you cut?
+
+Rank your critical observations from highest risk to lowest risk.
+```
+
+---
+
+## Processing the Critique
+
+When the second model returns its review:
+
+1. **Verify observations against codebase reality:** Not all critiques apply if the opposing model lacked local file context.
+2. **Update the spec:** Add newly discovered edge cases to the Edge Cases section; tighten acceptance criteria.
+3. **Log architectural pivots:** If a critique exposes an unviable path, log the alternative in `decisions[]` in `workflow_tracking.json`.

package/prompts/spec-review.md

@@ -0,0 +1,65 @@
+# Spec Review
+
+A structured pre-implementation audit for feature specifications. Run this against any draft spec in `specs/` before writing multi-file code. Modeled after Bugbot and Security Review: read the spec, check it against the live codebase, and catch ambiguities, missing verifiers, or architectural drift before code starts.
+
+---
+
+## How to Use
+
+Provide this prompt to an AI agent with read access to the repository:
+
+```
+Perform a Spec Review on [path/to/spec.md].
+Inspect the existing codebase to verify assumptions, referenced files, and API contracts.
+Report findings grouped by VERIFIER, FEASIBILITY, ACCEPTANCE CRITERIA, and AMBIGUITIES.
+Conclude with a clear verdict: APPROVED, REVISE, or BLOCKED.
+```
+
+---
+
+## Review Dimensions
+
+### 1. Verifier Presence (Gate)
+
+- [ ] Does the spec include a dedicated **How to test / Verifier command** section?
+- [ ] Is the command runnable by an agent or developer (e.g. `pnpm test`, `pnpm run verify`, or targeted test script)?
+- [ ] If no automated test exists, does it name the exact manual verification steps with expected outputs?
+- **Rule:** A delivery spec without a runnable verifier fails this gate automatically.
+
+### 2. Codebase Grounding & Feasibility
+
+- [ ] Do referenced files, routes, components, and functions actually exist in the codebase?
+- [ ] Does the proposed approach align with existing conventions (imports, error handling, state management)?
+- [ ] Does the proposed data model conflict with existing database schemas or migrations?
+- [ ] Will this change break existing tests or public API contracts?
+
+### 3. Acceptance Criteria Quality
+
+- [ ] Are criteria written as boolean-checkable statements?
+- [ ] Do criteria specify clear inputs and expected outcomes (Given / When / Then)?
+- [ ] Are vague qualifiers ("fast", "intuitive", "clean", "responsive") eliminated or replaced with concrete metrics?
+- [ ] Are sad paths, error conditions, and empty states covered?
+
+### 4. Edge Cases and Traps
+
+- [ ] What happens on network failure, timeout, or invalid inputs?
+- [ ] Are concurrency, race conditions, or multi-tab usage considered?
+- [ ] Are secrets, environment variables, or permissions handled properly?
+
+---
+
+## Output Format
+
+Return your review in the following structure:
+
+1. **Summary:** 1–2 sentences on what the spec intends to build.
+2. **Verifier Gate:** Pass or Fail (name the verifier command or flag missing).
+3. **Findings Table:**
+   | Severity | Category | Item | Issue / Risk | Suggested Fix |
+   |----------|----------|------|--------------|---------------|
+   | Blocker  | Feasibility | ... | ... | ... |
+   | Warning  | Acceptance Criteria | ... | ... | ... |
+4. **Verdict:**
+   - **APPROVED:** Ready for implementation.
+   - **REVISE:** Minor fixes needed in spec before implementation.
+   - **BLOCKED:** Architectural or verifier gaps prevent starting code.

package/scripts/forgetrail-cli.mjs

@@ -14,6 +14,7 @@ ForgeTrail — bootstrap a project folder and run the MCP server
 
 Usage:
   forgetrail install [--lite] [options]
+  forgetrail workspace [dir]         Scan workspace and emit cross-repo status table
   forgetrail mcp <subcommand>        Build, status, ping, Cursor config
 
 Global link (one-time, from your forgetrail clone):
@@ -58,6 +59,11 @@ function main() {
     return;
   }
 
+  if (cmd === "workspace" || cmd === "index") {
+    import("./workspace-index.mjs");
+    return;
+  }
+
   if (cmd !== "install") {
     console.error(`Unknown command: ${cmd ?? "(none)"}`);
     console.error("Run forgetrail --help");

package/scripts/install.mjs

@@ -30,12 +30,23 @@ const LITE_FILES = [
 ];
 
 const LITE_CURSOR_RULES = [
-  "forgetrail-no-trailer.mdc",
   "forgetrail-updates-log.mdc",
   "specs-and-todo.mdc",
   "spec-completion.mdc",
 ];
 
+const HOOK_FILES = [
+  "guard-shell.mjs",
+  "guard-edit.mjs",
+  "session-start.mjs",
+  "validate-tracking.mjs",
+  "validate-tracking-core.mjs",
+  "session-stop.mjs",
+  "cursor-hooks.json",
+  "claude-settings-hooks.json",
+  "README.md",
+];
+
 export function runInstallForgetrail(rawArgv, { defaultToCwd = false } = {}) {
   const args = parseInstallArgs(rawArgv);
   if (args.help) return { help: INSTALL_FULL_HELP };
@@ -67,10 +78,25 @@ export function runInstallForgetrail(rawArgv, { defaultToCwd = false } = {}) {
     );
   }
 
+  const hooksSrc = join(FORGETRAIL_ROOT, "content", "hooks");
+  const hooksDest = join(target, ".forgetrail", "hooks");
+  ensureDir(hooksDest, args.dryRun);
+  for (const hookFile of HOOK_FILES) {
+    copyPath(join(hooksSrc, hookFile), join(hooksDest, hookFile), opts);
+  }
+  const cursorDir = join(target, ".cursor");
+  ensureDir(cursorDir, args.dryRun);
+  copyPath(
+    join(hooksSrc, "cursor-hooks.json"),
+    join(cursorDir, "hooks.json"),
+    opts
+  );
+
   console.log("\nDone.");
   console.log("  Methodology:  _forgetrail/WORKFLOW.md");
   console.log("  First chat:   _forgetrail/INITIAL_PROMPT.md");
   console.log("  Tracking:     .forgetrail/workflow_tracking.json");
+  console.log("  Hooks:        .forgetrail/hooks/ (enforced via .cursor/hooks.json)");
   return { target, mode: "full" };
 }
 
@@ -109,6 +135,21 @@ export function runInstallLite(rawArgv, { defaultToCwd = false } = {}) {
     );
   }
 
+  const hooksSrc = join(contentDir, "hooks");
+  const hooksDest = join(forgetrailDir, "hooks");
+  ensureDir(hooksDest, args.dryRun);
+  for (const hookFile of HOOK_FILES) {
+    copyPath(join(hooksSrc, hookFile), join(hooksDest, hookFile), opts);
+  }
+
+  const cursorDir = join(target, ".cursor");
+  ensureDir(cursorDir, args.dryRun);
+  copyPath(
+    join(hooksSrc, "cursor-hooks.json"),
+    join(cursorDir, "hooks.json"),
+    opts
+  );
+
   if (args.withGenesisStub) {
     const genesisDest = join(target, "docs", "GENESIS.md");
     ensureDir(join(target, "docs"), args.dryRun);
@@ -118,6 +159,7 @@ export function runInstallLite(rawArgv, { defaultToCwd = false } = {}) {
   console.log("\nDone.");
   console.log("  Protocol:  .forgetrail/FORGETRAIL_LITE.md");
   console.log("  Tracking:  .forgetrail/workflow_tracking.json (lite-1 schema)");
+  console.log("  Hooks:     .forgetrail/hooks/ (enforced via .cursor/hooks.json)");
   if (args.withGenesisStub) {
     console.log("  Genesis:   docs/GENESIS.md (stub — replace with your spec)");
     console.log("  Next:      see TRY_FORGETRAIL.md in the ForgeTrail repo");