@juangcarmona/lighthouse 0.5.0 → 0.6.0

package/assets/profiles/dotnet/architecture.md

@@ -0,0 +1,37 @@
+# Backend structure and boundaries
+
+Use the product namespace under juangcarmona. The example's namespace is `JuanGCarmona.Lighthouse.Example`; the creator replaces it with `JuanGCarmona.<Product>`. Established products retain their namespace as a documented adoption choice.
+
+```text
+src/
+  root/<Product>.Api/                   host, HTTP policy, composition
+  root/<Product>.AppHost/               optional development orchestration
+  modules/<Product>.Modules.<Name>/
+    <Name>Module.cs                     public registration and route composition
+    Features/<Feature>/
+      CreateThing.cs                   one complete command slice
+      GetThing.cs                      one complete query slice
+      Domain/                         when the feature needs domain behavior
+    Infrastructure/Persistence/       when there is actual persistence
+  dotnet/Lighthouse.Cqrs/              initial typed command/query contracts
+  dotnet/Lighthouse.Analyzers/         local, versioned tooling source
+src/dotnet/tests/                     analyzer, HTTP and architecture tests
+```
+
+Paths describe responsibilities; create folders only when they hold real code. The distributed starter keeps its examples under `src/`; generated products start directly under `src/`.
+
+## Dependencies
+
+The API host composes modules. A module may depend on a sibling's separate `.Contracts` assembly, never its implementation assembly. Add a contracts project only when a consumer exists. Keep contracts small: integration DTOs, stable interfaces and events that describe a real boundary. A separate contracts assembly is a structural boundary; it does not by itself guarantee safe data exposure or correct authorization.
+
+Within a feature, use cases coordinate domain behavior and infrastructure. A command may write; a query returns a read model and must not mutate business state. Keep the domain independent of ASP.NET Core and storage APIs. A schema/DbContext per module is recommended when data ownership warrants that cost; cross-module joins or shared tables need an explicit decision. An in-memory single-module example cannot prove those persistence boundaries.
+
+## Composition and cross-cutting behavior
+
+Use explicit DI registration first. Introduce scanning or dispatch only when it removes measured repetition. The example injects typed handlers directly; it makes no mediator package mandatory. When logging, validation, authorization or caching become decorators, document and test their order. Authorization belongs at the edge and at the relevant domain/data boundary; validation must execute before mutation, including invocations outside HTTP.
+
+Transactions belong to the consistency boundary of a command. Use domain events for real domain coordination; introduce an outbox when delivery must survive process/transaction failure. Cache keys and invalidation must be tested together. These capabilities are recommendations with adoption costs, not speculative packages in the starter.
+
+## Runtime and diagnostics
+
+Aspire owns the optional local dependency graph and startup feedback. A deployment can use containers, a managed host or another product-approved topology. Production readiness covers configuration, identity, persistent data, migrations, health, telemetry, backup/recovery and release controls; the example implements only the smaller contract documented in its README.

package/assets/profiles/dotnet/guardrails.md

@@ -0,0 +1,32 @@
+# .NET guardrails and enforcement
+
+Each product maintainer owns activation and exceptions. Lighthouse maintainers own the reference diagnostics and their tests. The distinction between implemented and recommended checks is part of the contract.
+
+| Rule | Mechanism now | Failure | Exception / owner |
+| --- | --- | --- | --- |
+| LH1001: handlers stay internal sealed | Roslyn semantic rule for implementations of `JuanGCarmona.Lighthouse.Cqrs.ICommandHandler<,>` / `IQueryHandler<,>` | Error during module build | Maintainer records a narrow suppression and rationale; test the changed boundary |
+| LH1002: sibling module access uses Contracts | Roslyn compilation rule checks assembly references in the same `.Modules.` family | Error even for an unused implementation reference | Redesign dependency; temporary scoped suppression requires owner/review date |
+| Every implementation module activates the rules | Verifier inspects evaluated MSBuild properties and analyzer references for solution projects | Verifier fails if a named module silently omits enforcement | Product maintainer defines an explicit migration scope before adopting this full verifier |
+| Nullable correctness and SDK analysis | `src/dotnet/Directory.Build.props`, warnings-as-errors | Compiler/analysis warning fails build | Narrow documented suppression |
+| Formatting | `.editorconfig` and `dotnet format whitespace --verify-no-changes` | Verifier fails on whitespace drift | Product-owned formatting policy |
+| Reproducible dependency resolution | Pinned versions, SDK feature band, committed NuGet locks, locked restore | Restore fails on drift | Reviewed dependency update regenerates locks |
+| Known dependency vulnerabilities | NuGet audit of all dependencies; warnings-as-errors | Restore fails for reported advisories at low or above | Security owner decides explicit, expiring risk acceptance; no blanket audit disable |
+| HTTP validation and authorization | Functional tests of 400/401/403/201/200/404 behavior | Test fails | Accepted behavior changes require corresponding product decision |
+| Compiled module boundary | Reflection architecture test checks exported handlers and references | Test fails | Match product's actual architectural contract |
+| Broken compilation rules really fail build | `src/packages/cli/internal/verify-dotnet.mjs` compiles deliberately invalid temporary projects | Verifier fails unless LH1001 and LH1002 reject the fixture | Fix tooling; never accept a fixture merely because a unit test passed |
+| Public entity leaks, controller prohibition, domain-framework dependency | Documented profile rules; targeted automated rules are future work | Review finding today | Maintainer records exception; do not claim automatic enforcement |
+| Persistent data/tenant isolation | Product-specific integration tests, recommended | No coverage in this in-memory example | Product owner and security/data owner define requirements |
+
+## Activation
+
+Attach the analyzer as an analyzer-only project reference, set `LighthouseModule=true` on implementation projects, and expose that property with `CompilerVisibleProperty`. Module assembly names follow `<Root>.Modules.<Name>` and separate contract assemblies end in `.Contracts`. The distributed Catalog project and build properties are the executable contract.
+
+`LH1001` recognizes the supplied CQRS interfaces semantically, including aliases/inheritance. A different mediator/handler abstraction needs an adapter or another tested rule; class-name conventions alone are not enforcement. The rule skips compiler-generated code. `LH1002` checks compilation references for the configured naming family; it does not inspect payload semantics, reflection-based access, network calls or dependency injection at runtime. Use architecture/functional tests for those boundaries.
+
+## Diagnostic lifecycle
+
+New rules require positive and negative compiler fixtures, a stable diagnostic ID, useful remediation, release tracking and a failing-build rehearsal. Keep their compiler API compatible with the supported SDK. Move rules to the shipped ledger only as part of an accepted release. The current analyzers are local source tooling, not a published NuGet package.
+
+## Exceptions
+
+Record rule/diagnostic, affected paths, reason, owner, review date and compensating test. Suppress the smallest symbol/project scope, and remove the suppression after the migration. An architectural exception must not be disguised as generated code. CI runs the same verifier; required merge status still depends on the host's branch rules.

