chore: establish phase 0 baseline

2026-07-18 18:20:34 -04:00
commit b38da7d53f
42 changed files with 2618 additions and 0 deletions
@@ -0,0 +1,23 @@
+# Phase 0 exit checklist
+
+| Exit criterion | Evidence | State |
+| --- | --- | --- |
+| Rust workspace and component boundaries | root and crate manifests; ADR 0001 | Passed |
+| Temporary naming and rename path | rename manifest; placeholder scanner | Passed for private development |
+| Toolchain and lockfile | Rust 1.97.1 checker; desktop evidence; committed lockfile | Passed |
+| Formatting, linting, tests | `make verify`; desktop evidence | Passed |
+| CI | pinned workflow invoking `make verify` and `make audit` | Configured; first hosted run pending |
+| Dependency/license/security audits | workspace auditor; `deny.toml`; cargo-deny 0.20.2 | Passed |
+| Release/version policy | release policy and changelog | Passed |
+| ADRs | `docs/adr/` | Passed |
+| Fixture rules | fixture policy | Passed |
+| Threat model | initial threat model | Passed |
+| Package/source inventory | schema-versioned TOML inventory | Passed for current components |
+| Test evidence format | template plus desktop evidence | Passed |
+| Requirement traceability | 29 IDs mapped to phases and evidence classes | Passed structurally |
+| Supported-platform decision | supported-platform record | Passed |
+| Canonical project license | root GNU AGPL v3 text; hash checked | Passed |
+
+Phase 0 is closed. The first hosted CI run is operational evidence rather than a blocker
+to beginning private Phase 1 contract design, but it must pass before accepting external
+changes or treating CI as enforced.
@@ -0,0 +1,66 @@
+# Test evidence: Work Mode baseline
+
+- Date/time (UTC): 2026-07-18
+- Repository revision: uncommitted initial scaffold
+- Requirement IDs: R-001 through R-029 (structural traceability only)
+- Phase/gate: phase 0 / lightweight static baseline
+- Runtime: ChatGPT Work Mode container; Python 3.12; Git 2.51.1
+- Exact commands: `make static`, `python3 -m py_compile scripts/verify_repo.py`, `git diff --check`
+- Expected result: manifests/spec parse, identifiers are unique, every requirement is traced,
+  temporary naming is recorded, Python verifier compiles, and whitespace checks pass
+- Observed result: `PASS: Phase 0 static baseline (29 requirements traced)`; remaining checks passed silently
+- Logs/artifacts: none required; command output contains no credentials or personal provider data
+- Cleanup performed: generated Python bytecode ignored; no provider or user state accessed
+- Result: pass, with Rust compilation explicitly blocked because Rust is unavailable here
+
+## First desktop attempt
+
+The first local run correctly exposed two scaffold defects before compilation: source
+files were not in canonical Rustfmt form, and the workspace treated the 1.97.1 toolchain
+pin as its minimum supported compiler. The source was formatted and the MSRV was corrected
+to Rust 1.85 (the Edition 2024 baseline) while retaining 1.97.1 as the exact development
+and CI toolchain pin.
+
+The corrected workspace then passed Rustfmt, `cargo check`, all three core unit tests,
+Clippy with `-D warnings`, `kiln doctor`, and JSON doctor output on the user's
+EndeavourOS desktop. The output revealed that the active distro compiler was Rust 1.97.0,
+not the declared 1.97.1 pin. The result is retained as valid functional evidence, but it
+does not complete the reproducible-toolchain gate. `make verify` now checks the active
+compiler version before running Rust quality gates.
+
+## Final desktop rerun
+
+- Platform: EndeavourOS / Arch Linux package `rust 1:1.97.1-1`
+- Compiler: `rustc 1.97.1 (8bab26f4f 2026-07-14)`
+- Commands: `make verify`; preceding corrected run also executed both `kiln doctor` forms
+- Result: static baseline passed; exact compiler pin passed; Rustfmt passed; workspace and
+  all-target check passed; three of three core unit tests passed; Clippy passed with
+  warnings denied; doctor returned schema 1 and JSON status `ok`
+- Gate status: passed
+
+## Completed repository-policy baseline
+
+The subsequent Phase 0 audit added and verified the canonical 34,523-byte GNU AGPL v3
+license text, release/version policy, changelog, fixture policy, security-reporting
+policy, cargo-deny configuration, pinned audit-tool inventory, real placeholder scan,
+workspace/license/source audit, and local Markdown-link validation. The dependency-free
+workspace contains no external packages in `Cargo.lock`. `make static` passes all three
+dependency-free audit programs. The network-backed `make audit` gate remains pending.
+
+The first cargo-deny 0.20.2 execution rejected the local `kiln-core` path dependency as
+wildcarded because it lacked a version constraint. It also reported unused allowances in
+the speculative broad license list. The internal dependency now requires exact version
+`=0.0.1` while retaining its workspace path, and the license allowlist now contains only
+AGPL-3.0-or-later. Future dependency licenses require an explicit reviewed addition. A
+fresh `make verify` and `make audit` result is required.
+
+## Final Phase 0 audit rerun
+
+- Commands: `make verify`; `make audit`
+- Static baseline: passed, 29 requirement IDs traced
+- Workspace/license/source audit: passed
+- Temporary-name scan: passed, 29 private occurrences inventoried
+- Compiler: exact Rust 1.97.1 pin passed
+- Rustfmt, workspace/all-target check, three unit tests, and Clippy `-D warnings`: passed
+- cargo-deny 0.20.2: advisories, bans, licenses, and sources all passed
+- Phase 0 result: complete
@@ -0,0 +1,26 @@
+# Fixture policy
+
+## Allowed
+
+- Small, synthetic, deterministic files created specifically for tests.
+- Sanitized fragments whose provenance and redistribution permission are recorded.
+- Malformed, missing-field, duplicate, moved, unmounted, unusual-path, invalid-encoding,
+  oversized-boundary, symlink, traversal, and shell-metacharacter cases.
+- Temporary integration state created under a test-owned directory and removed afterward.
+
+## Forbidden
+
+- Live tokens, cookies, account identifiers, device identifiers, personal paths, save
+  files, complete personal libraries, crash dumps with private data, or proprietary
+  launcher databases copied wholesale.
+- Network access in unit or contract tests.
+- Fixtures whose expected result depends on the developer's username, UID, home path,
+  locale, clock, network, mount layout, or installed games.
+
+## Review and storage
+
+Every fixture directory contains a README stating its origin, license/permission,
+sanitization, parser behavior being tested, and whether it may be redistributed. Binary
+fixtures require a size justification and checksum. Secrets scanners and adversarial
+tests treat fixtures as hostile input, not trusted code or shell text.
+
@@ -0,0 +1,30 @@
+# Release and version policy
+
+## Private development
+
+- Workspace packages share one `0.0.x` version while contracts are private.
+- Every user-visible or contract-affecting change is recorded under `Unreleased`.
+- Machine-readable contracts carry their own positive integer schema version.
+- Breaking schema changes increment that schema version and include rejection tests for
+  unsupported versions; consumers never guess.
+- Temporary Kiln identifiers are never published, globally installed, or treated as
+  compatibility promises.
+
+## Public releases
+
+- Select and collision-check the final related naming system before the first public
+  package, crate, executable, configuration namespace, or IPC endpoint.
+- Use Semantic Versioning for project packages; pre-1.0 compatibility remains explicit
+  rather than implied stable.
+- A release derives from an annotated signed tag and clean repository state.
+- Release records include source revision, toolchain, lockfile, package/source inventory,
+  hashes, SBOM, signatures, license notices, supported-platform matrix, and test evidence.
+- Bit-for-bit reproducibility is claimed only after independent reproduction.
+- No release resolves live AUR state or downloads unpinned executable installer plugins.
+
+## Version ownership
+
+The workspace version is changed once at the root and inherited by every project crate.
+Provider protocol/schema versions remain independent when their compatibility boundaries
+require it. Release tooling must reject mismatched workspace package versions.
+
@@ -0,0 +1,15 @@
+# Temporary-name manifest
+
+All entries are private placeholders and must be replaced before publishing,
+packaging, or global installation.
+
+| Placeholder | Current use | Replacement gate |
+| --- | --- | --- |
+| `Project Kiln` | prose-only project codename | final related naming system approved |
+| `kiln` | repository-local binary target and examples | executable collision screen complete |
+| `kiln-*` | workspace package/component family | package and crate collision screen complete |
+| `KILN_*` | reserved future environment prefix; not yet used | environment/config namespace approved |
+
+The static verifier scans structure and requires this manifest. A later release gate
+must scan filenames and file contents for every placeholder and fail on remnants.
+
@@ -0,0 +1,21 @@
+schema_version = 1
+
+[[components]]
+name = "rust"
+kind = "toolchain"
+source = "https://static.rust-lang.org"
+version = "1.97.1"
+license = "Apache-2.0 OR MIT"
+owner = "project maintainers"
+update_policy = "explicit pull request after release and security review"
+release_profile = false
+
+[[components]]
+name = "cargo-deny"
+kind = "development-audit-tool"
+source = "https://crates.io/crates/cargo-deny"
+version = "0.20.2"
+license = "Apache-2.0 OR MIT"
+owner = "project maintainers"
+update_policy = "explicit pull request after release, changelog, and config review"
+release_profile = false
@@ -0,0 +1,43 @@
+# Phase 0 status — complete
+
+## Verified in Work Mode
+
+- Active numbered specification imported; archive intentionally excluded.
+- Workspace manifests and pinned-toolchain configuration parse successfully.
+- All 29 requirement IDs are unique and represented in the traceability matrix.
+- Decision IDs are unique; active spec version marker is `0.16`.
+- Temporary naming is documented and structurally constrained.
+- Python verifier compiles and the repository has no whitespace errors.
+
+## Local execution result — passed
+
+The initial desktop execution exposed and corrected formatting and toolchain-enforcement
+defects. The final execution passed under Arch Linux Rust 1.97.1:
+
+- static repository/specification verification;
+- exact-toolchain verification;
+- Rustfmt;
+- workspace and all-target compilation;
+- all three core unit tests;
+- Clippy for the workspace and all targets with warnings denied;
+- human and JSON `kiln doctor` smoke paths (verified in the preceding run).
+
+Reproduce the gate with:
+
+```sh
+make verify
+cargo run --locked -p kiln-cli -- doctor
+cargo run --locked -p kiln-cli -- doctor --json | jq -e \
+  '.schema_version == 1 and .status == "ok" and .private_placeholder == true'
+```
+
+The exact-toolchain gate, canonical AGPL license, dependency-free static audits, and
+cargo-deny 0.20.2 advisory/bans/licenses/sources audit all pass. Phase 0 is closed.
+A first hosted CI run remains required before accepting external changes or claiming
+enforced CI, but does not block private Phase 1 contract design.
+
+`rust-version = "1.85"` records the minimum supported compiler for Edition 2024. The
+exact reviewed development and CI toolchain remains pinned separately to Rust 1.97.1 in
+`rust-toolchain.toml`; these controls must not be conflated. `make verify` explicitly
+checks the active `rustc` version because distro-provided Rust binaries may ignore the
+Rustup override file.
@@ -0,0 +1,10 @@
+# Supported-platform decision record
+
+Version 1 targets x86_64 UEFI and one local gaming user. AMD and NVIDIA are
+release-blocking GPU families; Intel remains best-effort until representative coverage
+exists. The initial bare-metal reference is Ryzen 9 7900X3D plus RTX 5070 installed to
+a dedicated external USB drive. Xbox-family and PlayStation-family controllers require
+USB and Bluetooth coverage; exact revisions are recorded before phase 6 execution.
+
+Legacy BIOS, non-x86 architectures, and multi-user isolation are outside v1.
+
@@ -0,0 +1,16 @@
+# Test evidence
+
+- Date/time (UTC):
+- Repository revision:
+- Requirement IDs:
+- Phase/gate:
+- Hardware, firmware, kernel, driver:
+- Package/tool versions:
+- Fixture or dedicated test account:
+- Exact commands:
+- Expected result:
+- Observed result:
+- Logs/artifacts (sanitized):
+- Cleanup performed:
+- Result: pass / fail / blocked
+
@@ -0,0 +1,17 @@
+# Initial threat model
+
+## Assets and boundaries
+
+- Provider manifests, custom launch definitions, artwork, and frontend descriptors are untrusted.
+- Discovery and launch parsing run as the gaming user, never root.
+- Provider credentials remain owned by their provider/configuration owner.
+- Project state is per-user under XDG paths and must use atomic replacement.
+- Future IPC is local, owner-only, size-limited, authenticated by OS credentials, and optional.
+
+## Mandatory controls before provider work
+
+Use argument arrays rather than interpolated shells; reject traversal, control
+characters, oversized inputs, unsafe symlinks, and unexpected encodings; redact tokens
+and personal paths from evidence; constrain reads to documented roots; and keep fixtures
+free of proprietary library dumps and live credentials.
+
@@ -0,0 +1,31 @@
+requirement_id,owner_phase,initial_evidence,status
+R-001,10,package reconstruction record,planned
+R-002,8,session acceptance test,planned
+R-003,9,performance benchmark record,planned
+R-004,6,controller compatibility matrix,planned
+R-005,7,provider contract and acceptance tests,planned
+R-006,2,CLI integration tests,planned
+R-007,8,gaming-tool integration tests,planned
+R-008,8,session lifecycle acceptance test,planned
+R-009,1,core contract tests,planned
+R-010,5,TTY recovery acceptance test,planned
+R-011,0,development workflow record,active
+R-012,1,shared-backend architecture tests,planned
+R-013,8,profile policy acceptance tests,planned
+R-014,12,Pegasus adapter tests,post-v1
+R-015,8,Lean and Ready policy tests,planned
+R-016,7,adapter capability contract tests,planned
+R-017,8,window-switching acceptance tests,planned
+R-018,4,lifecycle confidence tests,planned
+R-019,15,vendor launcher tests,post-v1
+R-020,6,Bluetooth CLI and TUI tests,planned
+R-021,11,installer destructive VM tests,planned
+R-022,10,optional recovery profile tests,optional
+R-023,14,OpenGamepadUI evaluation,post-v1
+R-024,1,adversarial contract tests,planned
+R-025,0,source inventory and release review,active
+R-026,0,supported-platform record,active
+R-027,0,path and identity architecture review,active
+R-028,8,release GPU matrix,planned
+R-029,1,TOML and JSON contract tests,planned
+