@izkac/forgekit 0.1.7 → 0.3.0

package/vendor/skills/forge/references/operator-brief.md

@@ -0,0 +1,74 @@
+# Operator brief — `brief.html`
+
+Every tracked change (openspec or specs engine) ends its plan phase with an
+**operator brief**: one self-contained HTML file at
+`<changeDir>/brief.html` that a human can read in two minutes and understand
+*what will be built* — without reading proposal.md, design.md, or tasks.md.
+
+The plan-approval checkpoint is only as strong as the operator's comprehension.
+The specs are written for agents; the brief is the translation for the human
+who approves them. `forge phase implement` **refuses** while the brief is
+missing, unstamped, or stale.
+
+## Who writes it
+
+You (the agent), at the end of the plan phase — after the specs are final,
+before `forge phase implement`. The CLI never generates prose; it only stamps
+freshness and opens the file.
+
+## Workflow
+
+```bash
+# 1. specs are final (proposal.md / design.md / tasks.md)
+# 2. write <changeDir>/brief.html   (structure below)
+forge brief stamp        # records specs hash + opens it in the operator's browser
+forge phase implement --tasks-total <N>   # hard-gated on a fresh stamped brief
+```
+
+If any spec file changes later, the brief goes **stale** — update the affected
+sections and `forge brief stamp` again. `forge brief check` reports status.
+Genuine edge case (operator explicitly waives it):
+`forge phase implement --allow-incomplete "<reason>"`.
+
+## Writing rules
+
+Audience: a smart human who has NOT read the specs and doesn't want to.
+Plain language. No spec-speak, no requirement IDs, no file paths in headings.
+If a sentence would not make sense to a project stakeholder outside this
+session, rewrite it.
+
+Structure (sections, in order — skip a section only when truly empty):
+
+1. **TL;DR** — 2-3 sentences: what will exist after this change that doesn't
+   today, and why it's worth doing.
+2. **What you'll get** — the observable outcomes, bulleted. Behavior, not
+   implementation ("you can send a message to any session from one terminal",
+   not "a registry module under lib/").
+3. **How it works** — the shape of the solution in one short narrative plus a
+   **mermaid diagram** where a picture beats prose (flow, sequence, or state —
+   whichever fits; skip the diagram for trivial changes rather than forcing one).
+4. **What changes for you** — new commands/screens/steps the operator will
+   use; anything that behaves differently than before.
+5. **Risks and open questions** — honest, short. What could go wrong, what was
+   deliberately deferred, what the operator should keep an eye on.
+6. **Out of scope** — what this change deliberately does NOT do.
+7. **Work overview** — task groups from tasks.md compressed to one line each,
+   with rough size (n tasks). Not the full task list.
+
+## File rules
+
+- One file, self-contained: inline CSS, no build step, no local assets.
+- Mermaid via CDN is fine (`<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js">`
+  + `mermaid.initialize({ startOnLoad: true })`; diagrams in `<pre class="mermaid">` blocks).
+  Trade-off accepted: diagrams need internet to render; the text must stand on
+  its own without them.
+- Readable defaults: max-width ~48rem/prose, system font stack, dark-on-light.
+  Keep styling minimal — this is a memo, not a product page.
+- Do not remove the `<!-- forge-brief-specs-hash:… -->` comment `forge brief
+  stamp` inserts; re-stamping updates it.
+
+## Archive
+
+`brief.html` lives in the change dir, so it archives with the change
+(`changes/archive/…`) and remains the human-readable record of what was
+approved — useful input for archive→ADR.

package/vendor/skills/forge/references/runtime-integrity.md

@@ -45,12 +45,13 @@ task.
 - To shrink scope: stop and ask the user. Do not silently checkbox around gaps.
 - Prefer `DONE_WITH_CONCERNS` / incomplete tasks over green checkboxes.
 
-## 5. E2E means product loop, not job slice
+## 5. E2E means an executed product loop, not prose
 
 Before claiming the change complete:
 
-1. Run (or document exact commands for) the **closed product loop** through the
-   live entry points, **or**
+1. Author the **closed product loop** as executable steps in `e2e.json`
+   (`forge e2e init`), run it against the live entry points
+   (`forge e2e run`), and get a **green run** — **or**
 2. Leave an explicit **`BLOCKED`** list in `verify-evidence.md` — and do **not**
    mark the change complete / advance to `done`.
 
@@ -65,8 +66,19 @@ next run's OUTPUT DIFFERS from the baseline
 
 Example: ingest→Parquet plus a thin run→`.sav` does **not** verify a
 governance loop; analyze→proposals→ratify→run-applies-decisions does.
