forgetrail 0.4.20 → 0.5.0

package/content/AGENT_INTEGRATION_cursor.md

@@ -23,7 +23,7 @@ Use plan mode for Phase 1 if available. Lock PHASE_1_BRIEF.md before scaffolding
 
 **Resume:**
 ```
-Call getResumeSessionInstructions. Read .forgetrail/workflow_tracking.json and CONTEXT_PROMPT.md.
+Call getResumeSessionInstructions. Read appledger/profiles/forgetrail.yaml, the latest session record, and CONTEXT_PROMPT.md. Do not update workflow_tracking.json.
 ```
 
 ## Subagent patterns
@@ -41,8 +41,8 @@ Use `run_in_background` for long subagents when appropriate.
 ## Tracking sync
 
 After subagent or feature work:
-- Update `.forgetrail/workflow_tracking.json` (exit criteria, decisions, gotchas, sessions).
-- Run **`validateTracking`**.
+- Update `appledger/` (criteria, decision records, lessons, the session). Do not write `workflow_tracking.json`.
+- Run **`validateTracking`** only when a legacy tracking file is present. A missing file is expected.
 - Update `CONTEXT_PROMPT.md` when architecture or patterns change.
 
 ## Skills alternative

package/content/AGENT_INTEGRATION_generic.md

@@ -6,7 +6,7 @@ Use this when no agent-specific guide is available. ForgeTrail is **agent-agnost
 
 | Layer | Responsibility |
 |-------|----------------|
-| **ForgeTrail** | 7-phase lifecycle, `.forgetrail/workflow_tracking.json`, progressive docs, audits, lessons |
+| **ForgeTrail** | 7-phase lifecycle, `appledger/`, progressive docs, audits, lessons |
 | **Host agent** | Tool use, file edits, terminal, optional subagents/plan modes |
 
 ForgeTrail owns **what** and **when**. The host agent owns **execution**.
@@ -15,14 +15,14 @@ ForgeTrail owns **what** and **when**. The host agent owns **execution**.
 
 **New project:**
 ```
-Call ForgeTrail getNewProjectKickoff, write .forgetrail/workflow_tracking.json, then getPhaseGuidance("1").
+Call ForgeTrail getNewProjectKickoff, write appledger/, then getPhaseGuidance("1"). Do not write workflow_tracking.json.
 Lock architecture in docs/PHASE_1_BRIEF.md before any app code.
 ```
 
 **Resume:**
 ```
-Call getResumeSessionInstructions. Read .forgetrail/workflow_tracking.json and CONTEXT_PROMPT.md.
-Continue from currentPhase.
+Call getResumeSessionInstructions. Read appledger/profiles/forgetrail.yaml, the latest session record, and CONTEXT_PROMPT.md.
+Continue from the current phase. Do not update workflow_tracking.json.
 ```
 
 ## When the host supports subagents
@@ -35,7 +35,7 @@ Prefer **read-only** subagents for analysis; parent or a single write-capable wo
 
 ## When the host supports plan mode
 
-Use native plan mode for **Phase 1** only. On approval, export to `PHASE_1_BRIEF.md` + `decisions[]`. See **`getPlanModePatterns`**.
+Use native plan mode for **Phase 1** only. On approval, export to `PHASE_1_BRIEF.md` and decision records in `appledger/`. Do not write `workflow_tracking.json`. See **`getPlanModePatterns`**.
 
 ## Persistent discipline
 

package/content/AGENT_INTEGRATION_grok.md

@@ -6,25 +6,25 @@ Grok Build (the agentic TUI/CLI from xAI) has excellent native primitives that m
 
 | Grok Primitive              | ForgeTrail Phase(s)          | How to Use |
 |-----------------------------|----------------------------|------------|
-| `/plan` + enter/exit_plan_mode + plan.md | Phase 1 (Architecture)    | Use native plan mode for all Phase 1 work. On approval, export to `PHASE_1_BRIEF.md` + `decisions[]`. See `PLAN_MODE_PATTERNS.md`. |
+| `/plan` + enter/exit_plan_mode + plan.md | Phase 1 (Architecture)    | Use native plan mode for all Phase 1 work. On approval, export to `PHASE_1_BRIEF.md` and decision records in `appledger/`. Do not write `workflow_tracking.json`. See `PLAN_MODE_PATTERNS.md`. |
 | `spawn_subagent` (explore/plan/general, capability_mode, isolation: worktree, background, resume_from, personas) | All phases, especially 4, 5, 7 | Use for parallel audits (black-hat, UX, code quality), research, stabilize debugging, and exploratory spikes. Call `suggestSubagentDecomposition` first. Prefer read-only for analysis subagents. |
