Add Product/Forge separation audit

[IanFrelinger]

Overview

This PR adds a comprehensive audit document (docs/audits/2026-09-product-forge-separation.md) that analyzes the current Ashlar repository structure and proposes extraction of product-shaped code to a new Ashlar.Forge repository.

Strategic Context

Product Strategy:

• Ashlar Core = Unreal Engine (reusable runtime + admission system)
• Ashlar.Forge = Fortnite (adaptive app factory using Ashlar admission)
• Separation is essential to keep product concerns out of framework core

Audit Findings

The audit identifies ~15-20% of the current repository as product/application code that should be extracted:

High Priority Extractions

• Runtime Studio (apps/runtime-studio/) → Forge.Studio
• Application Surfaces (application/) → Forge.Surfaces (API + CLI)
• VS Code Extension (extensions/ashlar-vscode/) → forge-vscode

Additional Extractions

• Product samples & demos
• Autonomy spikes (spikes/autonomy-first-flight/)
• Product scaffolds (products/) — staging in Forge before individual repos

Stays in Core

• All src/ framework code (58 projects)
• Framework tests
• Minimal brick authoring samples
• Framework documentation

Key Proposals

1. Forge Repository Structure

Ashlar.Forge/
├── src/
│ ├── Forge.Studio/ (Runtime Studio)
│ ├── Forge.Surfaces/ (API + CLI)
│ ├── Forge.Verify/ (Cursor verify harness - NEW)
│ └── Forge.Adapters/ (Cursor adapter)
├── extensions/forge-vscode/
├── products/ (staging for future extraction)
├── examples/ (demos, samples)
└── research/ (spikes)

2. Forge.Verify Harness (NEW Component)

Cursor agent verification system for Forge self-extension:

• Phase 1: Syntax check (Roslyn compilation)
• Phase 2: Admission gate (Ashlar certification)
• Phase 3: Integration tests (API/CLI smoke tests)
• Phase 4: E2E validation (product workflows)

Why in Forge: Validates product code changes, uses Ashlar admission as a component.

3. One-Way Dependency Rule

Ashlar.Forge → Ashlar.Core (via NuGet packages ONLY)

• Forge consumes Ashlar framework via NuGet
• Core never references Forge
• Enforced by CI gates in both repositories

12-Phase Milestone Plan

1. ✅ Phase 0: Audit & Planning (this PR)
2. Phase 1: Bootstrap Forge repository
3. Phase 2: Extract Runtime Studio
4. Phase 3: Extract Application Surfaces (API + CLI)
5. Phase 4: Extract VS Code Extension
6. Phase 5: Create Forge.Verify Harness
7. Phase 6: Create Cursor Adapter
8. Phase 7: Migrate Samples & Examples
9. Phase 8: Migrate Products Tree
10. Phase 9: Migrate Scripts & Docs
11. Phase 10: Migrate Autonomy Spike
12. Phase 11: Clean Up Ashlar Core
13. Phase 12: Dogfooding (Cursor builds Forge using Forge.Verify)

Next Agent Task

Immediate next step: Scaffold Ashlar.Forge repository with:

• Basic structure (src/, tests/, docs/, examples/, etc.)
• Minimal Forge.Surfaces.CLI hello-world
• NuGet package references to Ashlar
• CI workflow (forge-gate.yml)
• Documentation (README, GettingStarted)

See Section 11 of the audit for detailed scaffolding task specification.

Benefits of Separation

1. Clarity: Framework vs. product is explicit
2. Independence: Core stability vs. product velocity
3. Reusability: Ashlar becomes a true framework for anyone
4. Autonomy: Forge validates itself using Ashlar admission (dogfooding)
5. Scalability: Products can extract to individual repos as they mature

Risk Mitigation

• Phased approach: 12 milestones prevent big-bang migration
• Dependency enforcement: CI gates prevent reverse dependencies
• Cross-repo testing: Forge CI tests against Ashlar packages
• Documentation: Clear placement rules for future code

Type of Change

• 📄 Documentation
• 🎯 Architectural decision
• ✨ New feature
• 🐛 Bug fix
• ♻️ Refactor

Testing

This is a documentation-only change (audit document). No code changes.

Checklist

• Documentation updated (new audit document added)
• Architecture decision documented
• Dependencies analyzed
• Migration plan defined
• Risk assessment completed
• Next steps clearly specified

Additional Context

This audit is a prerequisite for the strategic goal of enabling autonomous self-extend + validation with built-in agents. By separating Forge from Core:

• Forge becomes the proof that Ashlar is a usable framework
• Cursor agents can work on Forge using Forge.Verify to validate changes
• Core remains unopinionated about product verification strategies
• Other teams can build their own products on Ashlar (not just Forge)

Strategic model validation: If Forge (the product) successfully builds on top of Ashlar (the framework) using only NuGet dependencies, we prove Ashlar is a real framework, not just internal tooling.

---

Review focus:

1. Does the audit correctly identify framework vs. product code?
2. Is the proposed Forge structure reasonable?
3. Are there any extraction concerns or risks not covered?
4. Should any additional components be extracted or kept in core?