diff --git a/.noet/OPERATING.md b/.noet/OPERATING.md new file mode 100644 index 0000000..a253c51 --- /dev/null +++ b/.noet/OPERATING.md @@ -0,0 +1,78 @@ +# Noet Operating Contract + +This repository uses Noet as an agent-operated continuity and judgment layer. + +## Operating loop + +**1. The first action for any repository task is:** +``` +noet apply --task "" +``` +Run this **before** inspecting the repository, planning, or editing anything. +Consume the output before choosing a direction. Running `apply` after +implementation has begun does not satisfy this step. + +**2. Record judgment in the same diff as the work that creates it:** +- `noet record decision` — a project decision (with reason, current + consequence, reversal condition, and action when met) +- `noet record constraint` — a must or must-not +- `noet record failure` — a prior failure that constrains future work +- `noet record attention` — an unresolved obligation that must survive context + replacement +- `noet record continuity` — current goal, active direction, next action, + and open questions + +**3. Never manually edit Noet-managed JSON stores under `.noet/`.** +Use `noet record` commands. Hand-editing bypasses schema validation and will +cause subsequent Noet invocations to fail closed. + +**4. Before claiming completion:** +Run `noet verify run` (executes declared checks and records evidence), then +`noet verify check` (falsifies the completion claim; must exit 0). + +**5. Preserve continuity and judgment updates** in the same diff as the work +that creates them. Confirmed-judgment records remain candidate until the human +merges the PR; merging confirms them. Provisional working state (continuity, +attention) is adopted on merge but is not promoted to confirmed truth. + +**6. To run Noet commands,** use whichever of these is available: +- An installed Noet CLI (for example, from the repository's local bin path + via `npm exec -- noet`); or +- An attached Noet checkout — the Noet source in a separate directory that + you invoke by absolute path (see §7 below). + +If neither is available, treat all `.noet/` state as read-only. Report that +Noet cannot be safely operated. Do not hand-edit managed state. + +**7. Attached Noet checkout — explicit targeting required:** +The target repository (this project) and the Noet executable checkout are +two distinct directories. When using an attached Noet checkout, always: + +- Invoke the Noet CLI by its **absolute path** — never by changing into the + Noet checkout directory and running against ambient state. +- Pass the target repository explicitly with **`--cwd `** on + every command: `apply`, `record`, and `verify`. +- Use the same `--cwd` for all commands in a session. +- **Inspect the printed Noet target** before consuming applied judgment or + continuing. If the target shows the Noet checkout directory instead of + this repository, the output is irrelevant and must be discarded. + +Example (adapt paths; the Noet checkout and this repository will have +different names on your system): + + npx tsx /absolute/path/to/noet/src/cli.ts apply \ + --cwd /absolute/path/to/target \ + --task "describe the current task" + + npx tsx /absolute/path/to/noet/src/cli.ts record continuity \ + --cwd /absolute/path/to/target \ + --goal "..." + + npx tsx /absolute/path/to/noet/src/cli.ts verify run \ + --cwd /absolute/path/to/target + + npx tsx /absolute/path/to/noet/src/cli.ts verify check \ + --cwd /absolute/path/to/target + +The human does not need to sequence Noet commands during ordinary work. +The agent operates Noet; the human reviews work via PR. diff --git a/AGENTS.md b/AGENTS.md index b4df54e..6151b81 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -65,3 +65,14 @@ Owns all selection/follow state (`selectedSystemId`, `selectedEmpireId`, `select - **Save compatibility**: `Simulation.importSave()` calls `upgradeState()` to patch missing fields from older saves. When adding new fields to `GalaxyState`, `Empire`, `StarSystem`, or `Fleet`, also add a `??=` default in `upgradeState()` and bump `SAVE_VERSION` if the shape change is breaking. - **Event IDs**: Empire and system event arrays (`historicalEventIds`, `recentEventIds`) store `Id` references into `state.events`. The global `eventLog` array is the ordered log of all event IDs. - **React / canvas split**: React components must not be in the canvas RAF loop. The canvas component must not set React state on every frame. + + +The first action for any repository task is: + noet apply --task "" +Run this before inspecting the repository, planning, or editing. Consume the +output before choosing a direction. Running apply after implementation begins +does not satisfy this step. + +This repository uses Noet. Read `.noet/OPERATING.md` for the full operating loop. +Do not manually edit Noet-managed JSON files under `.noet/`. + diff --git a/CLAUDE.md b/CLAUDE.md index 24cb995..3d464e5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -86,3 +86,13 @@ Owns all selection/follow state (`selectedSystemId`, `selectedEmpireId`, `select - **Save compatibility**: `Simulation.importSave()` calls `upgradeState()` to patch missing fields from older saves. When adding new fields to `GalaxyState`, `Empire`, `StarSystem`, or `Fleet`, also add a `??=` default in `upgradeState()` and bump `SAVE_VERSION` if the shape change is breaking. - **Event IDs**: Empire and system event arrays (`historicalEventIds`, `recentEventIds`) store `Id` references into `state.events`. The global `eventLog` array is the ordered log of all event IDs. - **React / canvas split**: React components must not be in the canvas RAF loop. The canvas component must not set React state on every frame. + + +The first action for any repository task is: + noet apply --task "" +Run this before inspecting the repository, planning, or editing. Consume the +output before choosing a direction. Running apply after implementation begins +does not satisfy this step. + +@.noet/OPERATING.md +