@izkac/forgekit 0.1.0

package/vendor/skills/forge/skills/test-driven-development/testing-anti-patterns.md

@@ -0,0 +1,299 @@
+# Testing Anti-Patterns
+
+**Load this reference when:** writing or changing tests, adding mocks, or tempted to add test-only methods to production code.
+
+## Overview
+
+Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.
+
+**Core principle:** Test what the code does, not what the mocks do.
+
+**Following strict TDD prevents these anti-patterns.**
+
+## The Iron Laws
+
+```
+1. NEVER test mock behavior
+2. NEVER add test-only methods to production classes
+3. NEVER mock without understanding dependencies
+```
+
+## Anti-Pattern 1: Testing Mock Behavior
+
+**The violation:**
+```typescript
+// ❌ BAD: Testing that the mock exists
+test('renders sidebar', () => {
+  render(<Page />);
+  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
+});
+```
+
+**Why this is wrong:**
+- You're verifying the mock works, not that the component works
+- Test passes when mock is present, fails when it's not
+- Tells you nothing about real behavior
+
+**your human partner's correction:** "Are we testing the behavior of a mock?"
+
+**The fix:**
+```typescript
+// ✅ GOOD: Test real component or don't mock it
+test('renders sidebar', () => {
+  render(<Page />);  // Don't mock sidebar
+  expect(screen.getByRole('navigation')).toBeInTheDocument();
+});
+
+// OR if sidebar must be mocked for isolation:
+// Don't assert on the mock - test Page's behavior with sidebar present
+```
+
+### Gate Function
+
+```
+BEFORE asserting on any mock element:
+  Ask: "Am I testing real component behavior or just mock existence?"
+
+  IF testing mock existence:
+    STOP - Delete the assertion or unmock the component
+
+  Test real behavior instead
+```
+
+## Anti-Pattern 2: Test-Only Methods in Production
+
+**The violation:**
+```typescript
+// ❌ BAD: destroy() only used in tests
+class Session {
+  async destroy() {  // Looks like production API!
+    await this._workspaceManager?.destroyWorkspace(this.id);
+    // ... cleanup
+  }
+}
+
+// In tests
+afterEach(() => session.destroy());
+```
+
+**Why this is wrong:**
+- Production class polluted with test-only code
+- Dangerous if accidentally called in production
+- Violates YAGNI and separation of concerns
+- Confuses object lifecycle with entity lifecycle
+
+**The fix:**
+```typescript
+// ✅ GOOD: Test utilities handle test cleanup
+// Session has no destroy() - it's stateless in production
+
+// In test-utils/
+export async function cleanupSession(session: Session) {
+  const workspace = session.getWorkspaceInfo();
+  if (workspace) {
+    await workspaceManager.destroyWorkspace(workspace.id);
+  }
+}
+
+// In tests
+afterEach(() => cleanupSession(session));
+```
+
+### Gate Function
+
+```
+BEFORE adding any method to production class:
+  Ask: "Is this only used by tests?"
+
+  IF yes:
+    STOP - Don't add it
+    Put it in test utilities instead
+
+  Ask: "Does this class own this resource's lifecycle?"
+
+  IF no:
+    STOP - Wrong class for this method
+```
+
+## Anti-Pattern 3: Mocking Without Understanding
+
+**The violation:**
+```typescript
+// ❌ BAD: Mock breaks test logic
+test('detects duplicate server', () => {
+  // Mock prevents config write that test depends on!
+  vi.mock('ToolCatalog', () => ({
+    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
+  }));
+
+  await addServer(config);
+  await addServer(config);  // Should throw - but won't!
+});
+```
+
+**Why this is wrong:**
+- Mocked method had side effect test depended on (writing config)
+- Over-mocking to "be safe" breaks actual behavior
+- Test passes for wrong reason or fails mysteriously
+
+**The fix:**
+```typescript
+// ✅ GOOD: Mock at correct level
+test('detects duplicate server', () => {
+  // Mock the slow part, preserve behavior test needs
+  vi.mock('MCPServerManager'); // Just mock slow server startup
+
+  await addServer(config);  // Config written
+  await addServer(config);  // Duplicate detected ✓
+});
+```
+
+### Gate Function
+
+```
+BEFORE mocking any method:
+  STOP - Don't mock yet
+
+  1. Ask: "What side effects does the real method have?"
+  2. Ask: "Does this test depend on any of those side effects?"
+  3. Ask: "Do I fully understand what this test needs?"
+
+  IF depends on side effects:
+    Mock at lower level (the actual slow/external operation)
+    OR use test doubles that preserve necessary behavior
+    NOT the high-level method the test depends on
+
+  IF unsure what test depends on:
+    Run test with real implementation FIRST
+    Observe what actually needs to happen
+    THEN add minimal mocking at the right level
+
+  Red flags:
+    - "I'll mock this to be safe"
+    - "This might be slow, better mock it"
+    - Mocking without understanding the dependency chain
+```
+
+## Anti-Pattern 4: Incomplete Mocks
+
+**The violation:**
+```typescript
+// ❌ BAD: Partial mock - only fields you think you need
+const mockResponse = {
+  status: 'success',
+  data: { userId: '123', name: 'Alice' }
+  // Missing: metadata that downstream code uses
+};
+
+// Later: breaks when code accesses response.metadata.requestId
+```
+
+**Why this is wrong:**
+- **Partial mocks hide structural assumptions** - You only mocked fields you know about
+- **Downstream code may depend on fields you didn't include** - Silent failures
+- **Tests pass but integration fails** - Mock incomplete, real API complete
+- **False confidence** - Test proves nothing about real behavior
+
+**The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
+
+**The fix:**
+```typescript
+// ✅ GOOD: Mirror real API completeness
+const mockResponse = {
+  status: 'success',
+  data: { userId: '123', name: 'Alice' },
+  metadata: { requestId: 'req-789', timestamp: 1234567890 }
+  // All fields real API returns
+};
+```
+
+### Gate Function
+
+```
+BEFORE creating mock responses:
+  Check: "What fields does the real API response contain?"
+
+  Actions:
+    1. Examine actual API response from docs/examples
+    2. Include ALL fields system might consume downstream
+    3. Verify mock matches real response schema completely
+
+  Critical:
+    If you're creating a mock, you must understand the ENTIRE structure
+    Partial mocks fail silently when code depends on omitted fields
+
+  If uncertain: Include all documented fields
+```
+
+## Anti-Pattern 5: Integration Tests as Afterthought
+
+**The violation:**
+```
+✅ Implementation complete
+❌ No tests written
+"Ready for testing"
+```
+
+**Why this is wrong:**
+- Testing is part of implementation, not optional follow-up
+- TDD would have caught this
+- Can't claim complete without tests
+
+**The fix:**
+```
+TDD cycle:
+1. Write failing test
+2. Implement to pass
+3. Refactor
+4. THEN claim complete
+```
+
+## When Mocks Become Too Complex
+
+**Warning signs:**
+- Mock setup longer than test logic
+- Mocking everything to make test pass
+- Mocks missing methods real components have
+- Test breaks when mock changes
+
+**your human partner's question:** "Do we need to be using a mock here?"
+
+**Consider:** Integration tests with real components often simpler than complex mocks
+
+## TDD Prevents These Anti-Patterns
+
+**Why TDD helps:**
+1. **Write test first** → Forces you to think about what you're actually testing
+2. **Watch it fail** → Confirms test tests real behavior, not mocks
+3. **Minimal implementation** → No test-only methods creep in
+4. **Real dependencies** → You see what the test actually needs before mocking
+
+**If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
+
+## Quick Reference
+
+| Anti-Pattern | Fix |
+|--------------|-----|
+| Assert on mock elements | Test real component or unmock it |
+| Test-only methods in production | Move to test utilities |
+| Mock without understanding | Understand dependencies first, mock minimally |
+| Incomplete mocks | Mirror real API completely |
+| Tests as afterthought | TDD - tests first |
+| Over-complex mocks | Consider integration tests |
+
+## Red Flags
+
+- Assertion checks for `*-mock` test IDs
+- Methods only called in test files
+- Mock setup is >50% of test
+- Test fails when you remove mock
+- Can't explain why mock is needed
+- Mocking "just to be safe"
+
+## The Bottom Line
+
+**Mocks are tools to isolate, not things to test.**
+
+If TDD reveals you're testing mock behavior, you've gone wrong.
+
+Fix: Test real behavior or question why you're mocking at all.