-Record it under a `## Product loop` heading in `verify-evidence.md` —
-the mechanical gate looks for it.
+
+The mechanical gate requires a green, **current** `e2e-results.json` (its
+steps hash must match `e2e.json`) whenever the spine has real rows.
+Describing the loop in `verify-evidence.md` no longer satisfies the gate —
+prose cannot prove wiring. Each step is `{ name, cmd, expect?, timeoutMs? }`:
+exit code 0 required, `expect` (regex) matched against the output. Steps must
+assert **domain side effects** — a step list that would pass against a
+stubbed handler is invalid (rule 3 applies to e2e steps too).
+
+`e2e.json` may set `"notApplicable": "<reason>"` only when the loop cannot be
+driven by any command (e.g. requires a physical device). Reviewers police the
+reason; "no time" or "covered by unit tests" is a REJECT. Keep a short loop
+narrative under `## Product loop` in `verify-evidence.md` as reviewer context.
 
 ## 6. Job-kind closure
 
@@ -126,9 +138,9 @@ Then either:
    (e.g. `"sync HTTP only — no async producer/consumer"`). That is the honest
    opt-out; missing `spine.json` is not.
 
-Product-loop evidence in `verify-evidence.md` is required when the spine has
-real rows. Prefer `notApplicable` for sync-only changes instead of inventing a
-fake loop.
+An executed product loop (`forge e2e run`, green + current results) is
+required when the spine has real rows. Prefer `notApplicable` for sync-only
+changes instead of inventing a fake loop.
 
 ## Reviewer REJECT checklist (mandatory)
 
@@ -141,6 +153,8 @@ REJECT the task (or final review → `NOT READY`) if any of:
 - Spec requirement has a library but no named runtime owner
 - Deferred wiring without a registered open deferral (`forge defer list`)
 - Spine row for this capability missing or library-only
+- E2E steps would pass against a stubbed handler (no domain side-effect
+  assertions), or `e2e.json` opts out via `notApplicable` without a real reason
 
 ## Plan seam (every change)
 
@@ -148,10 +162,14 @@ Before apply-ready:
 
 1. `forge spine init` — **always**. Fill rows for each capability, or set
    `notApplicable` with a reason (sync-only / docs-only).
-2. If the change involves workers, job queues, handlers, or cross-runtime
+2. When the spine has real rows, `forge e2e init` — the acceptance **steps are
+   a plan deliverable**: author (or task out) the `e2e.json` step list that
+   drives the loop and asserts its side effects.
+3. If the change involves workers, job queues, handlers, or cross-runtime
    calls, `tasks.md` MUST also include:
    - Explicit **wiring** tasks per job kind / entry point → domain pipeline
-   - One **product-loop acceptance** task (last implement task, before verify)
+   - One **product-loop acceptance** task (last implement task, before
+     verify) — its output is a green `forge e2e run`
 
 Missing spine = plan not ready. Keyword guesses about “jobs in scope” are not
 an excuse to skip the spine.

package/vendor/skills/forge/subagents/final-reviewer-prompt.md

@@ -34,14 +34,17 @@ job, …) that invokes the implementing code. Cross-check against `spine.json`
 - UI/API reads a collection or artifact nothing in the production path writes → **`NOT READY`**
 - Missing E2E fixture path with no explicit `BLOCKED` in `verify-evidence.md` → **`NOT READY`**
 
-## Product-loop evidence (required)
+## Product-loop acceptance (required — executed, not described)
 
-`verify-evidence.md` must contain a `## Product loop` section proving the
-**closed loop** (produce → consume → decision changes output), or an explicit
-`BLOCKED` list. A single job slice (e.g. ingest→file) or a library-level E2E
-does **not** count as platform E2E.
+`forge e2e check` must be green: `e2e.json` steps drive the **closed loop**
+(produce → consume → decision changes output) and `e2e-results.json` records a
+green, current run (steps hash matches). A single job slice (e.g. ingest→file)
+or a library-level E2E does **not** count as platform E2E. Read the steps —
+would they pass against a stubbed handler? If yes, they prove nothing.
 
-- No product-loop section and no `BLOCKED` → **`NOT READY`**
+- No green, current e2e run and no `BLOCKED` in `verify-evidence.md` → **`NOT READY`**
+- E2E steps assert no domain side effects (would pass on a stub) → **`NOT READY`**
+- `e2e.json` `notApplicable` without a reason no command could overcome → **`NOT READY`**
 - `BLOCKED` present → **`NOT READY`** (honest, but not READY)
 - Unresolved deferrals in `forge defer list` → **`NOT READY`**
 

package/vendor/skills/forge/subagents/task-reviewer-prompt.md

@@ -43,6 +43,7 @@ Diff range: {DIFF_RANGE}   <!-- e.g. `git diff` (uncommitted) or BASE..HEAD -->
 - Brief authorized a stub / “wire later” for a path this change claims
 - Wiring is deferred **without a registered open deferral** — the packet must show `forge defer list` output naming this task's deferral; "wiring in §9" with no registry entry is a REJECT
 - The task claims a capability whose `spine.json` row is missing or library-only (empty runtimeOwner / writes / evidence)
+- The task authored or touched `e2e.json` steps that would pass against a stubbed handler (no domain side-effect assertions), or set `notApplicable` without a real reason
 
 **Code quality:**