human-to-code 0.1.3 → 0.1.5

package/docs/SCALABILITY.md

@@ -0,0 +1,144 @@
+# Scalability and engineering practices
+
+How to grow this codebase without eroding its guarantees. The safety
+invariants in [CONTRIBUTING.md](../CONTRIBUTING.md#non-negotiable-safety-invariants)
+are the hard floor; this document covers the structural practices that keep
+the code readable and extensible as it scales.
+
+## Layering rules
+
+Source lives in layered domain folders (see
+[ARCHITECTURE.md](ARCHITECTURE.md)). The rules:
+
+1. **Imports point upward only.** A module may import from its own folder or
+   a layer above it (`core` at the top, `pipeline` at the bottom, entry points
+   below everything). If you need a downward import, the type or helper you
+   want belongs in a higher layer — move it, don't bend the arrow.
+2. **`core/` stays dependency-free.** Nothing in `core/` imports from any
+   other folder or from an SDK. It is the shared vocabulary; keeping it leaf
+   is what prevents import cycles as the codebase grows.
+3. **Entry points stay thin.** `cli.ts` parses arguments, maps statuses to
+   exit codes, and prints; `index.ts` only re-exports. Behavior belongs in a
+   layer, where it is testable without a TTY.
+4. **One module, one responsibility.** New functionality gets a new file in
+   the right folder rather than growing an existing file past its purpose.
+   If a file needs a paragraph to describe, it is two files.
+5. **Every module starts with a `/** … */` header** stating what it does and,
+   where relevant, what it deliberately does not do. The headers are the
+   first line of documentation; keep them true when behavior changes.
+
+## Extension points
+
+The codebase has three designed seams. Extending along them requires no
+changes to the layers above.
+
+### Adding an ecosystem (e.g. Django, Spring)
+
+1. Implement `EcosystemAdapter` (`analysis/analyzer-types.ts`) in a new
+   `analysis/adapters/<name>.ts`. Analysis must stay static: inspect only the
+   bounded `AnalyzerContext`; never import project modules, evaluate config,
+   or spawn tools. Emit version evidence and candidate validation commands.
+2. Declare the recognized variants/versions in `analysis/support-matrix.ts`,
+   starting at `preview` tier. Support is declared, never inferred.
+3. Register the adapter in `DEFAULT_ECOSYSTEM_ADAPTERS`
+   (`analysis/analyzer.ts`).
+4. Add a skill pack in `context/compiler-skills.ts` for the ecosystem's
+   conventions (policy data only — it grants no authority).
+5. Add positive and adversarial fixtures per the analyzer checklist in
+   CONTRIBUTING.md: conflicting lockfiles, ambiguous workspaces, symlinks,
+   partial scans, stable ordering and fingerprints.
+
+### Adding a provider (e.g. Anthropic)
+
+1. Implement `ProviderAdapter` (`providers/provider.ts`) in
+   `providers/providers.ts` (or a sibling file) using only Node built-ins and
+   `security/pinned-http.ts` for transport. No new runtime dependencies.
+2. Route all output through the existing schema gate (`generateValidated`)
+   and budget accounting — pessimistic pre-request reservation, reconciliation
+   on provider-reported usage, conservative charge on failure.
+3. Bind credentials to the endpoint via `apiKeyEnv` only; require reviewed
+   pricing bounds for remote endpoints; never advertise context tools to a
+   non-loopback destination.
+4. Wire the name through `config/config.ts` validation and the CLI factory in
+   `cli.ts`. No silent fallback of provider, model, or endpoint — ever.
+5. Test with injected fetch/DNS/clock seams per the provider checklist in
+   CONTRIBUTING.md.
+
+### Evolving an artifact schema
+
+Artifacts (`*V1` in `core/contracts.ts`) are the contracts between stages and
+between releases:
+
+- **Additive and compatible?** Extend the V1 type and its exact validator
+  together, plus the JSON Schema in `providers/schemas.ts` if the artifact
+  crosses the provider boundary.
+- **Meaning changes?** New version (`*V2`), new validator, explicit migration
+  (the `migrate-config` command is the pattern). Never silently reinterpret a
+  stored artifact — run records outlive releases.
+- Unknown fields always remain errors. Loosening exact-key validation is a
+  design discussion, not a patch.
+
+## Code conventions
+
+- **TypeScript strict, no escape hatches.** `strict` and
+  `noUncheckedIndexedAccess` stay on; avoid `any` and non-null assertions —
+  validate at the boundary and let types flow.
+- **Zero production dependencies.** HTTP, hashing, JSON, and process handling
+  use Node built-ins. Adding a runtime dependency changes the supply-chain
+  posture and needs a design discussion first.
+- **Errors are typed and named.** Each layer exports its own error classes
+  (`ArtifactValidationError`, `ProviderError`, `PatchSafetyError`, …) so the
+  CLI can map failures to exit codes without string matching. Error messages
+  never contain secret values.
+- **Determinism by default.** Stable ordering for anything hashed, listed, or
+  persisted; inject clock/randomness/network/exec as parameters so tests can
+  control them.
+- **Statuses, not booleans.** Multi-outcome operations return the typed run
+  statuses (`VERIFIED`/`NEEDS_INPUT`/`UNSUPPORTED`/`INCONCLUSIVE`/`FAILED`/
+  `SECURITY_BLOCKED`), and only `VERIFIED` is success.
+
+## Testing practices
+
+- Every `src/**/x.ts` with behavior has a mirror `test/x.test.ts`; keep the
+  mirror when adding or moving modules.
+- Tests are deterministic and offline: injected fetch/DNS/environment/clock
+  seams, no real provider, network, or container daemon (the validation tests
+  stub the sandbox probe).
+- New behavior ships with its most plausible misuse and failure cases, not
+  just the happy path — the per-area checklists in CONTRIBUTING.md are the
+  bar.
+- Secret-handling tests use unmistakably synthetic values and assert that raw
+  values never appear in errors, reports, or stored artifacts.
+- `npm run typecheck && npm test && npm run build && npm run package:check`
+  must pass from a clean install before review; CI runs the same set.
+
+## Documentation practices
+
+Documentation is layered like the code — update the layer that owns the fact:
+
+| Layer | Owns | Update when |
+| --- | --- | --- |
+| Module headers | What one file does | The file's behavior changes |
+| [docs/MODULES.md](MODULES.md) | The per-file map | A module is added, moved, or repurposed |
+| [docs/ARCHITECTURE.md](ARCHITECTURE.md) | Layers, flow, design decisions | A layer, stage, or invariant-relevant design changes |
+| [Readme.md](../Readme.md) | User-facing behavior and guarantees | CLI behavior, config, statuses, or limitations change |
+| [SECURITY.md](../SECURITY.md) | Trust model | Any trust-boundary change |
+| [CONTRIBUTING.md](../CONTRIBUTING.md) | Invariants and checklists | The engineering bar itself changes |
+
+A pull request that changes behavior updates the affected documentation in
+the same change — documentation drift is treated as a defect, and honest
+wording is part of review (never describe a fail-closed limitation as a
+feature gap to be papered over).
+
+## Growth guardrails
+
+- **When a folder accumulates unrelated concerns, split the folder**, not
+  just the file — the layer list in ARCHITECTURE.md is expected to grow.
+- **New capability starts fail-closed.** Ship recognition at `preview`,
+  refuse ambiguity, and let certification evidence — not confidence — promote
+  it. This is what keeps adding surface area from multiplying risk.
+- **No bypass flags.** If a gate is inconvenient, the fix is evidence or
+  design, never a flag that converts a non-success status into exit 0.
+- **Entry-point stability.** `src/index.ts` and `src/cli.ts` stay at the
+  source root so `dist/index.js` and `dist/cli.js` (package `main`/`bin`)
+  never move; reorganize beneath them freely.

package/docs/roadmap/README.md

@@ -0,0 +1,69 @@
+# Language & framework support roadmap
+
+One file per language/framework we intend to support. Each file is an
+integration plan, not a promise of a date — items are implemented one by one,
+and a plan graduates out of this folder when its profile ships.
+
+## The four support levels
+
+Support in human-to-code is layered; "supporting a language" means moving it
+up this ladder deliberately:
+
+1. **Direct path** (`src/pipeline/simple.ts`) — the language has an entry in
+   `LANGUAGE_PROFILES` (output extension + prompt label) and, if it has an
+   inline-comment form, its source extensions are in `SCANNED_EXTENSIONS` for
+   `@human` markers. No grounding, no validation; receipt-and-confirm only.
+   *Today: TypeScript, JavaScript, Python, Rust, Go, Java, Ruby, C#, C++, C.*
+2. **General fallback** (`src/analysis/adapters/general.ts`) — any declared
+   language can flow through the guided pipeline ungrounded, permanently
+   `INCONCLUSIVE`. This exists for every language already; it is the floor,
+   not a goal.
+3. **Grounded profile** — a static `EcosystemAdapter` recognizes real
+   projects, collects version evidence, and emits a validation plan; the
+   variant is declared in the support matrix at `preview` tier. This is what
+   each plan in this folder describes.
+4. **Certified** — the profile passes the benchmark gate in
+   `src/providers/certification.ts` (≥25 tasks × 3 runs × ≥95% strong-sandbox
+   pass rate per provider/model). Never self-declared.
+
+## What every plan must cover
+
+The integration steps are fixed by [docs/SCALABILITY.md](../SCALABILITY.md#adding-an-ecosystem-eg-django-spring);
+each plan fills in the language-specific facts:
+
+| Section | It answers |
+| --- | --- |
+| Status today | Which level (1/2) the language sits at right now. |
+| Target profile | The `Ecosystem` name, variants, and version range for the support matrix. |
+| Detection signals | Manifests/lockfiles/config the static adapter may read — never execute. |
+| Version evidence | Where exact resolved versions come from (lockfile, manifest pin). |
+| Validation plan | Candidate commands (argv arrays) the sandbox would run — build, test, lint. |
+| Skill pack | Conventions the `compiler-skills.ts` policy pack must encode. |
+| Risks & gates | What must be treated as elevated risk or refused (codegen hooks, FFI, migrations…). |
+| Checklist | The mechanical steps, in order, with test obligations. |
+
+Ground rules that apply to every plan (from CONTRIBUTING.md's invariants):
+analysis stays static and read-only; new variants start at `preview`; support
+is declared in `support-matrix.ts`, never inferred; ambiguity returns
+`NEEDS_INPUT`/`UNSUPPORTED` rather than guessing; adding an `Ecosystem` value
+is a schema-visible change and updates `analyzer-types.ts`, skills selection,
+and the certification profile keys together.
+
+## Plans
+
+| Plan | Kind | Sits at level | Target |
+| --- | --- | --- | --- |
+| [go.md](go.md) | language | 1 (direct path) | Go modules ecosystem |
+| [java.md](java.md) | language | 1 (direct path) | Maven/Gradle ecosystem |
+| [csharp.md](csharp.md) | language | 1 (direct path) | .NET SDK ecosystem |
+| [ruby.md](ruby.md) | language | 1 (direct path) | Bundler/Rails ecosystem |
+| [php.md](php.md) | language | 2 (general only) | Composer/Laravel ecosystem |
+| [swift.md](swift.md) | language | 2 (general only) | SwiftPM ecosystem |
+| [kotlin.md](kotlin.md) | language | 2 (general only) | Gradle/Android ecosystem |
+| [dart.md](dart.md) | language | 2 (general only) | Pub/Flutter ecosystem |
+| [bash.md](bash.md) | language | 2 (general only) | Shell-script profile |
+| [sql.md](sql.md) | language | 2 (general only) | Migration-aware SQL profile |
+| [yaml.md](yaml.md) | config | 2 (general only) | Schema-validated config profile |
+| [html-css.md](html-css.md) | language | 2 (general only) | Static web profile |
+| [docker.md](docker.md) | infra | 2 (general only) | Dockerfile/Compose profile |
+| [terraform.md](terraform.md) | infra | 2 (general only) | Terraform/HCL profile |

package/docs/roadmap/bash.md

@@ -0,0 +1,46 @@
+# Bash / shell-script support plan
+
+## Status today
+Level 2 only: not in `LANGUAGE_PROFILES`; `.sh` not scanned for markers
+(`# @human` markers would already parse — the `#` comment form is supported
+by the marker regex — but `.sh` files are not in `SCANNED_EXTENSIONS`).
+
+## Target profile
+- `Ecosystem`: `shell`.
+- Variant: `script-collection` — a repo (or subtree) of `*.sh`/`*.bash`
+  scripts. There is no manifest, so this profile is signal-based:
+  shebang lines + extension inventory, and it should stay deliberately
+  narrow. Anything ambiguous stays with the general fallback.
+- Versions: bash ≥ 4 assumed by image; POSIX-sh scripts flagged by shebang.
+
+## Detection signals (static only)
+- Shebangs (`#!/usr/bin/env bash`, `#!/bin/sh`), `.shellcheckrc`,
+  `Makefile` targets referencing scripts, `bats` test files (`*.bats`).
+
+## Version evidence
+No package manager: dependency grounding is out of scope. The profile's
+honesty lever is that generation is anchored to shellcheck-clean patterns
+rather than external APIs.
+
+## Validation plan
+- `["shellcheck", "<changed scripts>"]` and `["bash", "-n", "<script>"]`
+  syntax checks; `["bats", "test/"]` when a bats suite exists. All in the
+  sandbox image — scripts themselves are never executed outside it.
+
+## Skill pack
+`set -euo pipefail` discipline, quoting rules, `trap` cleanup, no curl-pipe
+patterns (aligns with the validator's implicit-downloader rejection),
+portable vs bash-specific constructs by shebang.
+
+## Risks & gates
+Every script is arbitrary code — validation runs syntax/lint/bats only,
+never the script itself. Scripts that self-modify or fetch remote content
+must be flagged as elevated risk in contracts.
+
+## Checklist
+0. Add `bash` to `LANGUAGE_PROFILES` (`.sh`) and `.sh`/`.bash` to `SCANNED_EXTENSIONS`.
+1. `Ecosystem` union + `analysis/adapters/shell.ts` (small, signal-based).
+2. `shell/script-collection` at `preview`.
+3. Register adapter; shell skill pack.
+4. Tests: shebang inventory, non-script repos not claimed, bats detection, stable fingerprints.
+5. Docs updates.

package/docs/roadmap/csharp.md

@@ -0,0 +1,44 @@
+# C# / .NET support plan
+
+## Status today
+Level 1: `LANGUAGE_PROFILES` has `csharp` (`.cs`), and `.cs` is scanned for
+inline `// @human` markers. No grounded profile.
+
+## Target profile
+- `Ecosystem`: `dotnet`.
+- Variants: `sdk-project` (single `.csproj`), `solution` (`.sln` with
+  multiple projects), with ASP.NET Core detected as a framework signal.
+- Versions: .NET 8 LTS+ (from `<TargetFramework>`).
+
+## Detection signals (static only)
+- `.sln` project references; `.csproj` `<TargetFramework>`, `<PackageReference>`,
+  `<Nullable>`, `<ImplicitUsings>`.
+- `Program.cs` minimal-hosting vs `Startup.cs` as entry-point signals;
+  `*.Tests.csproj` for test roots. Never invoke `dotnet`.
+
+## Version evidence
+`packages.lock.json` when `RestorePackagesWithLockFile` is enabled gives
+exact versions; otherwise `<PackageReference Version="...">` literals. Range
+versions without a lockfile leave the dependency unproven for API grounding.
+
+## Validation plan
+- `["dotnet", "build", "--nologo"]`, `["dotnet", "test", "--nologo"]` against
+  a preinstalled SDK image matching `<TargetFramework>`; NuGet restore needs
+  either a no-network local cache or is `INCONCLUSIVE` (validation has no network).
+
+## Skill pack
+Nullable-reference-type discipline; DI via `IServiceCollection`; xUnit
+conventions; `record` for DTOs; generated `obj/`/`bin/` and `*.Designer.cs`
+protected.
+
+## Risks & gates
+Source generators/analyzers in project files, `unsafe` blocks, P/Invoke
+(`DllImport`), and EF Core migrations are elevated-risk; migrations are
+generated for review, never applied (existing invariant).
+
+## Checklist
+1. `Ecosystem` union + `analysis/adapters/dotnet.ts`.
+2. `dotnet/sdk-project`, `dotnet/solution` at `preview`.
+3. Register adapter; .NET skill pack.
+4. Tests: solution/project graph ambiguity, lockfile vs floating versions, offline-restore behavior, stable fingerprints.
+5. Docs updates.

package/docs/roadmap/dart.md

@@ -0,0 +1,43 @@
+# Dart / Flutter support plan
+
+## Status today
+Level 2 only: not in `LANGUAGE_PROFILES`; `.dart` not scanned for markers.
+
+## Target profile
+- `Ecosystem`: `dart`.
+- Variants: `package` (pure Dart), `flutter-app` (validation limited to
+  `flutter test` unit/widget tests — no device/emulator).
+- Versions: Dart ≥ 3.0 (from `environment.sdk` in `pubspec.yaml`).
+
+## Detection signals (static only)
+- `pubspec.yaml` (`environment`, `dependencies`, `flutter:` section),
+  `pubspec.lock`, `lib/`, `test/`, `analysis_options.yaml`. The `flutter`
+  SDK dependency distinguishes the variants. Never run `dart`/`flutter` CLIs.
+
+## Version evidence
+`pubspec.lock` is exact and required for grounding; caret ranges in
+`pubspec.yaml` alone are unproven.
+
+## Validation plan
+- `["dart", "analyze"]` + `["dart", "test"]`, or `["flutter", "test"]` for
+  the flutter variant, in an image with the SDK and a primed pub cache
+  (sandbox has no network for `pub get`).
+
+## Skill pack
+Effective-Dart naming/layout, null-safety, widget test conventions,
+`build_runner` outputs (`*.g.dart`, `*.freezed.dart`) protected as
+generated files.
+
+## Risks & gates
+`build_runner` codegen (never run by the tool; generated files protected),
+platform channels/FFI, and Flutter platform folders (`android/`, `ios/`)
+which follow their own ecosystems' rules — treat as prohibited paths
+initially.
+
+## Checklist
+0. Add `dart` to `LANGUAGE_PROFILES` (`.dart`) and scan `.dart` for `// @human`.
+1. `Ecosystem` union + `analysis/adapters/dart.ts`.
+2. `dart/package`, `dart/flutter-app` at `preview`.
+3. Register adapter; Dart/Flutter skill pack.
+4. Tests: lock absence, flutter vs pure-dart, generated-file protection, stable fingerprints.
+5. Docs updates.

package/docs/roadmap/docker.md

@@ -0,0 +1,46 @@
+# Docker / containerfile support plan
+
+## Status today
+Level 2 only. Note the tool already *consumes* Docker/Podman as its
+validation sandbox (`src/pipeline/validation.ts`); this plan is about
+generating and editing Dockerfiles/Compose files as change targets.
+
+## Target profile
+- `Ecosystem`: `container`.
+- Variants: `dockerfile` (Dockerfile/Containerfile present),
+  `compose` (`compose.yaml`/`docker-compose.yml`), usually attached as a
+  secondary workspace signal to the ecosystem that owns the app.
+- Versions: Compose schema version; base-image tags/digests as evidence.
+
+## Detection signals (static only)
+- `Dockerfile*`, `Containerfile`, `compose*.y(a)ml`, `.dockerignore`;
+  `FROM` lines (stage graph), `COPY --from` references — all textual.
+
+## Version evidence
+Base images pinned by digest are proven; tag-only `FROM` lines are recorded
+as unpinned evidence and the skill pack pushes toward digests. Compose
+`image:` entries likewise.
+
+## Validation plan
+- `["hadolint", "Dockerfile"]` lint in the sandbox image;
+  `["docker", "compose", "config", "-q"]` for Compose syntax (offline,
+  no engine calls beyond config parsing). An actual `docker build` is
+  arbitrary remote-fetching execution — out of scope for validation; at
+  most a later opt-in tier with a network-off buildkit and preloaded bases.
+
+## Skill pack
+Multi-stage builds, non-root `USER`, explicit `WORKDIR`, no secrets in
+layers/ARGs (aligns with the secret scanner), `.dockerignore` completeness,
+healthchecks, digest pinning.
+
+## Risks & gates
+`FROM` changes, new `RUN curl | sh` patterns (refuse — matches the
+implicit-downloader rejection), privileged/host-mount Compose options, and
+port/secret exposure are elevated-risk requiring contract authorization.
+
+## Checklist
+1. `Ecosystem` union + `analysis/adapters/container.ts`.
+2. `container/dockerfile`, `container/compose` at `preview`.
+3. Skill pack; patch-policy tests for RUN-pattern and privilege gating.
+4. Tests: multi-stage graphs, digest vs tag evidence, compose schema versions.
+5. Docs updates.

package/docs/roadmap/go.md

@@ -0,0 +1,47 @@
+# Go support plan
+
+## Status today
+Level 1: `LANGUAGE_PROFILES` has `go` (`.go`), and `.go` is in
+`SCANNED_EXTENSIONS`, so whole-file `.human` and inline `// @human` markers
+already work through the direct path. No grounded profile.
+
+## Target profile
+- `Ecosystem`: `go` (new union member in `analyzer-types.ts`).
+- Variants: `module` (single `go.mod`), `workspace` (`go.work`), with
+  HTTP-framework signals (net/http, chi, gin, echo) recorded as profile
+  signals, not variants, until one earns its own entry.
+- Versions: Go ≥ 1.21 (from the `go` directive in `go.mod`).
+
+## Detection signals (static only)
+- `go.mod` — module path, `go`/`toolchain` directives, `require` blocks.
+- `go.sum` — presence distinguishes resolved deps; `go.work`/`go.work.sum`
+  for workspaces. Conflicting nested modules without `go.work` → `NEEDS_INPUT`.
+- `*_test.go` naming for test roots; `cmd/`, `internal/`, `pkg/` conventions
+  for entry-point/source-root inventory. Never run `go list`.
+
+## Version evidence
+`go.mod` `require` lines give exact pinned versions (Go modules pin by
+design); `go.sum` corroborates. Both are protected/lockfile paths the model
+must not edit.
+
+## Validation plan (sandbox argv arrays)
+- `["go", "build", "./..."]`, `["go", "vet", "./..."]`, `["go", "test", "./..."]`.
+- Needs a Go toolchain image; record the `go` directive so an image mismatch
+  is `INCONCLUSIVE`, not a guess.
+
+## Skill pack
+Module-path-relative imports only; table-driven tests; error-wrapping
+(`%w`) conventions; no `init()` side effects; generated files
+(`*_gen.go`, `zz_generated*`) are protected.
+
+## Risks & gates
+`cgo`, `unsafe`, `//go:generate`, build tags, and replace directives are
+elevated-risk and need explicit contract authorization — same posture as
+Rust's `unsafe`/FFI gates.
+
+## Checklist
+1. Add `go` to the `Ecosystem` union + `analysis/adapters/go.ts` implementing `EcosystemAdapter`.
+2. Declare `go/module` + `go/workspace` in `support-matrix.ts` at `preview`.
+3. Register in `DEFAULT_ECOSYSTEM_ADAPTERS`; add a Go skill pack in `compiler-skills.ts`.
+4. Tests per CONTRIBUTING's analyzer checklist: nested modules, missing `go.sum`, `go.work` ambiguity, cgo detection, stable fingerprints.
+5. Update `docs/MODULES.md` and the support matrix section of the README.

package/docs/roadmap/html-css.md

@@ -0,0 +1,47 @@
+# HTML & CSS support plan
+
+## Status today
+Level 2 only: not in `LANGUAGE_PROFILES`. React/Vite workspaces already
+cover most component markup/styling through the existing node adapter; this
+plan is for *static* sites and stylesheet-centric projects.
+
+## Target profile
+- `Ecosystem`: `static-web`.
+- Variant: `static-site` — plain HTML/CSS/vanilla-JS trees (like this
+  repo's `website/`), optionally with a recognized static generator config
+  (Eleventy, Astro static) as a later variant.
+- Signals: `index.html` at a root, no framework manifest claiming the tree.
+
+## Detection signals (static only)
+- `index.html` + sibling `*.css`/`*.js` without `package.json` build
+  tooling; `<link rel="stylesheet">`/`<script src>` graphs (textual);
+  generator configs (`.eleventy.js`, `astro.config.*`) detected but not
+  executed.
+
+## Version evidence
+CDN dependencies (script/link URLs) are recorded as evidence with their
+pinned versions when the URL encodes one; unpinned CDN URLs are flagged —
+the skill pack should push toward pinned or vendored assets.
+
+## Validation plan
+- `["npx", "html-validate", "<files>"]` and `["npx", "stylelint", "<files>"]`
+  style checks with tools preinstalled in the image; link-graph check
+  (internal hrefs resolve) implementable in-process without execution.
+
+## Skill pack
+Semantic landmarks, heading order, alt text, `prefers-reduced-motion` and
+`prefers-color-scheme` support, no inline event handlers, responsive images
+— accessibility is the correctness bar for markup.
+
+## Risks & gates
+Third-party `<script src>` additions are supply-chain-sensitive →
+elevated-risk, must be pinned and contract-authorized. Inline scripts are
+ordinary code and reviewed as such.
+
+## Checklist
+0. Add `html`/`css` to `LANGUAGE_PROFILES` (`.html`, `.css`) for the direct path.
+1. `Ecosystem` union + `analysis/adapters/static-web.ts`.
+2. `static-web/static-site` at `preview`.
+3. Skill pack centred on accessibility conventions.
+4. Tests: framework-owned trees not double-claimed, CDN pin detection, link-graph checks.
+5. Docs updates.

package/docs/roadmap/java.md

@@ -0,0 +1,48 @@
+# Java support plan
+
+## Status today
+Level 1: `LANGUAGE_PROFILES` has `java` (`.java`), and `.java` is scanned for
+inline `// @human` markers. No grounded profile.
+
+## Target profile
+- `Ecosystem`: `java`.
+- Variants: `maven` (`pom.xml`) and `gradle` (`build.gradle`/`.kts`,
+  `settings.gradle`), with Spring Boot recorded as a framework signal first
+  and promoted to its own variant once the adapter proves reliable.
+- Versions: JDK 17+ (from `maven.compiler.release` / Gradle toolchain block).
+
+## Detection signals (static only)
+- `pom.xml` parent/modules for Maven multi-module ownership.
+- `settings.gradle(.kts)` `include(...)` for Gradle subprojects — parsed
+  textually and conservatively; unresolvable dynamic includes → `NEEDS_INPUT`.
+- `src/main/java`, `src/test/java` for source/test roots; `@SpringBootApplication`
+  as an entry-point signal. Never execute Maven/Gradle.
+
+## Version evidence
+Maven: exact `<version>` pins in `pom.xml` (property-indirected versions
+resolved only when the property is a literal in the same reactor).
+Gradle: version catalogs (`gradle/libs.versions.toml`) and lockfiles
+(`gradle.lockfile`) when present; otherwise the dependency is unproven and
+API grounding for it must refuse.
+
+## Validation plan
+- Maven: `["mvn", "-B", "-q", "verify"]`. Gradle: `["./gradlew", "--no-daemon", "build"]`
+  only when the wrapper exists (wrapper jars are arbitrary code — sandbox only).
+- JDK image recorded by version; mismatch is `INCONCLUSIVE`.
+
+## Skill pack
+Package/directory correspondence; constructor injection over field injection
+(Spring); JUnit 5 conventions; no reflection-based config edits; generated
+sources under `target/`/`build/` are protected.
+
+## Risks & gates
+Annotation processors, Gradle build-script edits, `module-info.java`
+changes, and dependency additions are elevated-risk; build scripts are
+executable code and must never be model-editable.
+
+## Checklist
+1. `Ecosystem` union + `analysis/adapters/java.ts`.
+2. `java/maven`, `java/gradle` at `preview` in `support-matrix.ts`.
+3. Register adapter; Java/Spring skill pack.
+4. Adversarial tests: multi-module reactors, dynamic Gradle includes, version properties, wrapper absence, stable fingerprints.
+5. Docs updates (MODULES.md, README support matrix).

package/docs/roadmap/kotlin.md

@@ -0,0 +1,44 @@
+# Kotlin support plan
+
+## Status today
+Level 2 only: not in `LANGUAGE_PROFILES`; `.kt` not scanned for markers.
+
+## Target profile
+- `Ecosystem`: `kotlin` (JVM/Gradle first; Android later as its own variant
+  because of SDK/emulator validation constraints).
+- Variants: `gradle-jvm`, then `android` (deferred until a headless
+  validation story exists — unit tests only, no instrumented tests).
+- Versions: Kotlin ≥ 1.9 (from the Kotlin Gradle plugin version in the
+  version catalog or build script literals).
+
+## Detection signals (static only)
+- `build.gradle.kts` with `kotlin("jvm")`/`org.jetbrains.kotlin` plugin
+  (textual, conservative), `gradle/libs.versions.toml`,
+  `src/main/kotlin`, `src/test/kotlin`; `AndroidManifest.xml` marks the
+  android variant. Never execute Gradle.
+
+## Version evidence
+Version catalogs and `gradle.lockfile` when present; literal plugin/dependency
+versions otherwise. Dynamic version expressions leave deps unproven.
+
+## Validation plan
+- `["./gradlew", "--no-daemon", "test"]` (wrapper = arbitrary code, sandbox
+  only, deps preinstalled/cached offline). Android: `testDebugUnitTest` only.
+
+## Skill pack
+Null-safety idioms, data classes, coroutines conventions (structured
+concurrency, no `GlobalScope`), JUnit5/Kotest layout, `build/` and generated
+KSP/KAPT output protected.
+
+## Risks & gates
+KSP/KAPT processors, Gradle script edits, multiplatform targets, and JNI are
+elevated-risk. Shares most gates with the Java plan — build one Gradle
+inventory helper both adapters reuse (`analyzer-utils.ts` addition).
+
+## Checklist
+0. Add `kotlin` to `LANGUAGE_PROFILES` (`.kt`) and scan `.kt`/`.kts` for `// @human`.
+1. `Ecosystem` union + `analysis/adapters/kotlin.ts` (shared Gradle helpers with java.md's adapter).
+2. `kotlin/gradle-jvm` at `preview`; `kotlin/android` deferred and documented.
+3. Register adapter; Kotlin skill pack.
+4. Tests: catalog vs literal versions, multiplatform refusal, Android detection, stable fingerprints.
+5. Docs updates.

package/docs/roadmap/php.md

@@ -0,0 +1,42 @@
+# PHP support plan
+
+## Status today
+Level 2 only: not in `LANGUAGE_PROFILES` (direct path would fall back to a
+`.txt` profile) and `.php` is not scanned for markers.
+
+## Target profile
+- `Ecosystem`: `php`.
+- Variants: `composer-app`, `laravel` (artisan + `bootstrap/app.php`),
+  `symfony` later.
+- Versions: PHP ≥ 8.2 (from `composer.json` `require.php`).
+
+## Detection signals (static only)
+- `composer.json` (`require`, `autoload.psr-4`), `composer.lock`,
+  `artisan`, `routes/`, `app/Http/` for Laravel; `phpunit.xml(.dist)` for
+  tests. Never run composer or artisan.
+
+## Version evidence
+`composer.lock` `packages[].version` is exact; `composer.json` ranges alone
+leave dependencies unproven.
+
+## Validation plan
+- `["vendor/bin/phpunit"]`; `["vendor/bin/phpstan", "analyse"]` when
+  configured; `["php", "-l", "<changed files>"]` as a cheap syntax gate.
+  `vendor/` must be preinstalled in the image (no network).
+
+## Skill pack
+PSR-4 path↔namespace correspondence, PSR-12 style, Laravel conventions
+(form requests for validation, Eloquent scopes), `vendor/` and framework
+cache dirs protected.
+
+## Risks & gates
+Laravel migrations review-only; `eval`/dynamic includes opaque to import
+grounding; service-provider registration changes are elevated-risk.
+
+## Checklist
+0. Add `php` to `LANGUAGE_PROFILES` (`.php`) and `.php` to `SCANNED_EXTENSIONS` — direct-path quick win.
+1. `Ecosystem` union + `analysis/adapters/php.ts`.
+2. `php/composer-app`, `php/laravel` at `preview`.
+3. Register adapter; PHP/Laravel skill pack.
+4. Tests: missing lockfile, PSR-4 mismatches, Laravel vs plain-composer ambiguity, stable fingerprints.
+5. Docs updates.