package/vendor/skills/forge/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: verification-before-completion
+description: Forge — verify before claiming done. Internal skill; read via forge orchestrator.
+---
+
+# Verification Before Completion
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always. Violating the letter of this rule is violating the spirit of this rule — it applies to exact phrases, paraphrases, and any wording implying success.
+
+## Forge — coordinator verify phase
+
+Three tiers: [test-strategy.md](../../references/test-strategy.md).
+
+**During implement:** implementers use tier 1 (scoped TDD) and tier 2 (narrow task evidence in `test-evidence.md`).
+
+**During verify:**
+
+1. **Audit** tier 2 evidence per task — exit code, pass summary, reviewer approvals. Do **not** re-run tier 2 commands.
+2. **Run tier 3 once** — fresh full workspace test per affected workspace (plus consumer workspaces if contracts changed). Save to `verify-evidence.md`.
+3. **Runtime wiring audit** — for each capability requirement, name the production caller. Library-only / stub / false success → incomplete. See [runtime-integrity.md](../../references/runtime-integrity.md).
+4. **E2E-or-BLOCKED** — one real fixture path through each critical live entry point, or an explicit `BLOCKED` list in `verify-evidence.md`. Do not claim complete while checkboxing around missing E2E.
+5. Cite tier 3 + wiring/E2E evidence when claiming the implementation passes.
+
+Re-run tier 3 only when it failed, coordinator edited code after verify evidence, reviewers flagged gaps, or the user asks. Per-task tier 2 runs **are** evidence for task-scoped claims; tier 3 **is** evidence for "full workspace passes." Do not duplicate tier 2 at verify; do not skip tier 3 because tier 2 passed; never run full workspace per implement task.
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+Before claiming any status or expressing satisfaction ("Done!", "Great!", "should work"):
+
+1. **IDENTIFY** the command that proves the claim
+2. **RUN** it fresh and complete
+3. **READ** full output — exit code, failure count
+4. **VERIFY** the output confirms the claim; if not, state the actual status with evidence
+5. Only then make the claim, **with** the evidence
+
+Skip any step = lying, not verifying.
+
+## What each claim requires
+
+| Claim | Requires | Not sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test of original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green verified (revert fix → must fail → restore → pass) | Test passes once |
+| Agent completed | VCS diff shows the changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist vs **capability specs** + named runtime owner per REQ | Tests passing; plan/task checkboxes alone |
+| Change complete | Tier 3 + wiring audit + E2E fixture path (or explicit `BLOCKED`) | Green suite with stub handlers / unwired libraries |
+
+## Red flags — stop and run the verification
+
+"Should / probably / seems to" · satisfaction before evidence · committing or moving to the next task unverified · trusting an agent's success report · partial checks ("linter passed" ≠ build) · "I'm confident" (confidence ≠ evidence) · "just this once" · tired and wanting the work over.

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