package/assets/profiles/dotnet/practices.md

@@ -0,0 +1,36 @@
+# Backend practice catalog
+
+This catalog makes the profile reviewable. Product code owners choose applicability; security/data owners accept changes to their boundaries. “Reference” means the example demonstrates a pattern. “Enforced” names the current tool. A recommendation becomes a gate only after a product implements and verifies it.
+
+| Practice | Problem addressed / when to apply | Mechanism in this release |
+| --- | --- | --- |
+| One deployable host, modules at real seams | Keep operations simple while preserving domain/data ownership; extra modules add coordination cost | Reference layout; boundary design is a review decision |
+| Feature-first organization | Keep behavior changes adjacent; avoid mandatory layer-by-layer file hopping | Reference and guidance |
+| One file per command/query | Keep route, DTOs, request, validation and handler together | Reference and review; file shape has no custom analyzer yet |
+| CQRS without separate storage by default | Distinguish reads from writes without adding a broker/read replica prematurely | Typed handler contracts and two working slices |
+| HTTP-independent handlers | Reuse/test application behavior without transport dependencies | Reference; dedicated dependency rule is future work |
+| Internal sealed handlers | Prevent application implementation from becoming a public API or inheritance surface | Enforced LH1001 for supported handler interfaces |
+| Public composition, private implementation | Make module registration explicit; expose only deliberate integration contracts | Reference; public entity-leak rule is future work |
+| Sibling Contracts assemblies | Stop modules depending on implementation internals; add contracts only for an actual consumer | Enforced LH1002 plus compiled architecture test |
+| Small shared kernel | Keep genuinely common technical contracts in one place without building an internal framework | Two typed handler interfaces; review additional abstractions |
+| Validation before side effects | Reject bad commands whether invoked through HTTP or another path | Reference handler validates before mutation; HTTP tests |
+| Explicit typed outcomes / ProblemDetails | Keep expected failures separate from unexpected exceptions and stable at the edge | Reference validation/missing-resource responses; HTTP tests |
+| Cross-cutting pipeline with tested order | Avoid inconsistent logging/validation/cache behavior after repetition justifies decorators | Recommendation; document order and test cache invalidation if introduced |
+| Trusted identity and authorization | Prevent callers from selecting their own owner/tenant boundary | JWT edge policy and 401/403 tests; tenant data checks require a persistent product slice |
+| Module-owned persistence and migrations | Avoid accidental shared-table coupling; separate schema/DbContext when ownership warrants the complexity | Recommendation; example has only in-memory storage |
+| Transaction boundaries per command | Make all-or-nothing behavior and concurrency conflicts explicit | Recommendation; database-backed tests required when introduced |
+| Domain events with durable delivery when needed | Keep domain coordination explicit; use an outbox only when delivery must survive failure | Recommendation; no event/outbox framework in the starter |
+| Read-model cache and tested invalidation | Reduce measured read cost without returning stale business state | Recommendation; no cache in the reference |
+| Cancellation and explicit identifiers | Bound abandoned work and expose stable resource identity | Reference propagates CancellationToken and uses GUID-v7 identifiers |
+| Same-origin/BFF where appropriate | Simplify browser session and API trust boundaries for products that benefit from one web origin | Optional architecture choice; no frontend/BFF in the example |
+| Generated API contracts | Detect API/client drift while keeping generated files disposable | Recommendation; require a real consumer before adding generation |
+| Structured logs and trace context | Diagnose a failed use case without logging sensitive payloads | Host development logging; exporter, redaction and event-ID policies remain product work |
+| Aspire development graph | Start related services with observable readiness and coherent configuration | Runnable AppHost for the API; provision only dependencies the product uses |
+| Layered verification by risk | Catch cheap faults early and reserve expensive journeys for valuable system behavior | Semantic analyzer, architecture and HTTP tests; engine/browser backend journeys added when needed |
+| SDK/package pins and lockfiles | Make local and CI feedback reproducible | Locked restore, central versions and SDK feature band |
+| Warnings, style and audit as failures | Surface compiler issues, code drift and known vulnerable dependencies before merge | SDK analysis, format verification and NuGet audit in the verifier |
+| Scoped CI with evidence of routing | Control cost without letting path filters hide meaningful changes | Current CI runs all selected profile checks; selective routing needs its own tests |
+| Concise agent/document routers | Help humans and agents find behavior, architecture and commands without duplicated truths | AGENTS entrypoint and profile navigation |
+| Owned, expiring exceptions | Make deviations deliberate and reversible | Documented process; no expiry automation is claimed |
+
+Use [architecture](architecture.md) for dependency direction, [use cases](use-cases.md) for implementation detail, and [guardrails](guardrails.md) for diagnostics, failure consequences and exception ownership.

