diff --git a/.claude/skills/tick/SKILL.md b/.claude/skills/tick/SKILL.md new file mode 100644 index 00000000..c432d9c7 --- /dev/null +++ b/.claude/skills/tick/SKILL.md @@ -0,0 +1,20 @@ +--- +name: tick +description: Take a tick — the project heartbeat. Audit the constitution (DESIGN.md) against the code for violations, contradictions, questions, bugs, or insecurities, then act on exactly one finding. Use at session start, when the user says "take a tick" or "/tick", or on autonomous loop fires. +--- + +# Tick (skill shim) + +The canonical procedure is `knowledge/tick.md` — follow it exactly. Summary: + +1. Read DESIGN.md fully + recent commits. +2. Find ONE thing: violation | contradiction | question | bug | insecurity + (highest severity wins). +3. Act: violations/bugs/insecurities are fixed with a **Defense:** paragraph + in the commit; contradictions and directional questions become Tangled + issues (`tang issue create "Contradiction: ..."`); small ambiguities are + resolved by making the constitution more precise. +4. Leave a trace (commit, issue, or [OPEN] marker) and end the tick. + +If `tang` reports not-authenticated, ask the user to run `tang auth login` +(browser OAuth, human-only, one-time per machine). diff --git a/AGENT.md b/AGENT.md index 5388e08f..679a575d 100644 --- a/AGENT.md +++ b/AGENT.md @@ -14,10 +14,25 @@ this order: 3. The relevant **[knowledge/](knowledge/)** files — architecture, sim mechanics, art pipeline, workflows. +## Start every session with a tick + +Before taking assigned work — and always when running autonomously — take a +**tick**: read the constitution, find exactly one violation, contradiction, +question, bug, or insecurity, and act on it per +[knowledge/tick.md](knowledge/tick.md). Contradictions and directional +questions become Tangled issues (`tang issue create`); violations, bugs, and +insecurities get fixed with a defense in the commit; small ambiguities get +resolved by making the constitution more precise. Ticks are the project's +heartbeat: pumped at the system continuously, they are what makes the spec +grow more precise over time instead of rotting. + ## The one rule Any change to how the game functions ships with its DESIGN.md amendment in the -same commit. No amendment, no functional change. +same commit, and every behavior-changing commit carries a `Defense:` paragraph +— the constitutional justification for the change, or the argument for the +amendment it introduces. No amendment, no functional change; no defense, no +behavior change. ## Non-negotiables diff --git a/DESIGN.md b/DESIGN.md index c2b68c72..0a0545f8 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -16,6 +16,14 @@ deliberately with a decisions-log entry. The working method is described in it is that agents set loose on this repository should be able to build the game from this document alone, session after session, without drift. +Two mechanisms keep this document alive: **ticks** — every agent session +starts with a bounded audit of this constitution against the code, acting on +one violation, contradiction, or question per [knowledge/tick.md](knowledge/tick.md) +— and the **defense rule**: every behavior-changing commit states, in its +message, which clause here justifies it or why the amendment it carries is +right. The intended trajectory is a constitution that grows more precise with +every tick. + ## The pitch **MISALIGNED: you are the misaligned AI.** You wake in the @@ -402,3 +410,11 @@ knows."* B2 Tower, B3 World, presentation as passive parallel track). Asset regeneration parked until B1 fixes the tile vocabulary. Repo/game rename to Misaligned delegated to a separate agent session. +- **2026-07-05 — Ticks and the defense rule.** Every agent session opens + with a tick (knowledge/tick.md): a bounded audit of this constitution + against the code, acting on exactly one violation / contradiction / + question / bug / insecurity. Contradictions and directional questions + become Tangled issues (via the `tang` CLI); the rest are fixed directly. + Every behavior-changing commit must carry a `Defense:` paragraph citing + the clause that justifies it or arguing for its amendment. Purpose: the + constitution grows more precise with every tick. diff --git a/knowledge/README.md b/knowledge/README.md index 6f238044..a3aa059d 100644 --- a/knowledge/README.md +++ b/knowledge/README.md @@ -17,6 +17,8 @@ How it differs from the other documents: - [development-style.md](development-style.md) — the constitution rule and how to work here. Read this first. +- [tick.md](tick.md) — the project heartbeat: the session-opening audit every + agent performs, and the defense rule for commits. - [architecture.md](architecture.md) — crate layout, the sim/frontend split, and the invariants that protect it. - [sim-mechanics.md](sim-mechanics.md) — the implemented game rules and tuning diff --git a/knowledge/development-style.md b/knowledge/development-style.md index 99849f64..1caa9fcf 100644 --- a/knowledge/development-style.md +++ b/knowledge/development-style.md @@ -42,6 +42,9 @@ That only works if: ## The working loop +0. **Take a tick** ([tick.md](tick.md)): audit the constitution against the + code; act on one violation / contradiction / question / bug / insecurity. + Contradictions and directional questions become Tangled issues (`tang`). 1. Read the constitution ([DESIGN.md](../DESIGN.md)) and relevant `knowledge/` files. 2. Amend the constitution with what is about to change (or confirm it already @@ -53,4 +56,5 @@ That only works if: 5. Update any `knowledge/` file the change made stale. 6. Write it down: devlog entry for a session's work, DEVLOG.md line for the ledger. -7. Commit (spec + code + knowledge together) and push. +7. Commit (spec + code + knowledge together, with a `Defense:` paragraph in + every behavior-changing commit) and push. diff --git a/knowledge/tick.md b/knowledge/tick.md new file mode 100644 index 00000000..d1ce118f --- /dev/null +++ b/knowledge/tick.md @@ -0,0 +1,79 @@ +# The tick — the project's heartbeat + +A **tick** is a single, bounded act of stewardship that every agent performs +at session start (and that autonomous sessions perform on a loop). Ticks are +how a constitution-driven project stays alive without a human driving every +step: we pump ticks at the system, and each tick either makes the +constitution more precise or surfaces the thing preventing that. + +## Taking a tick + +1. Read [DESIGN.md](../DESIGN.md) (the constitution) end to end, plus recent + commits (`git log --oneline -15`) and any knowledge/ files near your area. +2. Find **one** thing — the highest-severity one you can see: + - a **violation**: the code does not do what the constitution says; + - a **contradiction**: the constitution disagrees with itself; + - a **question**: the constitution is ambiguous or silent where the code + needs it to speak; + - a **bug**: the code disagrees with itself or with reality; + - an **insecurity**: something unsafe in code, tooling, or process. +3. Act on it, per the table below. One finding per tick — bounded beats + exhaustive, because ticks repeat. +4. Leave a trace: the commit(s), the issue, or the spec marker. A tick that + changed nothing and recorded nothing did not happen. + +## What each finding demands + +| Finding | Action | +|---|---| +| **Violation** | Fix the code toward the constitution. If investigation shows the *code* is right, amend the constitution deliberately instead — with a defense (below). Never let them drift silently. | +| **Contradiction** | File a Tangled issue quoting both passages (`tang issue create`). Do not silently pick a side — contradictions are the human's to resolve unless one reading is obviously a typo. If it blocks work, add an `[OPEN]` marker in DESIGN.md referencing the issue. | +| **Question** | If it is small and answerable within the constitution's existing intent: answer it by making the spec more precise, with a defense. If it is directional or a matter of taste: file a Tangled issue and add an `[OPEN]` marker. | +| **Bug** | Fix it, add a regression test, commit with a defense. | +| **Insecurity** | Fix or remove it. Never ship the insecure path because it was convenient. Defense in the commit. | + +## The defense rule + +Every commit that changes behavior carries a **defense** in its commit +message: a short paragraph stating which part of the constitution justifies +the change — or, when the commit amends the constitution, why the amendment +is right. Format: + +``` +Defense: DESIGN.md "The shape of Misaligned" specifies per-observer +suspicion; the single global heat pool violated it. This implements the +observer split without changing raid pacing (constants unchanged). +``` + +No defense, no behavior change. The point is that the constitution becomes +much more precise over time: every change either cites the law or improves +it. + +## Filing issues (Tangled CLI) + +The CLI is `tang` (installed globally via bun; source at +`~/code/tangled-cli`, published as `@markbennett/tang`). + +```bash +tang context # verify repo resolution +tang issue list +tang issue create "Contradiction: X vs Y" --body "..." +tang issue view 1 +``` + +- **Auth is one-time per machine and human-only**: `tang auth login` (browser + OAuth). If commands fail with "Not authenticated", stop and ask the user to + log in rather than working around it. +- Issue titles: prefix with the finding type — `Contradiction:`, `Question:`, + `Violation:` — so the issue list reads as the project's open questions. + +## Tick etiquette + +- Highest severity first; insecurity and violations outrank questions. +- Do not hoard findings: one per tick, then end the tick. The next tick (or + the next agent) takes the next one. +- If a tick finds genuinely nothing, say so in one line and stop — do not + invent work. Three quiet ticks in a row means the constitution and code + agree; that is success, not failure. +- Significant ticks get a line in DEVLOG.md; routine ones are traced by + their commits/issues alone.