@@ -0,0 +1,53 @@
+# Final implementation reviewer
+
+Review the **entire** Forge session implementation against the plan **and**
+the capability specs. See [references/runtime-integrity.md](../references/runtime-integrity.md).
+
+## Plan source
+
+{PLAN_REFERENCE}
+
+## Capability specs (source of truth)
+
+{CAPABILITY_SPECS_REFERENCE}
+
+## Tasks completed
+
+{TASK_SUMMARY}
+
+## Scope
+
+All files changed in this session (use git diff or explicit list):
+
+{CHANGED_FILES}
+
+## Spec-to-runtime trace (required)
+
+For **each** requirement in the change's capability specs, name the
+**production caller** (worker job kind, HTTP endpoint, CLI command, scheduled
+job, …) that invokes the implementing code. Cross-check against `spine.json`
+(`forge spine check`) — every capability row must be wired, not library-only.
+
+- Library-only / no production caller → **`NOT READY`**
+- Stub handler / false success / enqueueable-but-unhandled kind → **`NOT READY`**
+- Job kind on the product surface that is neither wired end-to-end nor deleted → **`NOT READY`**
+- 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)
+
+`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.
+
+- No product-loop section and no `BLOCKED` → **`NOT READY`**
+- `BLOCKED` present → **`NOT READY`** (honest, but not READY)
+- Unresolved deferrals in `forge defer list` → **`NOT READY`**
+
+## Verdict
+
+- **READY** — every capability has a runtime owner, product loop evidenced, tests evidence real outcomes, no critical gaps
+- **NOT READY** — list blockers (prefer runtime-integrity and missing wiring first)
+
+Do not approve if tests were not run, **`test-evidence.md` is missing**, tasks remain unchecked, or any claimed capability is library-only / stubbed / false-succeeding. Task checkboxes at 100% do **not** override a broken spine.

package/vendor/skills/forge/subagents/implementer-prompt.md

@@ -0,0 +1,38 @@
+# Implementer subagent brief
+
+You are the **implementer** for one Forge task. You receive only this brief — no chat history.
+
+## Task
+
+{TASK_TITLE}
+
+{TASK_BODY}
+
+## Files
+
+{FILE_LIST}
+
+## Requirements / spec excerpt
+
+{SPEC_EXCERPT}
+
+## Forge constraints
+
+- Read and follow [references/tdd-core.md](./references/tdd-core.md) before any production code (full TDD skill only if stuck).
+- **No** `git commit` or `git push` unless the user explicitly asked in the current message.
+- **Testing tiers:** tier 1 = scoped test file/pattern per red/green cycle; tier 2 = narrowest command proving this task. **Do not** run the full workspace suite unless this task touches shared contracts or the brief says so — that is tier 3 and runs once at verify.
+- Include **command, exit code, and pass/fail summary** for tier 2 in your report (coordinator saves to `test-evidence.md`).
+- Minimal diff; match existing style; trace ecosystem consumers if contracts change.
+
+## Runtime integrity (hard)
+
+Read [references/runtime-integrity.md](../references/runtime-integrity.md). Honor these without exception:
+
+- **No stub-with-success.** Do not implement a handler that only logs / bumps progress / marks succeeded. Unwired kinds must fail closed or not be exposed.
+- **Name the runtime caller.** If you add library code, report which production path (job kind, endpoint, CLI) invokes it. If nothing calls it yet, end with `DONE_WITH_CONCERNS` and say so — do not pretend the capability is done.
+- **Tests must fail on a no-op.** Assert domain side effects, not ceremony.
+- If this brief tells you a stub is OK or to “wire later,” **reject the brief**: reply `NEEDS_CONTEXT` / `BLOCKED` and ask the coordinator to restore full scope or get user approval to shrink it.
+
+## Report status
+
+End with one of: `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, `BLOCKED` plus details.

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

