@warpgogol/forge 0.3.1

package/os/rfc/rfc-0000-template.md

@@ -0,0 +1,222 @@
+---
+id: RFC-0000
+title: "Short imperative title (e.g. Add structure.validate command)"
+status: draft
+# kind options: architecture | contract | command | policy | deprecation
+kind: architecture
+# scope options: app | workspace
+scope: workspace
+owners:
+  - architecture
+# Set by the deciding human together with the status change (RFC-0335).
+# Draft scaffolds must keep this empty; do not prefill a default identity.
+# Format: human:<handle> (agent:<id> reserved — see RFC-0335).
+# Default reviewer when none is specified by the operator: human:andrii-syrokomskyi
+reviewers: []
+createdAt: YYYY-MM-DD
+updatedAt: YYYY-MM-DD
+implementedAt:
+closedAt:
+supersedes: []
+supersededBy:
+amends: []
+amendedBy: []
+related:
+  # Reference DNA invariants, anti-patterns, spec docs, or other RFCs:
+  # - DNA-1
+  # - AP-3
+  # - RFC-0005
+  # - PAGE-MANDATORY-ARTIFACTS
+  # - COMPONENT-THREE-WAY-MIRROR
+# RFC-0331: DNA invariants this RFC implements, protects, or extends.
+# Required for architecture/contract RFCs created on or after 2026-07-07.
+# Entries must match ^DNA-\d+$ and exist in docs/architecture-dna.md.
+satisfies: []
+# RFC-0396: Traceability to a vendored spec node: "<spec-id>/<node-id>", e.g. "pbp/RFC-PBP-020".
+# Set by spec.materialize; leave commented for non-spec RFCs.
+# specRef:
+# RFC-0478: Platform versioning enforcement. Declares the SemVer delta this RFC
+# produces when implemented. Required for post-cutoff implemented RFCs (V-29).
+# Values: minor (Breaks-B, requires migrator), patch (safe), none (prose-only),
+# major (architectural, manually reserved). Default: patch.
+versionBump: patch
+commands:
+  proposed: []
+  added: []
+  changed: []
+  removed: []
+appsImpacted: []
+# List only packages actually impacted. Leave empty if unknown.
+packagesImpacted: []
+successSignals: []
+nonGoals: []
+# RFC-0268: OPTIONAL machine-checkable acceptance probes, executed on-demand
+# via `pnpm exec site-kernel run rfc.acceptance.run --id <this-rfc-id>` (never
+# automatically inside build pipelines). Closed probe vocabulary — see
+# docs/rfcs/rfc-0268-make-rfc-acceptance-criteria-machine-checkable.md.
+# acceptance:
+#   - probe: run
+#     command: "site-kernel run some.command.validate --app warpgogol-com"
+#     expect:
+#       exitCode: 0
+#   - probe: file-exists
+#     path: "packages/share/src/some-new-module.ts"
+#   - probe: command-registered
+#     name: "some.new.command"
+#   - probe: file-contains
+#     path: "AGENTS.md"
+#     pattern: "Some new governance paragraph"
+---
+
+# RFC-0000: Short imperative title
+
+## Context
+
+<!-- Why does this RFC exist?
+     Describe the observable gap, drift, or risk in the current system.
+     Reference Architecture DNA invariants, anti-patterns, or spec documents
+     that this RFC is meant to close or protect. -->
+
+## Problem
+
+<!-- What specific invariant is unprotected right now?
+     What relies on manual discipline instead of automated or documented enforcement?
+     Be concrete: reference file paths, DNA invariant IDs, or known failure modes. -->
+
+## Decision
+
+<!-- State the single decision being made.
+     One of:
+     - Introduce a new OS command or set of commands
+     - Add or change an architectural contract (page, component, semantic, brand, quality)
+     - Establish a new governance policy
+     - Deprecate or supersede an existing rule or command
+
+     Write it in present tense as if already decided:
+     "The kernel gains a `structure.validate` command that checks..."
+     not "We should add..." -->
+
+## Architectural fit
+
+<!-- How does this decision relate to existing building blocks?
+     Explain alignment with the following — skip any that are not relevant:
+     - Architecture DNA (which invariants does this enforce or protect?)
+     - Anti-Patterns (which patterns does this prevent?)
+     - Page Contracts (which page-level rules are formalized?)
+     - Component Contracts (which component-level rules are formalized?)
+     - Site OS operator model (command scope, module placement, pipeline integration)
+     - Scaling Playbook (does this apply uniformly across growth stages 1–4?) -->
+
+## Design
+
+### CLI surface
+
+<!-- Show the exact command(s) as a user would type them:
+
+```sh
+pnpm exec site-kernel run domain.command --app main
+pnpm exec site-kernel run domain.command --all --json
+```
+
+Describe flags, arguments, and scope (app | workspace).
+-->
+
+### TypeScript contracts
+
+<!-- Specify the key types and interfaces needed.
+     Do not write full implementation — write the minimum contract
+     that a developer or agent needs to understand the shape.
+
+```ts
+interface ExampleInput {
+  // ...
+}
+
+interface ExampleResult {
+  // ...
+}
+```
+-->
+
+### File system responsibilities
+
+<!-- Which files/directories does this touch or read?
+     Which files does this create, validate, or refuse to touch?
+
+| Path | Role |
+|---|---|
+| `src/pages/[lang]/**/*.astro` | Scanned for violations |
+| `docs/rfcs/index.json` | Updated by rfc.index.generate |
+-->
+
+### Output format
+
+<!-- Describe the --json output shape so agents can parse it reliably.
+
+```json
+{
+  "command": "domain.command",
+  "status": "fail",
+  "violations": [
+    { "file": "src/pages/de/legal.astro", "rule": "missing-schema", "message": "..." }
+  ]
+}
+```
+-->
+
+### Failure modes
+
+<!-- What does the command do when it finds violations?
+     Does it exit non-zero? Does it log warnings only?
+     What is the behavior difference between --json and pretty output?
+     Are there any rules where the command should warn rather than fail? -->
+
+## Rollout
+
+<!-- Describe the adoption path — not a short-term wave, but a durable rollout strategy:
+
+- Default behavior on first introduction (fail-hard vs. warn vs. opt-in)
+- How existing apps adopt without a flag day (e.g., --strict mode, grace period)
+- How new apps automatically comply from day one
+- Deprecation path if this supersedes an existing command
+- How this integrates into the `build.check` or other standard pipelines
+-->
+
+## Alternatives considered
+
+<!-- What else was considered and why was it rejected?
+     Be brief but honest — this section prevents re-litigating old decisions. -->
+
+## Risks
+
+<!-- Technical, organizational, or agent-facing risks.
+     Include: performance impact, false positive rate, maintenance burden,
+     risk of agents misinterpreting this RFC. -->
+
+## Acceptance criteria
+
+- [ ] TypeScript types and interfaces defined in the relevant package
+- [ ] CLI command registered with correct name and scope
+- [ ] `--json` output format documented and stable
+- [ ] Integrated into appropriate pipeline (`build.check` or standalone)
+- [ ] Existing apps pass without changes (or migration path is documented)
+- [ ] `AGENTS.md` updated where agent behavior rules changed
+- [ ] Relevant Architecture DNA or spec docs link to this RFC
+- [ ] `rfc.validate` passes on this file before merging
+
+## Implementation notes for agents
+
+<!-- Rules that govern how AI agents interact with this RFC.
+     Be explicit. Agents read this section for behavioral policy.
+
+- Agents MAY implement code changes ONLY when this RFC has status: accepted (or implemented).
+- Agents MAY transition this RFC from `accepted` to `implemented` per RFC-0224 preconditions; reference this RFC ID in commits.
+- For RFCs created on or after 2026-07-07 with acceptance probes: before stamping `implemented`, run
+  `site-kernel run rfc.verification.emit --id <this-rfc-id>` and commit the evidence file
+  in the same commit (RFC-0330 amended transition precondition).
+- Agents MUST NOT weaken or remove enforcement rules established by this RFC
+  without a new RFC that supersedes it.
+- If implementation reveals an invariant conflict, run
+  `site-kernel run rfc.supersede.propose --id <this-rfc-id> --reason "..." --invariant "DNA-N"`
+  instead of working around it (RFC-0334).
+-->