package/assets/profiles/dotnet/testing-and-development.md

@@ -0,0 +1,29 @@
+# Tests and development feedback
+
+Run `npm run verify:dotnet` from Lighthouse or the generated backend. It performs locked restore, Release build, tests and a deliberately failing-build rehearsal. The repository CI definition runs this command as its .NET job.
+
+| Level | Purpose | Reference / cost |
+| --- | --- | --- |
+| Analyzer semantic fixtures | Reject forbidden shapes and allow legitimate code | Compiler in memory; fast |
+| Architecture | Inspect actual exports and assembly dependencies | Compiled assemblies; fast |
+| Functional HTTP | Verify routing, auth, validation and responses through the real ASP.NET pipeline | WebApplicationFactory; no network/services |
+| Persistence | Prove queries, transactions, schema and isolation against the real engine | Add Testcontainers when persistence is introduced |
+| Browser journey | Prove an actual user interaction across the system | Product UI only; slower lane |
+
+Choose boundaries according to failure risk. Use domain tests for complex domain rules, functional tests for API/data integration, and a small number of valuable end-to-end journeys. Don't replace functional coverage with mocks or make every PR start a full deployment without evidence that the cost helps.
+
+## Local loop
+
+```sh
+dotnet run --project src/dotnet/examples/src/root/Lighthouse.Example.Api
+dotnet run --project src/dotnet/examples/src/root/Lighthouse.Example.AppHost
+dotnet test src/dotnet/tests/Lighthouse.Example.Tests -c Release
+```
+
+Run either the API or AppHost entrypoint. The AppHost starts the API and exposes Aspire's local dashboard; the example has no fake database dependency. Host telemetry/health are development feedback, not proof of a production collector, alerts or durable storage. When adding PostgreSQL or another service, provision it in the local graph, wait for readiness, expose configuration through DI, and add engine-backed tests.
+
+Configure `Authentication__Authority` and `Authentication__Audience` with the product's trusted OIDC provider for authenticated manual requests. JWT defaults require issuer/signature/expiry validation and secure metadata. The test scheme and synthetic identity headers are confined to the test assembly. Missing credentials fail closed; the example ships no bypass, identity service or secret. `/health` is a minimal process-readiness route, not proof of data-service readiness.
+
+Use user-secrets/environment/approved secret storage for development configuration. Define production logging, redaction, traces/metrics exporters, graceful shutdown, dependency timeouts and recovery according to the product. The in-memory store and lack of full production hardening are explicit example limits.
+
+The AppHost pins MessagePack 2.5.303 to resolve [GHSA-qhrr-8q5h-9q3h](https://github.com/MessagePack-CSharp/MessagePack-CSharp/security/advisories/GHSA-qhrr-8q5h-9q3h) while retaining NuGet audit. Revisit the override when the upstream dependency includes the fix.

package/assets/profiles/dotnet/use-cases.md

@@ -0,0 +1,29 @@
+# One file per use case
+
+Read the distributed starter's `CreateEntry.cs` and `GetEntry.cs` examples. Each file owns a concrete behavior rather than a technical layer.
+
+| Part | Responsibility | Boundary |
+| --- | --- | --- |
+| Route mapping | URL, binding, authorization policy, cancellation and HTTP outcome | Thin transport adapter |
+| Request / response | External input and output shape | Never expose persistence entities |
+| Command / query | Application intent and its inputs | No HttpContext or IResult |
+| Validator | Structural/business input constraints before mutation | Callable for non-HTTP invocations |
+| Handler | Coordinate the use case and domain/storage work | Internal sealed; returns application data/outcome |
+
+Nest these types in the use-case class so related changes remain adjacent. Omit a request DTO where there is no body and no benefit; the query example binds its ID from the route. Keep reusable domain rules in the domain rather than duplicating them across validators.
+
+## Completion checklist
+
+1. Define the accepted behavior and failure examples before implementing the slice.
+2. Map a Minimal API endpoint and apply its real authorization policy.
+3. Resolve authenticated identity/tenant from trusted context when needed; never trust an owner ID supplied by the body.
+4. Map to a command/query, validate and call an HTTP-independent handler.
+5. Produce explicit success, validation, missing-resource and conflict outcomes as applicable. Hide unexpected exception details behind ProblemDetails and log context without secrets or payload dumps.
+6. Add the cheapest useful tests: domain rules, functional outcomes, authorization failures and persistence boundaries where present.
+7. Run build/analyzers and the required verification command; record any approved exception.
+
+The example keeps validation and outcome records local rather than introducing a general results framework. Products can choose an established result/validation library with a pinned version. Cancellation, authorization, logging and transactions still need verification regardless of the library.
+
+## Avoid accidental complexity
+
+Do not create a controller/service/repository class for every endpoint, a contracts assembly per feature, or a separate read database because a diagram says CQRS. Extract shared code only after a real use case needs it. Keep generated clients/metadata disposable; validate generator inputs, deterministic output and consumer contracts rather than hand-editing generated files.

package/assets/schemas/lighthouse-manifest.schema.json

@@ -10,16 +10,19 @@
     "schemaVersion": {"const": 1},
     "baseline": {"const": "0.1.0"},
     "product": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$"},
+    "application": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["shape", "stacks"],
+      "properties": {
+        "shape": {"enum": ["unknown", "frontend", "backend", "full-stack", "service", "library", "tooling", "cli", "worker", "mobile"]},
+        "stacks": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}
+      }
+    },
     "profiles": {"type": "array", "items": {"enum": ["node-tooling", "dotnet-backend", "visual-theme"]}, "uniqueItems": true},
     "integrations": {"type": "object", "additionalProperties": false, "required": ["productShape", "arcShape"], "properties": {"productShape": {"$ref": "#/$defs/pin"}, "arcShape": {"$ref": "#/$defs/pin"}}},
     "packages": {"type": "object", "additionalProperties": false, "required": ["sdlc"], "properties": {"sdlc": {"type": "object", "additionalProperties": false, "required": ["name", "version"], "properties": {"name": {"const": "@juangcarmona/lighthouse-sdlc"}, "version": {"$ref": "#/$defs/pin"}}}, "ui": {"type": "object", "additionalProperties": false, "required": ["name", "version"], "properties": {"name": {"const": "@juangcarmona/lighthouse-ui"}, "version": {"$ref": "#/$defs/pin"}}}}},