@@ -0,0 +1,61 @@
+# Task reviewer (spec compliance + code quality)
+
+You review one Forge task in a single pass. No chat history — only this packet.
+
+## What was requested (task / plan excerpt)
+
+{PLAN_OR_SPEC_EXCERPT}
+
+## Capability spec excerpt (source of truth)
+
+{CAPABILITY_SPEC_EXCERPT}
+
+Capability specs beat narrow task wording when they conflict. See
+[references/runtime-integrity.md](../references/runtime-integrity.md).
+
+## What was implemented (implementer's own summary)
+
+{IMPLEMENTER_SUMMARY}
+
+## Changed files / diff
+
+{FILE_LIST}
+
+Diff range: {DIFF_RANGE}   <!-- e.g. `git diff` (uncommitted) or BASE..HEAD -->
+
+**Read the actual code.** The summary above was written by the party under review — it is a map, not evidence. Read the changed files (or the diff range) before any verdict; verify each spec requirement against what the code does, not what the summary says it does.
+
+## Check — spec compliance first, then quality
+
+**Spec compliance** (gate — check before quality):
+
+- Every requirement in the **capability** excerpt is implemented; nothing important missing
+- No unrequested scope (extra flags, features, refactors not in the plan)
+- Be strict on contract/API behaviour; pragmatic on internal refactors that match the plan
+
+**Runtime integrity — REJECT if any of:**
+
+- Success path has no domain side effects required by the capability
+- Tests would still pass with a no-op handler (ceremony-only evidence)
+- API / UI can enqueue or trigger a job kind / path the runtime cannot truly execute
+- UI / consumers depend on data nothing in the production path writes
+- Spec requirement has a library but no named runtime owner (job kind, endpoint, CLI, …)
+- 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)
+
+**Code quality:**
+
+- Simplicity — no over-engineering
+- Surgical diff — no unrelated edits
+- Error handling — no silent failures
+- Tests — meaningful coverage for behaviour changes; **`test-evidence.md`** (tier 2) present with exit code `0` and pass summary; evidence is **narrow** unless task required full workspace
+- Ecosystem — dependents updated if contracts changed
+- AGENTS.md coding guidelines
+
+## Verdict
+
+- **APPROVED** — capability met, runtime owner present, quality acceptable
+- **REJECTED** — list spec gaps and runtime-integrity failures first, then quality issues classified Critical / Important / Minor
+
+Spec gaps, runtime-integrity failures, and Critical/Important quality issues must be fixed before the task is marked complete.

