@warpgogol/forge 0.8.0 → 0.9.0

package/package.json

@@ -1,19 +1,11 @@
 {
   "name": "@warpgogol/forge",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
   "description": "Framework for documenting and implementing ideas — RFC/ADR governance, skills, and project bootstrapping.",
-  "keywords": [
-    "rfc",
-    "adr",
-    "governance",
-    "skills",
-    "ai-agent",
-    "documentation",
-    "framework"
-  ],
+  "keywords": ["rfc", "adr", "governance", "skills", "ai-agent", "documentation", "framework"],
   "homepage": "https://warpgogol.com",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/skills/_shared/fo-pipeline-conventions.md

@@ -117,3 +117,68 @@ After completing implementation work, the operator may run a three-step session-
 3. **`fo-handoff`** — what does the next agent need? (continuity document)
 
 Most sessions need only `fo-doc-audit`. `fo-session-retro` is valuable after debugging sessions, exploratory work, or when non-obvious behaviors were discovered. `fo-handoff` is needed when work is incomplete and another agent will continue.
+
+## Context checkpoint between batch items
+
+When the orchestrator skill processes multiple documents (>=2), perform a context checkpoint after completing one document and before starting the next:
+
+1. **Emit checkpoint block** — output a YAML-formatted block in conversation output with the following fields:
+   - `completed`: RFC/ADR id of the completed document
+   - `status`: final status (implemented, accepted, draft, failed)
+   - `commits`: list of commit SHAs produced for this document
+   - `lessons`: 1-3 short freeform sentences capturing key errors, root causes, patterns discovered, or validator quirks encountered during this document's pipeline run
+   - `dependencies`: cross-RFC dependency notes (e.g., "RFC-YYYY depends on RFC-XXXX for schema field Z") — empty if none
+   - `next`: id of the next document to process, or `null` if this was the last
+2. **Release context** — explicitly treat all detailed context from the completed document as no longer actionable: file contents, search results, edit operations, intermediate reasoning. Retain only the checkpoint block. Release means treat as no longer actionable for reasoning, not delete or undo.
+3. **Fresh start** — begin the next document with a fresh read phase: re-read the RFC file and all related documents (amends, supersedes, related RFCs, DNA invariants, AGENTS.md sections).
+
+The checkpoint block doubles as a resume marker: when resuming an interrupted batch, scan conversation output for the last checkpoint block, extract completed ids and statuses, and continue with the next uncompleted item. If no checkpoint markers are found, fall back to the existing resume logic (git log, file inspection, frontmatter status).
+
+**Only applies to batch processing (>=2 documents).** Single-document invocations do not need a checkpoint — the context is already fresh at the start.
+
+## Step-level context checkpoint during implementation
+
+When the orchestrator skill implements a single RFC with >=5 plan steps, perform a step checkpoint after completing each plan step and committing:
+
+1. **Emit step-checkpoint block** — output a YAML-formatted block in conversation output with the following fields:
+   - `rfc`: RFC id being implemented
+   - `step`: plan step number (e.g., 3)
+   - `title`: plan step title
+   - `commit`: SHA of the commit produced by this step
+   - `decisions`: 1-3 short freeform sentences capturing key micro-decisions made during this step (e.g., "used flag instead of new command", "skipped validator X because it's in package Y, not in scope")
+   - `errors`: list of errors encountered and fixed during this step — empty if none
+   - `nextStep`: number of the next plan step, or `null` if this was the last
+2. **Release step context** — treat all detailed context from the completed step as no longer actionable: codebase search results, file reads, edit operations, validation output. Retain only the step-checkpoint block and the RFC's plan file.
+3. **Fresh start** — begin the next plan step with a fresh read of the plan file and the specific files the next step touches.
+
+The step checkpoint doubles as a resume marker: when resuming an interrupted implementation, scan conversation output for the last step-checkpoint block, extract the completed step number, and resume from the next step.
+
+**Only applies to plans with >=5 steps.** Small plans (4 or fewer steps) do not need step checkpoints — the context is manageable without them.
+
+## Progress beacon
+
+The orchestrator skill emits a one-line progress beacon after completing each pipeline step (audit, enhance, plan, implement, review, fix) for each RFC. The beacon is informational only — it does not pause the pipeline, does not request operator input, and does not release context.
+
+Format: `[beacon] RFC-XXXX | <step> ✓ | next: <next-step>`
+
+For failed steps being fixed: `[beacon] RFC-XXXX | <step> ✗ (fixing...) | next: <next-step>`
+
+The beacon text must use `aiLanguage` per the language policy.
+
+## Error checkpoint for pipeline step failures
+
+When a pipeline step fails and cannot be auto-fixed within 2 attempts (per §Command execution timeout discipline), emit a structured error checkpoint block in conversation output:
+
+1. **Emit error checkpoint** — output a YAML block with: rfc, step, planStep (if within implement phase), error (command, exitCode, summary, attempts), partialState (filesModified, commits, rfcStatus), resumePoint.
+2. **Stop the pipeline** — do not continue to the next pipeline step. The error is not auto-fixable; continuing would compound the problem. This is an **explicit exception** to the orchestrator's "no pauses between pipeline steps" constraint. The "no pauses" directive assumes the pipeline can proceed; when an error is unfixable after 2 attempts, continuing is impossible and the exception is justified. The pause is for error reporting, not for optional operator input.
+3. **Report to operator** — present the error checkpoint in `aiLanguage` and ask the operator how to proceed: fix manually, skip the step, or abort the RFC.
+
+The error checkpoint doubles as a resume marker: when resuming an interrupted session, scan for the last error checkpoint. If found, resume from the failed step using the partialState and resumePoint fields.
+
+## Batch plan preview
+
+When the orchestrator skill processes multiple documents (>=2), emit a batch plan preview before starting the first document. The preview is a table showing: processing order, document id, type, complexity estimate, dependencies, and notes.
+
+The preview is informational — it does not pause for operator approval unless the operator explicitly requests confirmation. The operator's invocation of the orchestrator is the instruction to proceed.
+
+The preview text must use `aiLanguage` per the language policy.

package/skills/fo/fo-idea-i-just-want-to-see-the-result/SKILL.md

@@ -54,6 +54,12 @@ Record the document id(s) and type(s) (RFC or ADR). If multiple documents were c
 
 For each document, run the full pipeline inline. The pipeline differs for RFCs and ADRs.
 
+**Between batch items:** After completing one document's pipeline and before starting the next, perform a context checkpoint per `_shared/fo-pipeline-conventions.md` §Context checkpoint between batch items. Emit the checkpoint block, release completed-item context, and start the next item with a fresh read phase. This does not pause for operator input — the checkpoint is an agent-internal context management step, not a user interaction.
+
+**Batch plan preview:** When processing >=2 documents, emit a batch plan preview per `_shared/fo-pipeline-conventions.md` §Batch plan preview before starting the first document.
+
+**Progress beacon:** After completing each pipeline step, emit a one-line progress beacon per `_shared/fo-pipeline-conventions.md` §Progress beacon. The beacon is informational — it does not pause the pipeline.
+
 #### RFC pipeline
 
 Execute these steps **in order**, invoking each skill inline via the `skill` tool. Do not stop between steps. Do not ask the operator "shall I proceed?" between steps — the operator's invocation of this skill IS the instruction to proceed through the entire pipeline.
@@ -80,6 +86,10 @@ Invoke `fo-idea-implement` on the RFC. Pass the RFC id. Wait for it to complete.
 
 Do not invoke `fo-review` or `fo-fix` separately — they are built into `fo-idea-implement`.
 
+**Step-level checkpoints:** When implementing an RFC with >=5 plan steps, perform a step checkpoint after each plan step per `_shared/fo-pipeline-conventions.md` §Step-level context checkpoint during implementation. Emit the step-checkpoint block, release completed-step context, and start the next step with a fresh plan read.
+
+**Error checkpoint:** If a pipeline step fails after 2 auto-fix attempts, emit a structured error checkpoint per `_shared/fo-pipeline-conventions.md` §Error checkpoint for pipeline step failures. Stop the pipeline and report to the operator.
+
 **Fallback verification (MANDATORY).** After `fo-idea-implement` returns, verify that review and fix were actually executed:
 
 1. Check for a review report in `docs/reviews/code/` dated today or with a `diffRange` covering this session's commits.