# Codex instructions

## Authority and scope

- Start with `docs/spec/00_SPEC_INDEX.md`. The numbered files under `docs/spec/` are the
  complete active specification; `99_FULL_SPEC_ARCHIVE.md` is historical and is not in
  this repository.
- Required and Confirmed items are binding. Proposed, Deferred, Open, Optional, and
  Post-v1 items must not silently become implementation requirements.
- Before changing scope, architecture, compatibility, release timing, schemas, commands,
  or user-visible behavior, read `docs/spec/01_PROJECT_FOUNDATION.md` and
  `docs/spec/07_RISKS_DECISIONS_AND_HISTORY.md` and apply the cross-spec integrity rules.
- Ask the project owner when multiple plausible resolutions materially differ. Do not
  invent a decision merely to keep moving.

## Current state

- Phase 0 is complete. Phase 1 contracts are next.
- `Project Kiln`, `kiln`, and every `kiln-*` name are private placeholders. Do not publish,
  globally install, register, or expose them as stable compatibility promises.
- The workspace is private, AGPL-3.0-or-later, Rust 2024, MSRV 1.85, with the reviewed
  development toolchain pinned to Rust 1.97.1.
- No real provider implementation starts until the relevant Phase 1 contracts and mock
  adapter tests pass.

## Required workflow

1. Define one narrow task with exclusions, affected components, acceptance criteria, and
   exact verification commands.
2. Implement one vertical capability at a time. Do not spread incomplete work across
   providers or system layers.
3. Treat provider files, manifests, artwork, frontend descriptors, paths, and strings as
   hostile input. Never interpolate them into a shell command.
4. Keep ordinary discovery and launch unprivileged. Preserve per-user XDG state and do
   not hard-code usernames, UIDs, home directories, mounts, or the reference hardware.
5. Use exact versions for local path dependencies as well as their paths. Update and
   commit `Cargo.lock` for every dependency change.
6. Add dependency licenses only after review; do not broaden `deny.toml` speculatively.
7. Update ADRs, evidence, traceability, source inventory, changelog, and active spec files
   whenever a change materially affects them.

## Verification

Run before handing work back:

```sh
make verify
make audit
```

Also run focused tests for the changed capability. Do not report a gate as passed unless
it actually ran. Record blocked hardware/VM/provider checks explicitly for later local
execution rather than fabricating evidence.

## Repository map

- `crates/kiln-core/`: provider-independent contracts and logic
- `crates/kiln-cli/`: the single human and machine-facing CLI
- `docs/spec/`: active specification
- `docs/adr/`: architecture decisions
- `docs/phase-0/`: completed baseline policies and evidence
- `docs/handoff/`: bounded Codex CLI task briefs
- `scripts/`: repository, toolchain, licensing, and placeholder gates