forgetrail 0.3.0

package/TRACKING_SCHEMA.md

@@ -0,0 +1,162 @@
+# workflow_tracking.json Schema Reference
+
+This file documents how to read and update **`.forgetrail/workflow_tracking.json`** in customer project repos. (This ForgeTrail repo keeps a starter copy at **`workflow_tracking.json`** at the repo root for MCP `getInitialWorkflowTracking` — agents write the output to **`.forgetrail/workflow_tracking.json`** in the app repo.)
+
+Agents should reference this when updating the tracking file.
+
+## Phase ID vocabulary (Lite vs MCP)
+
+Both schemas describe the same seven lifecycle phases. **`scripts/forgetrail-dev-launcher.mjs`** maps either shape to the display names below.
+
+| # | Lite `currentPhase` | MCP `currentPhase` | Display name |
+|---|---------------------|--------------------|--------------|
+| 1 | `1` | `1-architecture` | Plan |
+| 2 | `2` | `2-scaffolding` | Build |
+| 3 | `3` | `3-stabilization` | Stabilize |
+| 4 | `4` | `4-feature-iteration` | Iterate |
+| 5 | `5` | `5-refactoring` | Refine |
+| 6 | `6` | `6-strategic-review` | Align |
+| 7 | `7` | `7-hardening` | Harden |
+
+**Lite (`schemaVersion: "lite-1"`):** numeric `currentPhase`; each phase has **`exitCriteria`** as `{ "flagName": true/false }`. Starter: **`FORGETRAIL_LITE.md`** §11.
+
+**MCP / full starter:** string `currentPhase`; each phase has **`exitCriteriaMet`** and **`exitCriteriaRemaining`** string arrays. Starter: repo-root **`workflow_tracking.json`** via `getInitialWorkflowTracking`.
+
+## Top-Level Fields
+
+### `project`
+
+Static metadata. Set once at project creation (except `status`, which flips at wrap).
+
+```json
+{
+  "name": "My App",
+  "created": "2026-03-12",
+  "description": "One-sentence description",
+  "archetype": "product",
+  "status": "active"
+}
+```
+
+- **`archetype`** — `product` (default) | `internal-tool` | `one-shot`. Set during Phase 1 per **WORKFLOW.md §1d**. When the archetype is not `product`, **prune** non-applicable exit criteria from the phase arrays at bootstrap (e.g. drop payments/business-plan criteria for an internal tool; collapse phases 5–7 into a single polish-and-ship gate for a one-shot). Log the pruning in `decisions[]` so the removal reads as intentional. Do **not** leave inapplicable criteria in place and mark them "N/A" one by one — prune once instead.
+- **`status`** — `active` (default) | `wrapped`. Set to `wrapped` when the project is finished or shelved, after running the **wrap protocol** (WORKFLOW.md §1e): sweep `gotchas[]` + `decisions[]` for generalizable lessons, run the propagation prompt (Harvest mode), add a final `sessions[]` entry with end state and handoff pointers.
+
+### `currentPhase`
+
+String. One of: `1-architecture`, `2-scaffolding`, `3-stabilization`, `4-feature-iteration`, `5-refactoring`, `6-strategic-review`, `7-hardening`.
+
+Note: Phases 4 and 5 can alternate. A project might go 4 -> 5 -> 4 -> 6 -> 4 -> 7. The tracking file reflects reality, not a strict linear path.
+
+### `phases`
+
+Each phase has:
+
+- `status`: `not_started` | `in_progress` | `completed` | `revisiting` (for phases you return to)
+- `startedAt` / `completedAt`: ISO timestamps
+- `exitCriteriaMet`: Array of strings (criteria that have been satisfied)
+- `exitCriteriaRemaining`: Array of strings (criteria not yet met)
+- `notes`: Array of `{ timestamp, text }` objects for anything worth recording during this phase
+
+When Claude believes exit criteria are met, it moves items from `exitCriteriaRemaining` to `exitCriteriaMet` and proposes the phase transition.
+
+### `decisions`
+
+Architectural and design decisions with rationale. **Start logging in Phase 1** alongside **`docs/PHASE_1_BRIEF.md`** so Phase 2 can begin without the Phase 1 chat. After Phase 2, this array stays aligned with **Key Architectural Decisions** in `CONTEXT_PROMPT.md` (which should be populated by merging the brief).
+
+```json
+{
+  "id": "d1",
+  "timestamp": "2026-03-12T10:30:00",
+  "phase": "1-architecture",
+  "session": 1,
+  "decision": "Use PocketBase instead of filesystem storage",
+  "rationale": "Need multi-user support and real-time sync. Filesystem won't scale.",
+  "alternatives_considered": ["SQLite", "Supabase", "No database"],
+  "status": "active"
+}
+```
+
+`status` can be `active`, `superseded` (replaced by a later decision), or `revisit` (flagged for reconsideration). If superseded, add `superseded_by` field with the ID of the replacement decision.
+
+### `gotchas`
+
+Issues, surprises, or traps encountered during development. These persist across sessions so the same mistake isn't repeated.
+
+```json
+{
+  "timestamp": "2026-03-12T14:00:00",
+  "phase": "3-stabilization",
+  "session": 1,
+  "issue": "SvelteKit .env doesn't populate process.env",
+  "resolution": "Use $env/dynamic/private instead",
+  "category": "environment"
+}
+```
+
+Categories: `environment`, `integration`, `data-model`, `ui`, `performance`, `ai-output`, `security`, `tooling`, `other`.
+
+### `sessions`
+
+Log of each session with what was accomplished and where it left off.
+
+```json
+{
+  "session": 1,
+  "date": "2026-03-12",
+  "phasesWorked": ["1-architecture", "2-scaffolding"],
+  "accomplished": ["Confirmed tech stack", "Built full skeleton", "Imported 44 existing jobs"],
+  "leftOff": "App runs but env vars need fixing. Phase 3 next.",
+  "contextLimitHit": false,
+  "approximateLines": 3500
+}
+```
+
+## Update Rules for Claude
+
+1. **After completing a task:** Update the relevant phase's `notes` and move any satisfied exit criteria.
+2. **After making a decision:** Add to `decisions` array with full rationale.
+3. **After hitting a gotcha:** Add to `gotchas` array immediately so it's captured.
+4. **At session end:** Add a session entry to `sessions` array.
+5. **At phase transition:** Update `currentPhase`, set `completedAt` on the old phase, `startedAt` on the new one.
+6. **When revisiting a phase:** Set status to `revisiting`, don't overwrite the original `completedAt`.
+
+## Custom Extensions
+
+Projects may add custom fields to phases as needed. For example, `4-feature-iteration` has an `iterations` array for tracking feature-by-feature progress:
+
+```json
+{
+  "feature": "DOCX tailoring",
+  "status": "complete",
+  "turnsSpent": 8,
+  "approach": "Programmatic placeholder replacement",
+  "notes": "LLM find/replace failed due to Word XML run splitting. Pivoted in turn 6."
+}
+```
+
+Add whatever fields make sense for your project. The schema is a starting point, not a cage.
+
+### `agentContext` (optional, top-level)
+
+Record which agent stack drives the project and what native primitives are available:
+
+```json
+{
+  "primaryAgent": "cursor-agent",
+  "supportsSubagents": true,
+  "supportsPlanMode": true,
+  "lastSessionId": "optional-host-session-id"
+}
+```
+
+### `subagentRuns` (optional, per phase)
+
+Optional array under a phase object to log parallel subagent work (especially Phase 4, 5, 7):
+
+```json
+{
+  "id": "sa-7-security",
+  "description": "Black-hat audit via read-only subagent",
+  "outcome": "12 findings; 2 critical — synthesized into BLACK_HAT_REPORT.md"
+}
+```

