@warpgogol/forge 0.4.0 → 0.5.0

package/skills/shared/grilling/learned-principles.md

@@ -10,3 +10,17 @@ Concrete principles distilled from past grilling sessions. Each principle has a
 - **confirmations:** <N>
 - **Added:** <date>
 -->
+
+### K-0001: Extend infrastructure before feature logic
+
+```knowledge-entry
+id: K-0001
+layer: L2
+created: 2026-08-03
+lastConfirmedAt: 2026-08-03
+confirmations: 1
+status: active
+```
+
+- **Condition:** Plan grilling reveals that a feature depends on a schema field, serializer entry, or validation path that doesn't exist in the underlying module yet.
+- **Recommended answer:** Add a separate plan step to extend the infrastructure (schema, serializer, validator) before any step that creates or reads the new field/path. Zod safeParse silently strips unknown fields; fixed-order serializers skip unknown fields. Without the extension step, data is silently lost.

package/skills/shared/grilling/qa-log.md

@@ -1,10 +1,109 @@
+<!-- knowledge-layer: L0 -->
+
 # Q&A Log (L0)
 
 Append-only log of questions asked and answers given during grilling sessions. Used for meta-analysis to distill recurring decision patterns.
 
-<!-- Entries are appended by the skill during each run. -->
-<!-- Format:
-## <date> — <context>
-- **Question:** <short question summary>
-- **Answer:** <operator's decision>
--->
+### K-0001: Entry format for L0/L1/L2 knowledge records
+
+```knowledge-entry
+id: K-0001
+layer: L0
+created: 2026-08-03
+status: active
+```
+
+- **Context:** 2026-08-03 — forge knowledge lifecycle RFC series (RFC-1..5)
+- **Question:** Entry format for L0/L1/L2 knowledge records?
+- **Answer:** Markdown files with per-entry YAML metadata blocks (human-readable, grep-able, parseable); soft migration for existing freeform entries.
+
+### K-0002: How to define and enforce layer token budgets
+
+```knowledge-entry
+id: K-0002
+layer: L0
+created: 2026-08-03
+status: active
+```
+
+- **Context:** 2026-08-03 — forge knowledge lifecycle RFC series (RFC-1..5)
+- **Question:** How to define and enforce layer token budgets?
+- **Answer:** Hard defaults in forge (L2 hot ~4KB, L1 warm ~8KB, L0 cold unbudgeted), optional override in forge.yaml bindings; warning on exceed, not error.
+
+### K-0003: Where does AI distillation L0→L1/L2 live
+
+```knowledge-entry
+id: K-0003
+layer: L0
+created: 2026-08-03
+status: active
+```
+
+- **Context:** 2026-08-03 — forge knowledge lifecycle RFC series (RFC-1..5)
+- **Question:** Where does AI distillation L0→L1/L2 live?
+- **Answer:** New skill fo-knowledge-distill alongside deterministic forge.skill.knowledge.compact command; code mutates metadata, agent distills meaning.
+
+### K-0004: Should .agents/memory/ be versioned in git
+
+```knowledge-entry
+id: K-0004
+layer: L0
+created: 2026-08-03
+status: active
+```
+
+- **Context:** 2026-08-03 — forge knowledge lifecycle RFC series (RFC-1..5)
+- **Question:** Should .agents/memory/ be versioned in git?
+- **Answer:** Hybrid — MEMORY.md (curated) versioned, daily logs git-ignored.
+
+### K-0005: Schema extension before logic that depends on new fields
+
+```knowledge-entry
+id: K-0005
+layer: L0
+created: 2026-08-03
+status: active
+```
+
+- **Context:** 2026-08-03 — grilling RFC-0663 plan (cross-skill knowledge promotion)
+- **Question:** RFC proposes a new metadata field (promotedFrom) but the underlying schema (RFC-0660) doesn't define it. Where should schema extension live in the plan?
+- **Answer:** Schema extension must be a separate step before any logic that creates or reads the field. Zod safeParse silently strips unknown fields; the serializer uses a fixed FIELD_ORDER array. Without extending both, the field is lost on parse and never written on serialize.
+
+### K-0006: Doctor check status for informational warnings
+
+```knowledge-entry
+id: K-0006
+layer: L0
+created: 2026-08-03
+status: active
+```
+
+- **Context:** 2026-08-03 — grilling RFC-0663 plan (knowledge-duplicate doctor check)
+- **Question:** RFC says "informational warnings, never affects exit status." Should the doctor check use status "pass" or "warn"?
+- **Answer:** Use "warn" when duplicates found, "pass" when none. Only "fail" affects exit status. "warn" makes duplicates visible in doctor summary (N warn(s)) and --json output, consistent with RFC-0661 SKILL-21 budget warnings. "pass" always would hide duplicates in the summary.
+
+### K-0007: Validating non-skill knowledge files in doctor
+
+```knowledge-entry
+id: K-0007
+layer: L0
+created: 2026-08-03
+status: active
+```
+
+- **Context:** 2026-08-03 — grilling RFC-0663 plan (shared knowledge layer validation)
+- **Question:** The shared knowledge layer file is not inside a skill directory (no SKILL.md). Existing checks (checkLegacyKnowledgeSections, checkKnowledgeBudgets) and forge.skill.validate (SKILL-19/SKILL-20) discover knowledge files only through the skill registry. How to validate it?
+- **Answer:** Add a dedicated checkSharedKnowledgeFile() in doctor.ts that parses the shared file via parseKnowledgeFile and checks SKILL-19 (schema validity) and SKILL-20 (id uniqueness) directly. A skill-wrapper would misrepresent the shared layer as a skill; skipping validation leaves schema violations undetected.
+
+### K-0008: Dogfood criterion when no real duplicates exist
+
+```knowledge-entry
+id: K-0008
+layer: L0
+created: 2026-08-03
+status: active
+```
+
+- **Context:** 2026-08-03 — grilling RFC-0663 plan (dogfood acceptance criterion)
+- **Question:** RFC requires "at least one real duplicate pair promoted end-to-end" but the current monorepo has very few L2 entries across skills. Real duplicates are unlikely. How to handle the dogfood criterion?
+- **Answer:** Conditional dogfood: run detection on the monorepo. If duplicates found, promote with operator approval. If none found, the detection pipeline running end-to-end (detection → doctor report → zero duplicates) serves as evidence. Promotion mechanics are verified by unit tests. Creating artificial test duplicates is not natural and would not test the real promotion path.

