diff --git a/AGENTS.md b/AGENTS.md index d0f3980..79033e4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,6 +33,16 @@ the agreement does not exist. Nothing here authorizes work the constitution forbids. When you cannot satisfy both a request and the constitution, say so rather than picking one silently. +## What you find on the way + +Record an inconsistency rather than widening the change or dropping it. Open an +issue on the repository the fix lands in, with the command that found it, and +carry on with what you were doing. [Issues](CONTRIBUTING.md#issues) has the +rule; the part agents get wrong is the widening. + +A page that disagrees with the code is the same situation. Say so and fix the +page in its own change, rather than writing around it. + ## Writing a page **Run `unslop` over anything you write.** It applies to prose here the way diff --git a/CONSTITUTION.md b/CONSTITUTION.md index 6b68978..8de7398 100644 --- a/CONSTITUTION.md +++ b/CONSTITUTION.md @@ -101,17 +101,21 @@ long as nobody measures. ## Tracking -An issue records that something should change. A specification records what -changing it means, and a task list records the order it is built in. These are -stages of one piece of work, not three records of it: an issue is closed by the -pull request that implements the specification it became, and a task is never -mirrored into an issue. A copy of a task list is a second list that drifts from -the first. +An issue records that something should change. The page records what changing it +means. These are stages of one piece of work rather than two records of it, and +an issue is closed by the pull request that makes its page true. An issue exists so an intent survives being put down. Work under way is tracked -by its task list, which is authoritative while it runs; copying it into issues -produces a second list that drifts from the first and is read by whoever finds -it first. +wherever it is being done, and copying that into issues produces a second list +that drifts from the first and is read by whoever finds it first. + +Open one when the work is larger than the change in hand, and fix it directly +when it is not. An inconsistency found while doing something else is the case +this rule is for: widening the change buries the fix in a diff about something +unrelated, and saying nothing loses it. Neither is tracking. + +An issue carries the evidence that found it, with the command that reproduces +it, for the same reason a page does. An issue is opened in the repository the change lands in, never in the design record, because that is where the reader of the code looks. Work spanning the diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c3194c..5d5943e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,6 +26,27 @@ or an agreement two of them must both keep. Job retry logic is osapi's behaviour. The subject naming that osapi and osapi-orchestrator both depend on belongs to neither, so it goes in `ARCHITECTURE.md`. +## Issues + +The rule is [Tracking](CONSTITUTION.md#tracking). In practice: + +An issue is opened in the repository the change lands in. A finding about +osapi's code is an osapi issue, not one here, because that is where the person +who fixes it is looking. An issue here is for the design record itself: a page +that is wrong, a subject with no page, a rule stated in two places. + +Open one when the work is larger than the change in hand. A one-line fix found +while editing a page is part of that change. A provider that decides idempotency +the wrong way is not, and widening the change to cover it buries the fix in a +diff about something else. + +Carry the evidence. The counts and commands that found it belong in the issue +for the same reason they belong in a page: a reader who cannot reproduce it has +to take your word for it, and in six months so do you. + +Something exploitable is never an issue, because an issue is public the moment +it is opened. It is a draft advisory on the repository it affects. + ## Prerequisites ```bash