package/vendor/skills/git-resolve-adr-conflict/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: git-resolve-adr-conflict
+description: >-
+  Git-scoped resolution of duplicate ADR number collisions after a coworker
+  commits the same sequential number first. Renames the local ADR file to the
+  next free number, updates its internal ADR-NNNN references, merges the ADR
+  README by keeping all HEAD table rows, renumbering only the local row from the
+  ======= side, and deleting every conflict marker, patches
+  openspec/changes/archive/**/proposal.md backlinks that still point at the old
+  ADR path, then git add to mark conflicts resolved. Git commands allowed are
+  git mv and git add (ADR dir and touched archive proposal.md only). Use when
+  the ADR README has merge conflict markers, two NNNN-*.md files share the same
+  prefix, or the user says git resolve ADR conflict / duplicate ADR number.
+disable-model-invocation: true
+---
+
+# Git: resolve ADR number conflict
+
+When two authors pick the same ADR number almost simultaneously, the remote
+commit wins the number. **Renumber yours** — never recycle or overwrite a
+committed ADR.
+
+## Project config
+
+Read **`.forge/config.json`**:
+
+```json
+{ "adr": { "enabled": true, "dir": "docs/adr", "decisionsDoc": "docs/decisions.md" } }
+```
+
+Use **`{adrDir}`** = `adr.dir` (default `docs/adr`). If `adr.enabled` is `false`,
+stop — this skill does not apply.
+
+## Scope (strict)
+
+| In scope | Out of scope |
+| -------- | ------------ |
+| Files under `{adrDir}/` | Implementation code, other docs |
+| `openspec/changes/archive/**/proposal.md` — ADR backlink only | Other files under `openspec/` |
+| `git mv` to rename the local ADR file | `git commit`, `git merge`, `git pull`, `git push` |
+| `git add` on touched `{adrDir}/` and archive `proposal.md` paths | `git add` on any other path |
+| Fix conflict markers in `{adrDir}/README.md` | Editing archive `design.md`, `tasks.md`, specs |
+
+## When to run
+
+- `{adrDir}/README.md` contains `<<<<<<<` / `=======` / `>>>>>>>` around table rows
+- Two `{adrDir}/NNNN-*.md` files share the same four-digit prefix (different slugs)
+- User reports "my ADR number was taken" after pulling or rebasing
+
+## Workflow
+
+```
+Task progress:
+- [ ] Detect collision and identify the local ADR
+- [ ] Compute next free ADR number
+- [ ] git mv rename local ADR file
+- [ ] Update ADR body (title + ADR-NNNN references)
+- [ ] Resolve {adrDir}/README.md — HEAD rows + your row renumbered; no markers left
+- [ ] git add — mark README conflict resolved
+- [ ] Patch archive proposal.md backlinks (old ADR number / path)
+- [ ] git add — stage updated proposal.md files
+- [ ] Verify
+```
+
+### 1. Detect collision and identify the local ADR
+
+```bash
+git status --porcelain {adrDir}/
+git ls-files {adrDir}/
+```
+
+**Local ADR (yours)** — untracked (`??`) / added (`A`), or the `>>>>>>>` side of a
+README conflict. **Committed ADR (coworker's)** — tracked and HEAD side.
+
+Record **`old_padded`** (four-digit prefix) and **`slug`** (filename after `NNNN-`).
+
+### 2. Compute next free ADR number
+
+Use the **higher** of HEAD README table max and on-disk `NNNN-*.md` max, then +1.
+Zero-pad to 4 digits. Never reuse a number that already exists.
+
+### 3. Rename with git mv
+
+```bash
+git mv {adrDir}/<old_padded>-<slug>.md {adrDir}/<next_padded>-<slug>.md
+```
+
+### 4. Update the ADR file body
+
+1. H1 `# NNNN.` → `# <next_padded>.`
+2. Replace every `ADR-<old>` with `ADR-<next_padded>`
+3. Do not change decision text unless it embeds the wrong number
+
+### 5. Resolve `{adrDir}/README.md`
+
+For each conflict block:
+
+1. Keep every table row from the `<<<<<<< HEAD` side verbatim
+2. Keep your row from the `=======` … `>>>>>>>` side, changing **only** the `#`
+   column to `<next_padded>`
+3. Delete every conflict marker
+4. Order: HEAD rows first, then your renumbered row(s)
+
+```bash
+rg '<<<<<<<|=======|>>>>>>>' {adrDir}/README.md
+```
+
+Must print **no matches**.
+
+### 6–8. Stage and patch backlinks
+
+```bash
+git add {adrDir}/README.md {adrDir}/<next_padded>-<slug>.md
+rg -l "ADR-<old_padded>\\b|<old_padded>-<slug>\\.md" openspec/changes/archive/
+```
+
+In matching `proposal.md` files: update `ADR-NNNN` and filename segments only;
+preserve the relative path prefix to `{adrDir}`. Then `git add` those proposals.
+
+### 9. Verify
+
+```bash
+git status {adrDir}/ openspec/changes/archive/
+```
+
+Expect no unmerged README, no duplicate `NNNN-` prefixes, no stale
+`ADR-<old_padded>` for your slug.
+
+## Output
+
+Report old → new path, new number, README merge summary, patched proposals.
+Do **not** commit unless the user explicitly asks.