package/skills/shared/knowledge/learned-principles.md

@@ -0,0 +1,5 @@
+<!-- knowledge-layer: L2 -->
+
+# learned-principles.md (shared)
+
+Promoted cross-skill principles. Entries are added by `fo-knowledge-distill` under operator grilling — never edited directly. Each entry uses `shared/K-NNNN` as its citation id.

package/skills/shared/windows-ai-tooling/SKILL.md

@@ -3,7 +3,7 @@ name: windows-ai-tooling
 description: Bootstrap a Windows project for AI agents. Installs verified tools, generates .gitattributes, and emits a command allow-list for agent prompts. Run when starting a new project or when agents fail.
 invocation: user
 category: shared
-concerns: document-only
+concerns: code-mutation
 dependsOn: []
 languagePolicy: ref(PREFERENCES.md)
 ---
@@ -189,6 +189,159 @@ Report:
 - A copyable block with the agent prompt snippet.
 - A reminder that re-running this skill is useful when adding a new tool or onboarding a new machine.
 
+### 8. GitHub Actions CI (optional)
+
+If the project uses GitHub Actions, generate or update `.github/workflows/ci.yml` with the following Windows-specific guidance:
+
+#### Action versions
+
+Use the latest official actions with Node 24 runtime:
+
+- `actions/checkout@v5`
+- `actions/setup-node@v5`
+
+These versions use the Node 24 runtime that GitHub Actions now recommends. Older versions (`@v4` and below) run on the deprecated Node 20 runtime.
+
+#### Windows runner images
+
+Do not pin to `windows-latest` blindly — the image composition changes over time and a toolchain that worked yesterday may break today. If native compilation is critical, pin to a specific Windows image version (e.g. `windows-2022`) and verify the actual compiler version in CI output.
+
+Do not hardcode the path to Visual Studio and do not let tooling auto-select the newest installed version. Some `node-gyp` versions do not yet recognize Visual Studio 2026. For those, install Visual Studio Build Tools 2022 and constrain the toolset search to the `[17.0,18.0)` range:
+
+```yaml
+- name: Set up Build Tools 2022
+  run: |
+    $vsPath = & "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" `
+      -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 `
+      -property installationPath -version "[17.0,18.0)"
+    echo "VS_PATH=$vsPath" >> $env:GITHUB_ENV
+```
+
+Before installing dependencies, activate the Developer Command Prompt for the discovered Visual Studio in the same step so that `cl.exe` and the MSVC toolchain are on `PATH`:
+
+```yaml
+- name: Activate Developer Command Prompt
+  shell: cmd
+  run: |
+    call "%VS_PATH%\Common7\Tools\VsDevCmd.bat" -arch=x64 -host_arch=x64
+    pnpm install --frozen-lockfile
+```
+
+#### Native dependencies
+
+Native dependencies (SQLite drivers, `better-sqlite3`, `sharp`, `node-sass`, etc.) need CI testing on each target OS. A prebuilt binary may not exist for every Node version + OS + architecture combination — when it is missing, `node-gyp` falls back to source compilation and requires a working C++ compiler.
+
+Verify in CI that `pnpm install` succeeds without manual intervention on every OS in the matrix. If it fails, either:
+
+- Add `node-gyp` build prerequisites to the CI step (Build Tools + Developer Command Prompt), or
+- Pin to a Node version that has prebuilt binaries for all target platforms.
+
+#### Diagnostic step on Windows failure
+
+When a Windows CI job fails — especially during `pnpm install` or native compilation — add a diagnostic step that prints the toolchain versions. This is critical while the Windows image transitions to Visual Studio 2026 and `node-gyp` versions may not yet recognize it:
+
+```yaml
+- name: Diagnostics (on failure)
+  if: failure()
+  shell: pwsh
+  run: |
+    Write-Host "=== Node ==="
+    node --version
+    Write-Host "=== npm ==="
+    npm --version
+    Write-Host "=== pnpm ==="
+    pnpm --version
+    Write-Host "=== node-gyp ==="
+    npx node-gyp --version
+    Write-Host "=== MSVC ==="
+    & "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" `
+      -latest -products * -property displayName -version "[17.0,18.0)"
+    Write-Host "=== cl.exe ==="
+    where.exe cl 2>$null || Write-Host "cl.exe not found on PATH"
+    Write-Host "=== Python ==="
+    python --version 2>$null || Write-Host "Python not found"
+```
+
+The `if: failure()` condition ensures the step only runs when a previous step failed — it does not slow down successful runs. The output helps identify whether the failure is due to a missing compiler, wrong Visual Studio version, or a `node-gyp` incompatibility.
+
+#### Windows long paths
+
+If Windows is in the CI matrix, set `core.longpaths` **before** the checkout step via job-level env:
+
+```yaml
+jobs:
+  windows-ci:
+    runs-on: windows-2022
+    env:
+      GIT_CONFIG_COUNT: 1
+      GIT_CONFIG_KEY_0: core.longpaths
+      GIT_CONFIG_VALUE_0: "true"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+      # ...
+```
+
+Without this, `git clone` fails on repositories with file paths longer than 260 characters (common in monorepos with deeply nested `node_modules` or generated content trees).
+
+#### When to include Windows
+
+Windows CI catches important platform-specific issues (path lengths, native builds, line endings), but it requires separate configuration of native dependencies, compiler toolchain, and shell differences (PowerShell vs bash). Only add Windows to the CI matrix where the product genuinely supports or ships Windows artifacts — not "just in case".
+
+#### CI reliability patterns (all platforms)
+
+Apply these to every workflow, not just Windows:
+
+**Concurrency cancellation** — cancel superseded runs on PRs to save CI minutes and avoid cache thrashing:
+
+```yaml
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+```
+
+**Minimal permissions** — default GitHub Actions grants `contents: write`. Restrict to read-only at the workflow level; escalate per-job only where needed (e.g. changelog commit):
+
+```yaml
+permissions:
+  contents: read
+```
+
+**Job timeouts** — the default 6-hour timeout can exhaust CI limits on a hung install or test. Set `timeout-minutes` per job: 10–15 for lint/validate, 20–30 for build/test.
+
+**Deterministic timezone** — tests using `new Date()` produce different results depending on the runner's timezone. Set `TZ: UTC` at the job level to make timestamps deterministic across runs:
+
+```yaml
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      TZ: UTC
+```
+
+**Explicit shell** — on Windows the default shell is PowerShell, which breaks bash syntax. Steps using bash must declare `shell: bash`; Windows-specific steps should declare `shell: cmd` or `shell: pwsh`:
+
+```yaml
+- name: Run bash script
+  shell: bash
+  run: ./scripts/build.sh
+```
+
+#### Package-scoped commands
+
+Do not run package-level tools (test runners, linters, build commands) from the monorepo root. Run them via the package's own script or workspace context:
+
+```yaml
+# Good — scoped to the package
+- run: pnpm --filter <package-name> test
+
+# Bad — runs from root, may pick up wrong config
+- run: pnpm test
+```
+
+Ask: **"Настроить GitHub Actions CI для Windows? (Y/m/s)"**. Default **Y** if the project already has `.github/workflows/`; otherwise **s** (skip — the scaffolded CI template already includes Ubuntu-only CI).
+
 ## Constraints
 
 - Default to automatic execution (`Y`) for every step. Offer `m` (manual) and `s` (skip) only as explicit opt-outs.

package/skills/shared/writing-great-skills/SKILL.md

@@ -90,7 +90,7 @@ Use these to diagnose issues the user may be having with the skill.
 
 ## Cumulative knowledge pattern
 
-Skills that run repeatedly accumulate knowledge across sessions. The cumulative knowledge convention provides an opt-in three-layer reference pattern for this.
+Skills that run repeatedly accumulate knowledge across sessions. The cumulative knowledge convention provides an opt-in three-layer reference pattern (plus one shared cross-skill layer) for this.
 
 ### Knowledge frontmatter
 
@@ -116,6 +116,78 @@ Skills adopt 0, 1, 2, or 3 layers as needed — the pattern is adaptive, not man
 
 Not every skill needs all three. `grilling` uses L0 and L2 only (no fix patterns). A site-scanning skill may use all three.
 
+### Shared layer (L2, cross-skill)
+
+In addition to the three skill-local layers, there is a fourth tier: the **shared knowledge layer** at `packages/forge/skills/shared/knowledge/learned-principles.md`. This file holds promoted cross-skill principles with `shared/K-NNNN` identifiers.
+
+- **Detection**: `forge.doctor` reports cross-skill duplicate L2 entries via normalized-title matching (exact and bounded containment).
+- **Promotion**: `fo-knowledge-distill` executes promotions under operator grilling — the principle moves to the shared layer with summed confirmations and `promotedFrom` provenance; each skill-local copy is rewritten to a pointer entry (`promotedTo: shared/K-NNNN`, `status: superseded`).
+- **Consumption**: knowledge-adopting skills read the shared layer at run start and cite shared principles as `shared/K-NNNN`.
+- **Validation**: `forge.doctor` validates the shared layer file for schema validity and id uniqueness (it is not inside a skill directory, so `forge.skill.validate` does not reach it).
+- **npm portability**: the shared layer ships as an empty template — accumulated promotions are project-specific.
+
+### Entry format
+
+Each knowledge entry is a `### K-NNNN: title` heading followed by a `knowledge-entry` YAML metadata block and a markdown body:
+
+````markdown
+### K-0001: Skip non-project sessions
+
+```knowledge-entry
+id: K-0001
+layer: L1
+created: 2026-08-03
+status: active
+````
+
+**Situation:** ...
+
+**Action:** ...
+
+```
+
+#### Metadata schema
+
+| Field | Type | Required | Layers | Meaning |
+| --- | --- | --- | --- | --- |
+| `id` | `K-NNNN` | all | all | Unique 4-digit identifier within the file |
+| `layer` | `L0` \| `L1` \| `L2` | all | all | Knowledge layer |
+| `created` | `YYYY-MM-DD` | all | all | Date the entry was first written |
+| `lastConfirmedAt` | `YYYY-MM-DD` \| `null` | L2 only | L2 | Date of last operator confirmation |
+| `confirmations` | integer ≥ 0 | L2 only | L2 | Confirmation counter for autonomous application |
+| `expiresAt` | `YYYY-MM-DD` \| `null` | optional | all | Date after which the entry is stale |
+| `supersedes` | `K-NNNN[]` | optional | all | Entries this one replaces (must resolve in same file) |
+| `promotedTo` | `shared/K-NNNN` \| `null` | optional | all | Cross-file promotion target |
+| `promotedFrom` | `<skill>/K-NNNN[]` | optional | shared | Provenance — which skill-local entries were promoted into this shared entry |
+| `status` | `active` \| `stale` \| `superseded` \| `archived` | all | all | Lifecycle state |
+
+#### Layer-specific rules
+
+- **L0** (`qa-log.md`): `confirmations` and `lastConfirmedAt` are forbidden.
+- **L1** (`fix-patterns.md`): `confirmations` and `lastConfirmedAt` are forbidden.
+- **L2** (`learned-principles.md`): `confirmations` and `lastConfirmedAt` are required.
+
+#### Knowledge-adjacent files
+
+Files declared in `knowledge:` frontmatter that do not use `### K-NNNN:` headings and have no `<!-- knowledge-layer: ... -->` preamble are **knowledge-adjacent** — they are exempt from SKILL-19/SKILL-20. Examples: `forge-about.md`, `operator-profile-template.md`, `project-narrative-template.md`.
+
+#### Validation
+
+`forge.skill.validate` enforces:
+- **SKILL-19**: entry metadata schema validity (errors) and legacy section warnings (migration window).
+- **SKILL-20**: identifier uniqueness (`K-NNNN` format, no duplicates, `supersedes` references resolve, `promotedTo` format).
+- **SKILL-21**: hot (L2) and warm (L1) layer character budget warnings — warnings only, never build gates. Defaults: hot=4096, warm=8192. Override in `forge.yaml` under `bindings.knowledge.budgets`.
+
+`forge.doctor` reports legacy section counts and knowledge budget summaries as informational warnings.
+
+### Reading discipline
+
+When a skill declares `knowledge:` files, the skill body MUST include a one-line instruction telling the agent how to read them. Add this line to the skill's process section:
+
+> Read declared knowledge files at the start of each run, in declaration order. Apply only entries with `status: active`. Skip entries with `status: stale`, `superseded`, or `archived`.
+
+This ensures the agent knows to load and filter knowledge entries by lifecycle status, rather than blindly applying all entries including stale ones.
+
 ### Confidence progression
 
 L2 entries carry a `confirmations: N` counter. When confirmations reach threshold 3, the skill may apply the principle autonomously without asking the operator. Rejecting a recommended answer resets confirmations to 0. Autonomous application is context-dependent — the skill should re-evaluate if context changes.
@@ -130,3 +202,4 @@ L2 entries carry a `confirmations: N` counter. When confirmations reach threshol
 ### npm portability
 
 `@warpgogol/forge` is published to npm with `skills/` in the `files` array. Knowledge files ship as empty templates (header comments only). Forge's accumulated Q&A and learned principles are project-specific and should not leak to npm consumers. Each project accumulates its own knowledge locally after running `forge.create`.
+```