-| `todo_write` + TODO panel   | All phases                 | Mirror open exit criteria and next actions from `.forgetrail/workflow_tracking.json`. Use as the visible "what's next" while tracking.json is the durable record. |
+| `todo_write` + TODO panel   | All phases                 | Mirror open criteria and next actions from `appledger/profiles/forgetrail.yaml`. The ledger is the durable record. Do not write `workflow_tracking.json`. |
 | Skills (`/create-skill`, SKILL.md) | All sessions             | Install the `forgetrail` skill (see `SKILL.md` in content/skills/forgetrail). It keeps phase discipline, tracking rules, and subagent patterns always active. |
 | Native MCP (search_tool + use_tool) | Methodology delivery    | Register the ForgeTrail MCP server. Tools appear as `forgetrail__*`. Use `getNewProjectKickoff`, `getPhaseGuidance`, `getCompanionSuggestions`, `runAudit`, `searchLessons`, `validateTracking`, etc. |
 | Headless (`grok -p ... --output-format json`) | Automation / CI       | Call kickoff/resume tools and have the agent produce structured phase state. Add exit-criteria validation in pipelines. |
 | `docx` / `pptx` / `xlsx` skills + image/video gen | Phase 1 intake, Phase 6/7 deliverables | Use for exports (PDF/DOCX/PPTX), landing pages, brand assets, and marketing materials called out in greenfield intake. |
-| Sessions + memory + AGENTS.md | Cross-session continuity | `.forgetrail/workflow_tracking.json` + `CONTEXT_PROMPT.md` are the ForgeTrail equivalents. Update them at session end. |
+| Sessions + memory + AGENTS.md | Cross-session continuity | `appledger/` plus `CONTEXT_PROMPT.md` are the ForgeTrail equivalents. Update the session record at session end. Do not write `workflow_tracking.json`. |
 
 ## Recommended Session Openers in Grok
 
 For a new project:
 ```
-Call ForgeTrail getNewProjectKickoff (includeCursorRule false), write the tracking file, then start Phase 1 using native /plan mode. Read the generated plan on approval and produce PHASE_1_BRIEF.md + decisions.
+Call ForgeTrail getNewProjectKickoff (includeCursorRule false), write appledger/, then start Phase 1 using native /plan mode. Read the generated plan on approval and produce PHASE_1_BRIEF.md plus decision records. Do not write workflow_tracking.json.
 ```
 
 For resuming:
 ```
-Call ForgeTrail getResumeSessionInstructions. Read .forgetrail/workflow_tracking.json and CONTEXT_PROMPT.md. Continue from current phase.
+Call ForgeTrail getResumeSessionInstructions. Read appledger/profiles/forgetrail.yaml, the latest session record, and CONTEXT_PROMPT.md. Continue from the current phase. Do not update workflow_tracking.json.
 ```
 
 ## Subagent Patterns (Grok-specific)
@@ -42,11 +42,11 @@ Main thread: synthesize results into BLACK_HAT_REPORT.md + CODE_QUALITY.md, upda
 
 Use `background: true` for long-running subagents and retrieve with `get_command_or_subagent_output`.
 
-## Tracking Sync
+## Ledger sync
 
 After meaningful work (especially subagent results or feature completion):
-- Update `.forgetrail/workflow_tracking.json` (exit criteria, decisions, gotchas, sessions).
-- Use `todo_write` to surface the next 3–5 open items from the tracking file.
+- Update `appledger/` (criteria, decision records, lessons, the session). Do not write `workflow_tracking.json`.
+- Use `todo_write` to surface the next 3–5 open items from the profile.
 - Update `CONTEXT_PROMPT.md` when patterns or architecture change.
 
 ## Skills Usage

package/content/COMPANION_TOOLS.md

@@ -4,7 +4,7 @@ ForgeTrail owns phases, tracking, and progressive docs. **Companions** do one bo
 
 Public shelf (current versions and install): [catalystforge.com/tools](https://catalystforge.com/tools/).
 
-**Agents:** call **`getCompanionSuggestions`** with a `phase` (`1`–`7`) or a `situation` id when a trigger below is true. `getPhaseGuidance` also appends a short optional-companions footer. Offer one sentence plus the homepage. Do **not** install unless the user asked. Do **not** name this file, MCP tools, or spec paths in the human-facing offer. After a run that matters, persist the outcome in `.forgetrail/workflow_tracking.json` and the matching progressive doc.
+**Agents:** call **`getCompanionSuggestions`** with a `phase` (`1`–`7`) or a `situation` id when a trigger below is true. `getPhaseGuidance` also appends a short optional-companions footer. Offer one sentence plus the homepage. Do **not** install unless the user asked. Do **not** name this file, MCP tools, or spec paths in the human-facing offer. After a run that matters, persist the outcome on the appledger session as `data.companion_outcomes` and in the matching progressive doc. Do not write `workflow_tracking.json`.
 
 **Humans:** skip this file unless you already want a neighbor for a specific job.