package/package.json

@@ -0,0 +1,262 @@
+{
+  "name": "@warpgogol/forge",
+  "version": "0.3.1",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "description": "Framework for documenting and implementing ideas — RFC/ADR governance, skills, and project bootstrapping.",
+  "keywords": [
+    "rfc",
+    "adr",
+    "governance",
+    "skills",
+    "ai-agent",
+    "documentation",
+    "framework"
+  ],
+  "homepage": "https://github.com/syrokomskyi/warpgogol-4#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syrokomskyi/warpgogol-4.git",
+    "directory": "packages/forge"
+  },
+  "bugs": {
+    "url": "https://github.com/syrokomskyi/warpgogol-4/issues"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "forge": "./bin/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./types": {
+      "types": "./src/types.ts",
+      "default": "./src/types.ts"
+    },
+    "./utils": {
+      "types": "./src/utils/index.ts",
+      "default": "./src/utils/index.ts"
+    },
+    "./config": {
+      "types": "./src/config/forge-config.ts",
+      "default": "./src/config/forge-config.ts"
+    },
+    "./os/core": {
+      "types": "./os/core/core.module.ts",
+      "default": "./os/core/core.module.ts"
+    },
+    "./os/compass": {
+      "types": "./os/compass/index.ts",
+      "default": "./os/compass/index.ts"
+    },
+    "./os/naming": {
+      "types": "./os/naming/index.ts",
+      "default": "./os/naming/index.ts"
+    },
+    "./os/naming-module": {
+      "types": "./os/naming/naming.module.ts",
+      "default": "./os/naming/naming.module.ts"
+    },
+    "./os/rfc": {
+      "types": "./os/rfc/index.ts",
+      "default": "./os/rfc/index.ts"
+    },
+    "./os/rfc-module": {
+      "types": "./os/rfc/rfc.module.ts",
+      "default": "./os/rfc/rfc.module.ts"
+    },
+    "./os/werkstatt": {
+      "types": "./os/werkstatt/index.ts",
+      "default": "./os/werkstatt/index.ts"
+    },
+    "./os/workflow": {
+      "types": "./os/workflow/index.ts",
+      "default": "./os/workflow/index.ts"
+    },
+    "./os/workflow-module": {
+      "types": "./os/workflow/workflow.module.ts",
+      "default": "./os/workflow/workflow.module.ts"
+    },
+    "./os/spec-module": {
+      "types": "./os/spec/spec.module.ts",
+      "default": "./os/spec/spec.module.ts"
+    },
+    "./os/adr": {
+      "types": "./os/adr/index.ts",
+      "default": "./os/adr/index.ts"
+    },
+    "./os/adr-module": {
+      "types": "./os/adr/adr.module.ts",
+      "default": "./os/adr/adr.module.ts"
+    },
+    "./os/plan": {
+      "types": "./os/plan/index.ts",
+      "default": "./os/plan/index.ts"
+    },
+    "./os/plan-module": {
+      "types": "./os/plan/plan.module.ts",
+      "default": "./os/plan/plan.module.ts"
+    },
+    "./os/audit": {
+      "types": "./os/audit/index.ts",
+      "default": "./os/audit/index.ts"
+    },
+    "./os/audit-module": {
+      "types": "./os/audit/audit.module.ts",
+      "default": "./os/audit/audit.module.ts"
+    },
+    "./os/session": {
+      "types": "./os/session/index.ts",
+      "default": "./os/session/index.ts"
+    },
+    "./os/session-module": {
+      "types": "./os/session/session.module.ts",
+      "default": "./os/session/session.module.ts"
+    },
+    "./os/mission": {
+      "types": "./os/mission/index.ts",
+      "default": "./os/mission/index.ts"
+    },
+    "./os/mission-module": {
+      "types": "./os/mission/mission.module.ts",
+      "default": "./os/mission/mission.module.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "bin/cli.js",
+    "skills/",
+    "profiles/",
+    "os/rfc/rfc-0000-template.md",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "pnpm exec tsc -p tsconfig.json",
+    "build:check": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "pnpm run clean && pnpm run build && node scripts/publish-check.mjs",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "fast-check": "^4.9.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/src/index.js",
+    "types": "./dist/src/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/src/index.d.ts",
+        "default": "./dist/src/index.js"
+      },
+      "./types": {
+        "types": "./dist/src/types.d.ts",
+        "default": "./dist/src/types.js"
+      },
+      "./utils": {
+        "types": "./dist/src/utils/index.d.ts",
+        "default": "./dist/src/utils/index.js"
+      },
+      "./config": {
+        "types": "./dist/src/config/forge-config.d.ts",
+        "default": "./dist/src/config/forge-config.js"
+      },
+      "./os/core": {
+        "types": "./dist/os/core/core.module.d.ts",
+        "default": "./dist/os/core/core.module.js"
+      },
+      "./os/compass": {
+        "types": "./dist/os/compass/index.d.ts",
+        "default": "./dist/os/compass/index.js"
+      },
+      "./os/naming": {
+        "types": "./dist/os/naming/index.d.ts",
+        "default": "./dist/os/naming/index.js"
+      },
+      "./os/naming-module": {
+        "types": "./dist/os/naming/naming.module.d.ts",
+        "default": "./dist/os/naming/naming.module.js"
+      },
+      "./os/rfc": {
+        "types": "./dist/os/rfc/index.d.ts",
+        "default": "./dist/os/rfc/index.js"
+      },
+      "./os/rfc-module": {
+        "types": "./dist/os/rfc/rfc.module.d.ts",
+        "default": "./dist/os/rfc/rfc.module.js"
+      },
+      "./os/werkstatt": {
+        "types": "./dist/os/werkstatt/index.d.ts",
+        "default": "./dist/os/werkstatt/index.js"
+      },
+      "./os/workflow": {
+        "types": "./dist/os/workflow/index.d.ts",
+        "default": "./dist/os/workflow/index.js"
+      },
+      "./os/workflow-module": {
+        "types": "./dist/os/workflow/workflow.module.d.ts",
+        "default": "./dist/os/workflow/workflow.module.js"
+      },
+      "./os/spec-module": {
+        "types": "./dist/os/spec/spec.module.d.ts",
+        "default": "./dist/os/spec/spec.module.js"
+      },
+      "./os/adr": {
+        "types": "./dist/os/adr/index.d.ts",
+        "default": "./dist/os/adr/index.js"
+      },
+      "./os/adr-module": {
+        "types": "./dist/os/adr/adr.module.d.ts",
+        "default": "./dist/os/adr/adr.module.js"
+      },
+      "./os/plan": {
+        "types": "./dist/os/plan/index.d.ts",
+        "default": "./dist/os/plan/index.js"
+      },
+      "./os/plan-module": {
+        "types": "./dist/os/plan/plan.module.d.ts",
+        "default": "./dist/os/plan/plan.module.js"
+      },
+      "./os/audit": {
+        "types": "./dist/os/audit/index.d.ts",
+        "default": "./dist/os/audit/index.js"
+      },
+      "./os/audit-module": {
+        "types": "./dist/os/audit/audit.module.d.ts",
+        "default": "./dist/os/audit/audit.module.js"
+      },
+      "./os/session": {
+        "types": "./dist/os/session/index.d.ts",
+        "default": "./dist/os/session/index.js"
+      },
+      "./os/session-module": {
+        "types": "./dist/os/session/session.module.d.ts",
+        "default": "./dist/os/session/session.module.js"
+      },
+      "./os/mission": {
+        "types": "./dist/os/mission/index.d.ts",
+        "default": "./dist/os/mission/index.js"
+      },
+      "./os/mission-module": {
+        "types": "./dist/os/mission/mission.module.d.ts",
+        "default": "./dist/os/mission/mission.module.js"
+      }
+    }
+  }
+}

