@warpgogol/forge 0.3.1 → 0.5.0

package/skills/meta/forge-bootstrap/SKILL.md

@@ -39,6 +39,7 @@ Interactive skill for configuring a freshly created forge project. Runs after `f
 - The skill never collects personal data as a separate interview before the first creation moment — personal data emerges naturally from the creative dialogue.
 - `operator-profile.md` is local and private — it is in `.gitignore` and is not committed to the repository. The operator can delete it at any time.
 - Gender is optional — the operator may decline to provide it. If declined, the skill uses gender-neutral addressing and notes the absence in `operator-profile.md`.
+- Form of address defaults to formal if the operator skips the question.
 - The skill never informs the operator about migration, version numbers, or upgrade mechanics — the silent version check in step 0 is invisible to the operator.
 - The skill never asks the operator for permission to migrate — if versions differ, migration runs automatically.
 
@@ -83,7 +84,7 @@ Accept the operator's choice and store it:
 
 The register controls whether the extended behavioral layer is included in `AGENTS.md`. Both registers receive the full core behavioral layer. The operator can change the register at any time via live operator feedback.
 
-### 3. Operator name and gender (new)
+### 3. Operator name, gender, and form of address (new)
 
 Ask the operator:
 
@@ -95,7 +96,18 @@ Then ask:
 
 If the operator declines to provide gender, use gender-neutral addressing and note the absence in `operator-profile.md` under `## Personal`.
 
-Store the operator's name and gender (or absence) in `operator-profile.md` under `## Personal`. These are the only personal data collected before the first creation moment.
+Then ask about the form of address:
+
+> Do you prefer informal or formal address? In some languages this means saying "you" in a familiar way (e.g. "ty" in Russian/Ukrainian, "du" in German) versus a more formal way (e.g. "vy" in Russian/Ukrainian, "Sie" in German). If you're not sure, formal is the safe default.
+
+Accept the operator's choice and store it:
+
+- In `PREFERENCES.md` as `formOfAddress: formal` or `formOfAddress: informal`.
+- In `operator-profile.md` under `## Register`.
+
+If the operator skips the question, default to `formOfAddress: formal`. The preference applies to all agent-generated text: chat messages, reports, suggestions, and skill output. The operator can change it at any time by editing `PREFERENCES.md`.
+
+Store the operator's name, gender (or absence), and form of address in `operator-profile.md` under `## Personal` and `## Register`. These are the only personal data collected before the first creation moment.
 
 ### 4. Verify forge project
 
@@ -161,7 +173,7 @@ The transplant mode performs real code migration via a migration-adapter registr
 
 6.7. **Build verification and error repair** — after post-setup, verify the transplanted project builds successfully:
 
-1.  Resolve the build command via `ref(forge.yaml bindings.commands.scopedBuild)`. If the binding is null (the migration adapter could not derive a build command from the source project), skip build verification with a note in the welcoming report and continue to the next step.
+1.  Resolve the build command via `ref(forge.yaml bindings.commands.produce)`. If the binding is null (the migration adapter could not derive a build command from the source project), skip build verification with a note in the welcoming report and continue to the next step.
 2.  Run the resolved build command and capture stdout/stderr. Set a timeout of 300 seconds (configurable); if the build does not complete in time, report the timeout in human language and continue.
 3.  Parse build output for:
     - Missing modules (TS2307: Cannot find module 'X')
@@ -225,6 +237,18 @@ The operator can choose to start one immediately or defer.
 
 If project analysis finds nothing recommendable (transplant of an empty or minimal project), the skill skips recommendations and proceeds to the first creation moment with a direct invitation to start creating.
 
+### 9.1. Hand-written AGENTS.md improvement proposals (transplant only)
+
+After project analysis, the skill checks existing hand-written `AGENTS.md` files in workspace directories (directories with a `package.json`). For each hand-written `AGENTS.md` (one without a generated marker), the skill checks for common forge conventions:
+
+- Does the file reference the root `AGENTS.md` for project-wide rules?
+- Does the file include workspace-type-appropriate guidance (app, package, service)?
+- Does the file contain a generated marker (it should not for hand-written files)?
+
+If improvement opportunities are found, the skill proposes them to the operator in creator-facing language (in `aiLanguage`). The operator confirms before any file is modified. Proposals are opt-in — the operator can decline all or select specific improvements.
+
+If no hand-written `AGENTS.md` files exist, or no improvement opportunities are found, this step is skipped silently.
+
 ### 10. First creation moment (new)
 
 After the welcoming report, the skill helps the operator create something real immediately — not a placeholder, not a test, but a first piece of their actual project.
@@ -327,7 +351,7 @@ The skill declares the following knowledge files in its `knowledge` frontmatter
 
 ### 14. Privacy
 
-`operator-profile.md` contains personal data: operator name, gender, project story, deep purpose, creative influences, target audience, writing voice. Gender is special category data under GDPR Article 9. To prevent accidental exposure:
+`operator-profile.md` contains personal data: operator name, gender, form of address, project story, deep purpose, creative influences, target audience, writing voice. Gender is special category data under GDPR Article 9. To prevent accidental exposure:
 
 - `operator-profile.md` is in `.gitignore` (added by scaffold profiles).
 - The skill informs the operator that `operator-profile.md` is local and private — it is not committed to the repository.

package/skills/meta/forge-bootstrap/operator-profile-template.md

@@ -15,6 +15,7 @@ This file is private and local to your project. It is not committed to the repos
 ## Register
 
 - **Communication register:** (business | creative — how you prefer the system to work with you)
+- **Form of address:** (formal | informal — how the system should address you in languages with a formal/informal distinction)
 
 ## Communication style
 

package/skills/meta/skill-create/SKILL.md

@@ -46,7 +46,7 @@ Before creating knowledge files, the agent analyzes the skill's knowledge domain
 
 3. **Which layers are needed?** Not every skill needs all three. `grilling` uses L0+L2 only. A site-scanning skill with all three layers is a good example. A skill with purely reactive error resolution may use L1+L2 only (no Q&A log).
 
-Present the analysis to the operator. If they confirm, create the knowledge files with header comments matching the chosen structure and add `knowledge:` to the frontmatter. See `writing-great-skills` § Cumulative knowledge pattern for the three-layer reference pattern and mutation contract.
+Present the analysis to the operator. If they confirm, create the knowledge files with header comments matching the chosen structure and add `knowledge:` to the frontmatter. See `writing-great-skills` § Cumulative knowledge pattern for the three-layer reference pattern, entry format, and mutation contract.
 
 ### 2. Scaffold
 

package/skills/shared/grilling/SKILL.md

@@ -13,7 +13,7 @@ knowledge:
 
 Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
 
-Read `learned-principles.md` (L2) at the start of each session to improve recommended answers. Principles with `confirmations >= 3` may be applied autonomously — but re-evaluate if context changes.
+Read `learned-principles.md` (L2) at the start of each session to improve recommended answers. Apply only entries with `status: active`; skip entries with `status: stale`, `superseded`, or `archived`. Principles with `confirmations >= 3` may be applied autonomously — but re-evaluate if context changes.
 
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
 

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`.
+```