65 lines
2.8 KiB
Markdown
65 lines
2.8 KiB
Markdown
# 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
|
|
|