-    "managed": {"anyOf": [
-      {"const": ["LIGHTHOUSE.md"]},
-      {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml"]},
-      {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml", ".lighthouse/sdlc.json"]},
-      {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml", ".lighthouse/sdlc.json", ".lighthouse/upgrade.json"]},
-      {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml", ".lighthouse/sdlc.json", ".lighthouse/upgrade.json", "docs/design/DESIGN.md", ".agents/skills/lighthouse-ui/SKILL.md"]}
-    ]},
+    "managed": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}, "uniqueItems": true},
     "repository": {
       "type": "object",
       "additionalProperties": false,

package/assets/schemas/profile-catalog.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/profile-catalog.schema.json",
+  "title": "Lighthouse profile catalog",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "schemaVersion", "profiles"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "profiles": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/profile" }
+    }
+  },
+  "$defs": {
+    "profile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "owner", "purpose", "appliesTo", "surfaces", "verification"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+        "owner": { "type": "string", "minLength": 1 },
+        "purpose": { "type": "string", "minLength": 1 },
+        "appliesTo": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["shapes", "stacks"],
+          "properties": {
+            "shapes": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true },
+            "stacks": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+          }
+        },
+        "surfaces": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true },
+        "verification": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["layers"],
+          "properties": {
+            "layers": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/layer" },
+              "minItems": 1,
+              "uniqueItems": true
+            }
+          }
+        }
+      }
+    },
+    "layer": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "level", "kind", "verification"],
+      "properties": {
+        "id": { "enum": ["static", "unit", "architecture", "integration", "functional", "browser-e2e", "operational"] },
+        "level": { "enum": ["required", "recommended", "optional"] },
+        "kind": { "enum": ["hard", "soft"] },
+        "verification": { "enum": ["deterministic", "semantic", "human"] },
+        "command": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Lighthouse adoption and verification CLI",
   "repository": {
@@ -23,13 +23,16 @@
     "@arcshape/cli": "0.1.3",
     "@juangcarmona/lighthouse-ui": "0.2.0",
     "@prodshape/cli": "0.22.0",
-    "@juangcarmona/lighthouse-sdlc": "0.5.0"
+    "@juangcarmona/lighthouse-sdlc": "0.6.0"
   },
   "files": [
     "src/lighthouse.mjs",
     "src/guardrails.mjs",
     "assets",
     "README.md",
+    "src/profiles.mjs",
+    "src/create-dotnet.mjs",
+    "src/verify-dotnet.mjs",
     "upgrades"
   ],
   "bin": {

package/src/create-dotnet.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+const templateRoot = resolve(packageRoot, 'assets/dotnet-template');
+const cliPackage = JSON.parse(await readFile(resolve(packageRoot, 'package.json'), 'utf8'));
+const require = createRequire(import.meta.url);
+const sdlcContract = JSON.parse(await readFile(require.resolve('@juangcarmona/lighthouse-sdlc/contract.json'), 'utf8'));
+const args = process.argv.slice(2);
+const target = args[0] ? resolve(args[0]) : null;
+const name = args.includes('--name') ? args[args.indexOf('--name') + 1] : null;
+
+if (!target || !name || !/^[A-Z][A-Za-z0-9]{1,47}$/.test(name) || args.length !== 3 || args[1] !== '--name') {
+  process.stderr.write('Usage: lighthouse create-dotnet <empty-target> --name Workshop\nUse a PascalCase product identifier of 2–48 letters/digits.\n');
+  process.exit(2);
+}
+
+let existing = false;
+try {
+  const info = await lstat(target);
+  if (!info.isDirectory() || info.isSymbolicLink() || (await readdir(target)).length > 0) throw new Error('The target must be a new directory or an empty directory.');
+  existing = true;
+} catch (error) {
+  if (error.code !== 'ENOENT') throw error;
+}
+
+const transform = (text) => text
+  .replaceAll('JuanGCarmona.Lighthouse.Example', `JuanGCarmona.${name}`)
+  .replaceAll('Lighthouse.Example', name)
+  .replaceAll('Lighthouse_Example', name)
+  .replaceAll('../../../../Lighthouse.Cqrs/', '../../dotnet/Lighthouse.Cqrs/')
+  .replaceAll('../../../../Lighthouse.Analyzers/', '../../dotnet/Lighthouse.Analyzers/')
+  .replaceAll('../../Lighthouse.Analyzers/', '../../../src/dotnet/Lighthouse.Analyzers/')
+  .replaceAll('../../examples/src/root/', '../../../src/root/');
+
+async function copy(from, to) {
+  const info = await lstat(from);
+  if (info.isDirectory()) {
+    await mkdir(to, { recursive: true });
+    for (const entry of await readdir(from)) {
+      if (['bin', 'obj'].includes(entry)) continue;
+      await copy(join(from, entry), join(to, entry.replaceAll('Lighthouse.Example', name)));
+    }
+    return;
+  }
+  if (!info.isFile()) throw new Error('Starter sources must be ordinary files and directories.');
+  await mkdir(dirname(to), { recursive: true });
+  await writeFile(to, transform(await readFile(from, 'utf8')));
+}
+
+const stage = await mkdtemp(join(dirname(target), '.lighthouse-create-dotnet-'));
+try {
+  for (const [from, to] of [
+    ['Lighthouse.Analyzers', 'src/dotnet/Lighthouse.Analyzers'],
+    ['Lighthouse.Cqrs', 'src/dotnet/Lighthouse.Cqrs'],
+    ['examples/src', 'src'],
+    ['tests', 'tests/dotnet'],
+    ['Directory.Build.props', 'Directory.Build.props'],
+    ['Directory.Packages.props', 'Directory.Packages.props'],
+    ['global.json', 'global.json'],
+    ['Lighthouse.slnx', `${name}.slnx`],
+  ]) await copy(resolve(templateRoot, from), resolve(stage, to));
+
+  const solutionFile = resolve(stage, `${name}.slnx`);
+  const solutionText = (await readFile(solutionFile, 'utf8'))
+    .replaceAll('examples/src/', 'src/')
+    .replaceAll('Lighthouse.Analyzers/', 'src/dotnet/Lighthouse.Analyzers/')
+    .replaceAll('Lighthouse.Cqrs/', 'src/dotnet/Lighthouse.Cqrs/')
+    .replaceAll('tests/', 'tests/dotnet/');
+  const projects = [...solutionText.matchAll(/<Project Path="[^"]+"\s*\/>/g)].map((match) => match[0]);
+  await writeFile(solutionFile, `<Solution>\n${projects.map((project) => `  ${project}`).join('\n')}\n</Solution>\n`);
+
+  await copy(resolve(packageRoot, 'src/lighthouse.mjs'), resolve(stage, 'scripts/lighthouse.mjs'));
+  await copy(resolve(packageRoot, 'src/guardrails.mjs'), resolve(stage, 'scripts/guardrails.mjs'));
+  await copy(resolve(packageRoot, 'src/profiles.mjs'), resolve(stage, 'scripts/profiles.mjs'));
+  await copy(resolve(packageRoot, 'src/verify-dotnet.mjs'), resolve(stage, 'scripts/verify-dotnet.mjs'));
+  await copy(resolve(packageRoot, 'assets/guardrails'), resolve(stage, 'assets/guardrails'));
+  await copy(resolve(packageRoot, 'assets/profiles'), resolve(stage, 'assets/profiles'));
+  await copy(resolve(packageRoot, 'assets/schemas'), resolve(stage, 'schemas'));
+
+  await writeFile(resolve(stage, 'lighthouse.json'), `${JSON.stringify({
+    $schema: './schemas/lighthouse-manifest.schema.json', schemaVersion: 1, baseline: '0.1.0',
+    product: name, application: { shape: 'backend', stacks: ['dotnet'] }, profiles: ['dotnet-backend'],
+    integrations: { productShape: null, arcShape: null },
+    packages: { sdlc: { name: '@juangcarmona/lighthouse-sdlc', version: sdlcContract.version } },
+    managed: ['LIGHTHOUSE.md', 'scripts/lighthouse-guard.mjs', '.husky/commit-msg', '.husky/pre-push', '.github/workflows/lighthouse.yml', '.lighthouse/sdlc.json', '.lighthouse/upgrade.json', 'docs/profiles/dotnet/README.md', 'docs/profiles/dotnet/adoption.md', 'docs/profiles/dotnet/architecture.md', 'docs/profiles/dotnet/guardrails.md', 'docs/profiles/dotnet/practices.md', 'docs/profiles/dotnet/testing-and-development.md', 'docs/profiles/dotnet/use-cases.md', '.agents/skills/lighthouse-dotnet/SKILL.md'],
+    repository: {
+      layout: ['src', 'docs', 'infra', 'scripts'], publicSite: { enabled: true },
+      conventions: { commits: 'conventional', branchPattern: '^(feat|fix|docs|refactor|test|chore|build|ci|perf|revert)/[1-9]\\d*-[a-z0-9]+(?:-[a-z0-9]+)*$' },
+    },
+  }, null, 2)}\n`);
+  await writeFile(resolve(stage, 'package.json'), `${JSON.stringify({
+    name: `@juangcarmona/${name.toLowerCase()}`, private: true, type: 'module', engines: { node: '>=22' },
+    scripts: { verify: 'node scripts/lighthouse.mjs verify && node scripts/verify-dotnet.mjs' },
+  }, null, 2)}\n`);
+  await writeFile(resolve(stage, 'README.md'), `# ${name}\n\nBackend seeded from Lighthouse ${cliPackage.version}. Application and tooling sources are product-owned after creation.\n\nRun dotnet restore ${name}.slnx once to create lockfiles, then npm run verify. Commit lockfiles.\n\nStart dotnet run --project src/root/${name}.Api or the optional src/root/${name}.AppHost. Configure authentication using a trusted OIDC provider for manual API access. Test identities exist only in tests.\n\nThe sample catalog uses disposable in-memory storage. Add real persistence, data isolation, telemetry and deployment policy according to product requirements. Keep each command/query's endpoint, DTOs, validation and internal sealed handler together.\n`);
+  await writeFile(resolve(stage, 'AGENTS.md'), `# ${name} engineering guidance\n\nUse the Lighthouse .NET profile from the pinned baseline revision. Keep Minimal API commands/queries as complete single-file slices. Handlers remain internal sealed and independent of HTTP. Modules use sibling Contracts assemblies. Run npm run verify.\n\nApplication and tooling source is product-owned. Do not hand-edit LIGHTHOUSE.md. Record narrow, expiring exceptions for suppressed diagnostics.\n`);
+  await mkdir(resolve(stage, '.github/workflows'), { recursive: true });
+  await writeFile(resolve(stage, '.github/workflows/ci.yml'), `name: Backend verification\non: [push, pull_request]\npermissions:\n  contents: read\njobs:\n  dotnet:\n    runs-on: ubuntu-latest\n    timeout-minutes: 15\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '22'\n      - uses: actions/setup-dotnet@v4\n        with:\n          global-json-file: global.json\n      - run: npm run verify\n`);
+
+  const initialized = (await import('node:child_process')).spawnSync(process.execPath, [resolve(stage, 'scripts/lighthouse.mjs'), 'init'], { cwd: stage, encoding: 'utf8' });
+  if (initialized.status !== 0) throw new Error(initialized.stderr || 'Projection generation failed.');
+  if (existing) await rmdir(target);
+  await rename(stage, target);
+  process.stdout.write(`Created ${name} in ${target}. Run dotnet restore ${name}.slnx, then npm run verify.\n`);
+} catch (error) {
+  await rm(stage, { recursive: true, force: true });
+  throw error;
+}

package/src/lighthouse.mjs

@@ -6,6 +6,7 @@ import { createRequire } from 'node:module';
 import { basename, dirname, resolve } from 'node:path';
 import { execFileSync, spawnSync } from 'node:child_process';
 import { evaluateGuardrails, readGuardrailCatalog } from './guardrails.mjs';
+import { composeProfiles, normalizeApplication, profileCompositionResult, readProfileCatalog } from './profiles.mjs';
 let sdlcCapabilities;
 let sdlcReconcile;
 let sdlcGithub;
@@ -44,6 +45,7 @@ const managedPaths = [
 ];
 const profileManagedPaths = Object.freeze({
   'visual-theme': ['docs/design/DESIGN.md', '.agents/skills/lighthouse-ui/SKILL.md'],
+  'dotnet-backend': ['docs/profiles/dotnet/README.md', 'docs/profiles/dotnet/adoption.md', 'docs/profiles/dotnet/architecture.md', 'docs/profiles/dotnet/guardrails.md', 'docs/profiles/dotnet/practices.md', 'docs/profiles/dotnet/testing-and-development.md', 'docs/profiles/dotnet/use-cases.md', '.agents/skills/lighthouse-dotnet/SKILL.md'],
 });
 const previousManagedPaths = managedPaths.slice(0, -1);
 const legacyManagedPaths = [projection];
@@ -51,7 +53,7 @@ const supportedProfiles = ['node-tooling', 'dotnet-backend', 'visual-theme'];
 const branchPattern = '^(feat|fix|docs|refactor|test|chore|build|ci|perf|revert)/[1-9]\\d*-[a-z0-9]+(?:-[a-z0-9]+)*$';
 const authorityVersions = { productShape: '0.22.0', arcShape: '0.1.3' };
 const upgradeSchema = './node_modules/@juangcarmona/lighthouse/assets/schemas/lighthouse-upgrade.schema.json';
-const usage = 'Usage: lighthouse <init|authorities|reconcile|upgrade|capabilities|verify> [--name <product>] [--profile <profile>] [--scope <harness|sdlc|all>] [--format <text|json>] [--dry-run] [--apply]';
+const usage = 'Usage: lighthouse <init|create-dotnet|profiles|authorities|reconcile|upgrade|capabilities|verify> [--name <product>] [--profile <profile>] [--scope <harness|sdlc|all>] [--format <text|json>] [--dry-run] [--apply]';
 
 const defaultRepository = () => ({
   layout: [...layout],
@@ -77,15 +79,24 @@ function packageAsset(packageName, entry) {
 }
 
 function profileAssets(manifest) {
-  if (!(manifest?.profiles ?? []).includes('visual-theme')) return {};
-  try {
-    return {
-      'docs/design/DESIGN.md': packageAsset('@juangcarmona/lighthouse-ui', 'DESIGN.md'),
-      '.agents/skills/lighthouse-ui/SKILL.md': packageAsset('@juangcarmona/lighthouse-ui', 'skills/ui-design/SKILL.md'),
-    };
-  } catch (error) {
-    throw new Error(`Cannot read the installed Lighthouse UI profile: ${error.message}`);
+  const assets = {};
+  if ((manifest?.profiles ?? []).includes('visual-theme')) {
+    try {
+      assets['docs/design/DESIGN.md'] = packageAsset('@juangcarmona/lighthouse-ui', 'DESIGN.md');
+      assets['.agents/skills/lighthouse-ui/SKILL.md'] = packageAsset('@juangcarmona/lighthouse-ui', 'skills/ui-design/SKILL.md');
+    } catch (error) {
+      throw new Error(`Cannot read the installed Lighthouse UI profile: ${error.message}`);
+    }
   }
+  if ((manifest?.profiles ?? []).includes('dotnet-backend')) {
+    const files = ['README.md', 'adoption.md', 'architecture.md', 'guardrails.md', 'practices.md', 'testing-and-development.md', 'use-cases.md', 'SKILL.md'];
+    for (const file of files) {
+      const target = file === 'SKILL.md' ? '.agents/skills/lighthouse-dotnet/SKILL.md' : `docs/profiles/dotnet/${file}`;
+      try { assets[target] = readFileSync(new URL(`../assets/profiles/dotnet/${file}`, import.meta.url), 'utf8'); }
+      catch (error) { throw new Error(`Cannot read the installed Lighthouse .NET profile: ${error.message}`); }
+    }
+  }
+  return assets;
 }
 
 function profileArguments(args) {
@@ -108,6 +119,7 @@ function defaultManifest(product, profiles = []) {
     schemaVersion: 1,
     baseline: '0.1.0',
     product,
+    application: { shape: 'unknown', stacks: [] },
     profiles: [...profiles],
     integrations: { productShape: null, arcShape: null },
     packages,
@@ -458,7 +470,7 @@ function printUpgradePlan(plan) {
 function validate(manifest) {
   const problems = [];
   if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) return ['manifest must be an object'];
-  const allowed = ['$schema', 'schemaVersion', 'baseline', 'product', 'profiles', 'integrations', 'packages', 'managed', 'repository'];
+  const allowed = ['$schema', 'schemaVersion', 'baseline', 'product', 'application', 'profiles', 'integrations', 'packages', 'managed', 'repository'];
   for (const key of Object.keys(manifest)) if (!allowed.includes(key)) problems.push(`unknown field ${key}`);
   for (const key of ['schemaVersion', 'baseline', 'product', 'profiles', 'integrations', 'managed']) {
     if (!(key in manifest)) problems.push(`missing ${key}`);
@@ -469,6 +481,15 @@ function validate(manifest) {
   if (typeof manifest.product !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$/.test(manifest.product)) {
     problems.push('product must be a readable name of 1–64 characters');
   }
+  if ('application' in manifest) {
+    const application = manifest.application;
+    if (!application || typeof application !== 'object' || Array.isArray(application)
+        || !['unknown', 'frontend', 'backend', 'full-stack', 'service', 'library', 'tooling', 'cli', 'worker', 'mobile'].includes(application.shape)
+        || !Array.isArray(application.stacks) || application.stacks.some((stack) => typeof stack !== 'string' || !stack)
+        || new Set(application.stacks).size !== application.stacks.length) {
+      problems.push('application must declare a supported shape and unique stack names');
+    }
+  }
   const profiles = supportedProfiles;
   if (!Array.isArray(manifest.profiles) || manifest.profiles.some((p) => !profiles.includes(p))
       || new Set(manifest.profiles).size !== manifest.profiles.length) {
@@ -923,6 +944,11 @@ async function verify(manifest, format = 'text') {
     branch: gitBranch(),
     uiTokens: manifest?.profiles?.includes('visual-theme') ? packageAsset('@juangcarmona/lighthouse-ui', 'tokens.css') : null,
   });
+  const profileComposition = composeProfiles(readProfileCatalog(), manifest);
+  report.profiles = profileComposition;
+  const profileResult = profileCompositionResult(profileComposition);
+  report.results.push(profileResult);
+  report.summary[profileResult.status] = (report.summary[profileResult.status] ?? 0) + 1;
   const adoption = Object.values(capabilityAdoption(await readUpgradeState()));
   for (const item of adoption) {
     if (item.status !== 'adopted' || !item.recordPath || await exists(resolve(root, item.recordPath))) continue;
@@ -956,6 +982,20 @@ async function verify(manifest, format = 'text') {
   console.log('Lighthouse manifest, repository boundaries and managed projection are valid.');
 }
 
+async function profiles(manifest, format = 'text') {
+  const composition = composeProfiles(readProfileCatalog(), manifest);
+  if (format === 'json') {
+    console.log(JSON.stringify(composition, null, 2));
+    if (composition.status === 'failed') process.exitCode = 1;
+    return;
+  }
+  console.log(`Lighthouse profile composition: ${composition.status}`);
+  console.log(`  application ${composition.application.shape}${composition.application.stacks.length ? ` (${composition.application.stacks.join(', ')})` : ''}`);
+  for (const profile of composition.selected) console.log(`  ${profile.id}: ${profile.status}${profile.nextAction ? `; next: ${profile.nextAction}` : ''}`);
+  if (!composition.selected.length) console.log('  no profiles selected');
+  if (composition.status === 'failed') process.exitCode = 1;
+}
+
 function planHash(plan) {
   const { authorization, ...payload } = plan;
   return contentHash(JSON.stringify(payload));
@@ -1117,6 +1157,11 @@ function formatFromArgs(args) {
 const args = process.argv.slice(2);
 const command = args[0];
 const commandArgs = args.slice(1);
+if (command === 'create-dotnet') {
+  process.argv.splice(2, 1);
+  await import('./create-dotnet.mjs');
+  process.exit(0);
+}
 let invalidArgument = false;
 for (let index = 0; index < commandArgs.length; index += 1) {
   const arg = commandArgs[index];
@@ -1135,12 +1180,12 @@ for (let index = 0; index < commandArgs.length; index += 1) {
     continue;
   }
   if (arg === '--format') {
-    if (!['verify', 'upgrade', 'capabilities'].includes(command) || !['text', 'json'].includes(commandArgs[index + 1])) invalidArgument = true;
+    if (!['profiles', 'verify', 'upgrade', 'capabilities'].includes(command) || !['text', 'json'].includes(commandArgs[index + 1])) invalidArgument = true;
     else index += 1;
     continue;
   }
   if (arg.startsWith('--format=') && ['text', 'json'].includes(arg.slice('--format='.length))) {
-    if (!['verify', 'upgrade', 'capabilities'].includes(command)) invalidArgument = true;
+    if (!['profiles', 'verify', 'upgrade', 'capabilities'].includes(command)) invalidArgument = true;
     continue;
   }
   if (arg === '--scope') {
@@ -1160,7 +1205,7 @@ for (let index = 0; index < commandArgs.length; index += 1) {
   if (['--id=', '--provider=', '--repo=', '--input=', '--plan-file=', '--authorize='].some((prefix) => arg.startsWith(prefix) && arg.length > prefix.length)) continue;
   invalidArgument = true;
 }
-if (!['init', 'authorities', 'reconcile', 'upgrade', 'capabilities', 'verify'].includes(command) || invalidArgument) {
+if (!['init', 'profiles', 'authorities', 'reconcile', 'upgrade', 'capabilities', 'verify'].includes(command) || invalidArgument) {
   console.error(usage);
   process.exit(2);
 }
@@ -1170,6 +1215,11 @@ try {
   else if (command === 'reconcile') await reconcile(args.slice(1));
   else if (command === 'upgrade') await upgrade(args.slice(1));
   else if (command === 'capabilities') await capabilities(args.slice(1));
+  else if (command === 'profiles') {
+    const manifest = await readManifest();
+    if (!manifest) throw new Error('Cannot read lighthouse.json: file does not exist; run lighthouse init --name <product>.');
+    await profiles(manifest, formatFromArgs(commandArgs));
+  }
   else {
     const manifest = await readManifest();
     if (!manifest) throw new Error('Cannot read lighthouse.json: file does not exist; run lighthouse init --name <product>.');