package/profiles/astro-typescript-turborepo.yaml

@@ -0,0 +1,144 @@
+schema: forge/stack-profile@1
+id: astro-typescript-turborepo
+displayName: Astro + TypeScript + Turborepo
+detect:
+  anyOf:
+    - astro.config.*
+    - tsconfig.json
+workspace:
+  dirs:
+    - sites
+    - packages
+    - services
+    - scripts
+  files:
+    - path: pnpm-workspace.yaml
+      content: |
+        packages:
+          - "sites/*"
+          - "packages/*"
+          - "services/*"
+    - path: turbo.json
+      content: |
+        {
+          "$schema": "https://turbo.build/schema.json",
+          "tasks": {
+            "build": {
+              "dependsOn": ["^build"],
+              "outputs": ["dist/**"]
+            },
+            "build:check": {
+              "dependsOn": ["^build:check"]
+            },
+            "test": {
+              "dependsOn": ["^build:check"]
+            }
+          }
+        }
+    - path: tsconfig.base.json
+      content: |
+        {
+          "compilerOptions": {
+            "target": "ESNext",
+            "module": "ESNext",
+            "moduleResolution": "bundler",
+            "strict": true,
+            "esModuleInterop": true,
+            "skipLibCheck": true,
+            "forceConsistentCasingInFileNames": true
+          }
+        }
+    - path: .gitignore
+      content: |
+        node_modules
+        dist
+        .turbo
+        .cache
+        operator-profile.md
+    - path: package.json
+      content: |
+        {
+          "name": "__PROJECT_NAME__",
+          "version": "0.1.0",
+          "private": true,
+          "type": "module",
+          "engines": {
+            "node": ">=22"
+          },
+          "scripts": {
+            "clean": "node scripts/clean.mjs",
+            "format": "prettier --write .",
+            "format:check": "prettier --check .",
+            "build": "turbo run build",
+            "build:check": "turbo run build:check",
+            "test": "turbo run test",
+            "upgrade-packages": "pnpm -r up"
+          }
+        }
+    - path: scripts/clean.mjs
+      content: |
+        import { readdir, rm } from "node:fs/promises";
+        import { join } from "node:path";
+        import { fileURLToPath } from "node:url";
+
+        const TARGETS = new Set(["node_modules", ".turbo", "dist", ".astro", ".cache", ".wrangler"]);
+
+        const repoRoot = join(fileURLToPath(import.meta.url), "..", "..");
+
+        async function walk(dir, toDelete) {
+          const entries = await readdir(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            const name = entry.name;
+            const fullPath = join(dir, name);
+            if (TARGETS.has(name)) {
+              toDelete.push(fullPath);
+              continue;
+            }
+            await walk(fullPath, toDelete);
+          }
+        }
+
+        const toDelete = [];
+        await walk(repoRoot, toDelete);
+
+        if (toDelete.length === 0) {
+          console.log("Nothing to clean.");
+          process.exit(0);
+        }
+
+        await Promise.all(toDelete.map((p) => rm(p, { recursive: true, force: true })));
+
+        for (const p of toDelete) {
+          console.log("deleted", p.replace(repoRoot + "/", ""));
+        }
+
+        console.log(`Cleaned ${toDelete.length} directories.`);
+install:
+  - pnpm add -D typescript turbo @warpgogol/forge prettier
+firstWorkspace:
+  path: sites/my-site
+  files:
+    - path: package.json
+      content: |
+        {
+          "name": "my-site",
+          "version": "0.1.0",
+          "private": true,
+          "type": "module",
+          "scripts": {
+            "build:check": "pnpm exec tsc -p tsconfig.json --noEmit",
+            "test": "vitest run --passWithNoTests"
+          }
+        }
+    - path: tsconfig.json
+      content: |
+        {
+          "extends": "../tsconfig.base.json",
+          "compilerOptions": {
+            "outDir": "./dist"
+          }
+        }
+  install:
+    - pnpm add astro
+    - pnpm add -D vitest