package/TRY_FORGETRAIL.md

@@ -0,0 +1,78 @@
+# Try ForgeTrail (no MCP required)
+
+Prove ForgeTrail in one sitting: write a **what, not how** spec in any AI chat, drop it next to **ForgeTrail Lite**, and let your coding agent forge the path and keep the trail.
+
+**You need:** any LLM chat (ChatGPT, Claude, Grok, a local Ollama UI, …) and any coding agent that can read files (Cursor, Claude Code, Codex, …).
+
+**You do not need:** Node MCP setup, `pnpm run mcp:build`, or `forgetrail` on PATH (those are optional shortcuts below).
+
+**Important:** Use a **new empty project folder**. Do not run this inside a clone of the ForgeTrail methodology repo.
+
+---
+
+## 15-minute recipe
+
+1. **Get the Genesis prompt**  
+   Open [`content/GENESIS_SPEC_PROMPT.md`](content/GENESIS_SPEC_PROMPT.md) (or the [raw file on GitHub](https://github.com/Catalyst-Forge-LLC/forgetrail/blob/main/content/GENESIS_SPEC_PROMPT.md)). Copy the **Copy-paste prompt** section.
+
+2. **Iterate a spec in your favorite chat app**  
+   Fill the bracketed parts, send it, and refine until you trust the markdown. Optional shape reference: [`content/examples/GENESIS_SAMPLE_mars-habitat-roster.md`](content/examples/GENESIS_SAMPLE_mars-habitat-roster.md) (fictional Mars duty roster; relatable shared-schedule problem).
+
+3. **Create a new project folder**  
+   Example: `mkdir my-app && cd my-app`
+
+4. **Add ForgeTrail Lite**  
+   - **Copy:** save [`content/FORGETRAIL_LITE.md`](content/FORGETRAIL_LITE.md) as `.forgetrail/FORGETRAIL_LITE.md` in your project, **or**  
+   - **CLI** (Node 20+):  
+     `npx forgetrail install --lite`  
+     Stub for Genesis too:  
+     `npx forgetrail install --lite --with-genesis-stub`
+
+5. **Save your spec as `docs/GENESIS.md`**  
+   Create `docs/` if needed. That path is the canonical handoff for ForgeTrail (not the repo root).
+
+6. **Open the folder in your coding agent** and paste this kickoff line:
+
+> Follow `.forgetrail/FORGETRAIL_LITE.md` as the project protocol. Treat `docs/GENESIS.md` as the product spec (what, not how). Create `.forgetrail/workflow_tracking.json` and draft `docs/PHASE_1_BRIEF.md` from the Genesis file, asking me only about gaps. Do not scaffold application code until I explicitly approve the Phase 1 brief.
+
+7. **Approve the Phase 1 brief** before any app scaffold. If the agent starts writing application code early, stop it and paste the kickoff line again.
+
+---
+
+## What “it worked” looks like
+
+- [ ] `.forgetrail/FORGETRAIL_LITE.md` is present  
+- [ ] `docs/GENESIS.md` is present  
+- [ ] `.forgetrail/workflow_tracking.json` exists  
+- [ ] `docs/PHASE_1_BRIEF.md` drafted from your Genesis (or clearly in progress)  
+- [ ] The agent asked for approval before scaffolding  
+
+Stuck? Open a [Try ForgeTrail checklist](https://github.com/Catalyst-Forge-LLC/forgetrail/issues/new?template=try-forgetrail-checklist.md) issue and mark how far you got.
+
+---
+
+## If you skip Genesis
+
+No written idea yet? Tell the agent: *Follow `.forgetrail/FORGETRAIL_LITE.md`. Ask me the §5 intake questions before writing any code.* You can add `docs/GENESIS.md` later.
+
+Already have a long PRD? Save it as `docs/GENESIS.md` and use the kickoff line above. Optionally run the Genesis prompt only to fill gaps (prior art, file-format research, edge cases).
+
+---
+
+## After the try: graduation ladder
+
+1. **Stay on Lite** for small tools and weekend builds. Enough for many projects.  
+2. **Add MCP** when you live in Cursor/Claude: `npx -y forgetrail-mcp` (set `FORGETRAIL_ROOT` to a `forgetrail` install or clone). See [mcp-server/README.md](mcp-server/README.md).  
+3. **Full `_forgetrail/` install** when you need the whole template tree on disk (offline / no MCP). `npx forgetrail install` (without `--lite`).
+
+---
+
+## Related files
+
+| File | Role |
+|------|------|
+| [`content/GENESIS_SPEC_PROMPT.md`](content/GENESIS_SPEC_PROMPT.md) | Prompt to paste into any LLM chat |
+| [`content/examples/GENESIS_SAMPLE_mars-habitat-roster.md`](content/examples/GENESIS_SAMPLE_mars-habitat-roster.md) | Fictional sample Genesis |
+| [`content/FORGETRAIL_LITE.md`](content/FORGETRAIL_LITE.md) | Portable agent protocol |
+| [`content/GENESIS_STUB.md`](content/GENESIS_STUB.md) | Stub written by `--with-genesis-stub` |
+| [`README.md`](README.md) | Full methodology overview |